By David Kidd
7/15/2022

Gherkin-style acceptance criteria are most effective when they are clear, actionable, and collaborative. However, writing them well takes practice and attention to detail. Below is an in-depth guide to writing effective Gherkin scenarios, including tips on when and how to split stories for better clarity and manageability.

1. Focus on One Behavior Per Scenario

Each Gherkin scenario should test one specific behavior or outcome. If you find a scenario growing too complex, it’s likely trying to do too much.

Why It’s Important:

• Ensures clarity for both the development and testing teams.
• Makes debugging easier when scenarios fail.
• Reduces the risk of overlooking edge cases.

Example:

Instead of writing one scenario to cover logging in, resetting a password, and handling invalid credentials, split it into:

• Successful login
• Password reset
• Handling invalid login credentials

2. Write in Simple, Plain Language

The goal of Gherkin is to bridge the gap between technical and non-technical stakeholders. Avoid using technical jargon or overly complex phrasing.

Best Practices:

• Use language that mirrors how users talk about the feature.
• Avoid implementation details (e.g., database queries, APIs).

Example:

Instead of:

“Given the API returns a 200 status code...”

Use:

“Given the user enters valid credentials…”

3. Collaborate Early and Often

Writing Gherkin scenarios should be a collaborative effort involving:

• Product Owners: To ensure the criteria meet business needs.
• Developers: To confirm technical feasibility.
• Testers: To ensure testability and identify edge cases.

Tips:

• Use Three Amigos sessions (Product, Development, Testing) to collaboratively define scenarios.
• Iterate on scenarios during sprint planning or backlog refinement.

4. Prioritize Testability

Scenarios should be specific enough to allow for automated testing. Each step in the Given-When-Then structure should describe an action or result that can be objectively verified.

How to Ensure Testability:

• Avoid vague terms like “appropriate message” or “reasonable speed.”
• Clearly define expected outcomes, including exact error messages or UI behaviors.

5. Use Consistent Language

Maintain uniformity in how you describe actions and outcomes. This reduces confusion and ensures the scenarios are easier to read and automate.

Tips for Consistency:

• Standardize terms for common actions (e.g., “user clicks,” “system displays”).
• Create a glossary of terms if your project has domain-specific language.

6. Include Both Positive and Negative Scenarios

It’s essential to capture both the "happy path" and edge cases where things don’t go as expected. This ensures robustness in the application and better user experience.

Examples:

• Positive Scenario: A user logs in successfully with valid credentials.
• Negative Scenario: A user enters invalid credentials and sees an error message.

7. Keep Scenarios Independent

Each scenario should stand alone, with no dependencies on the results of other scenarios. This ensures that tests can be executed in any order and remain reliable.

Example:

If testing login functionality, do not assume a user is already logged out. Explicitly state the precondition:

“Given the user is not logged in…”

8. Know When to Split Stories

Large, complex user stories can result in bloated Gherkin scenarios that are difficult to manage. Split stories when:

• The story includes multiple independent behaviors (e.g., login, password reset).
• Scenarios require different actors or roles (e.g., admin vs. standard user).
• There are multiple acceptance criteria addressing unrelated functionalities.
• Testing becomes unwieldy due to too many edge cases.

Examples of Splitting:

Example 1:  Too many items for the story
Original Story: "As a user, I want to manage my account, including logging in, changing my password, and updating my profile."

• Split into:
  1. Login Story: "As a user, I want to log in to my account so I can access my profile."
  2. Password Change Story: "As a user, I want to change my password to ensure account security."
  3. Profile Update Story: "As a user, I want to update my profile to keep my information current.

Example 2: When you see "OR" in the "When" statement of your Acceptance Criteria
Whenever you see the word "or" in the When statement of your Acceptance Criteria.  This is a good indication you need a second story.  

9. Handle Variations with Parameterized Scenarios

When the same behavior applies to multiple conditions, use parameterization to avoid duplicating scenarios.

Example:

Instead of writing separate scenarios for each type of invalid input:

• Parameterize the invalid inputs (e.g., empty field, incorrect password format).

Format:

• “Given the user enters <invalid_input>…”

10. Avoid Overloading Scenarios with UI Details

While Gherkin can describe user interactions, avoid excessive focus on UI specifics that may change frequently.

Better Practice:

• Focus on the intent (e.g., “User selects an item”) rather than implementation (e.g., “User clicks the blue button”).

11. Validate Scenarios Against the Definition of Done

Scenarios should align with your team’s Definition of Done (DoD) to ensure that the story is complete when all criteria are met.

Checklist for Validation:

• Does each scenario fully describe expected behavior?
• Are all edge cases accounted for?
• Are scenarios written in a way that stakeholders understand?

12. Use Examples to Drive Clarity

Include concrete examples where possible to eliminate ambiguity. This is particularly useful for scenarios involving calculations, filters, or complex conditions.

Example:

Instead of:

“Given the user filters by date…”

Use:

“Given the user filters by date ‘01/01/2024 to 01/07/2024’…”

13. Review and Refactor Regularly

Gherkin scenarios are living documents that should evolve with the product. Periodically review them to ensure they remain relevant, concise, and effective.

Tips:

• Remove obsolete scenarios as features change.
• Refactor overly complex scenarios into smaller, clearer ones.
• Regularly involve stakeholders in scenario reviews.

Conclusion

Writing effective Gherkin-style acceptance criteria requires a balance of clarity, collaboration, and focus. By keeping scenarios user-centric, testable, and independent, and knowing when to split complex stories, teams can ensure alignment and deliver software that meets expectations. Regular reviews and adherence to best practices help maintain the quality and relevance of Gherkin criteria throughout the project lifecycle.