---

Good Gherkin Guidelines

Here are some guidelines started by the team to help you write better FeatureFiles using GherkinLanguage.

Keep Scenarios Simple, Short, and Human-Readable (StanVogel)

The purpose of GherkinLanguage is to make success criteria clear for everyone. If you read it and it doesn't make sense, it's not good Gherkin.

Be Specific (KyleRoth)

If two pages or applications use a similar step, including more detail to describe the page or application you’re looking at may be helpful to ensure the correct code is called. For instance, instead of "When Click the save button", write "When Click the Admin save button".

One Scenario Should Test One Behavior (NicoleRadziwill)

A When-Then pair describes a behavior. When the test based on that behavior fails, it should provide a clear signal to SoftwareEngineers regarding what functionality is broken. It is difficult to clearly provide this information when multiple behaviors are embedded within a scenario.

If you have a good reason for including multiple When-Then pairs in your Scenario (for example, if the sequence of steps is needed to test a single concept) then be sure to include a brief comment explaining why you made this choice. This will help future readers of the FeatureFile understand your decision.

Use Keywords Appropriately (KyleRoth)

• A Given statement should contain only preconditions.
• A When statement should contain only actions to be taken.
• A Then statement should only contain conditions and outcomes to be verified in the test.
• Double check that the assertions match the Scenario description. For example, Scenario: Verify Login should contain a Then statement with a condition that indicates the login has been successful.

Make your FeatureFile More Readable Using And and But Keywords (LeslieReis)

Although you could write your FeatureFile with only Given, When, and Then keywords, it is easier to read when you use supplement it with And and But. For more complex scenarios, instead of having several Then statements verifying things at the end it can be easier to read "Then Verify text is on screen And Verify error message does not appear", versus using Then for both statements.

Here's an example from https://programsbuzz.com/article/how-use-and-and-keyword-cucumber-scenario.

Use Indentation

Notice that you could make the example above even more readable by indenting the And and But lines.

Use Parameterization (StanVogel)

If you would be performing the same test Scenarios for two or more Example values, use Scenario Outline. Remember, a properly-annotated GlueCode method will properly map to the correct words in a non-parameterized Gherkin statement for a single iteration of the Scenario.

Use Tags (LeslieReis)

Prior to the Scenario or Scenario Outline keywords, use GherkinTags (that start with the @

symbol) to declare metadata about that Scenario. Tags can be used to:

• Group test types (e.g. Regression, EndToEnd) so that they can be run conditionally
• Provide information about the requirement or user story that the scenario has been written to verify

-- NicoleRadziwill - 13 Apr 2020