Gherkin Authoring

Gherkin/BDD acceptance criteria authoring for executable specifications.

When to Use This Skill

Keywords: Gherkin, Given/When/Then, BDD, behavior-driven development, feature files, scenarios, acceptance criteria, Reqnroll, Cucumber, SpecFlow, executable specifications

Use this skill when:

Writing acceptance criteria in Given/When/Then format
Creating .feature files for BDD testing
Converting requirements to executable specifications
Setting up Reqnroll tests in .NET projects
Understanding Gherkin syntax and best practices

Quick Syntax Reference

Feature File Structure

Feature: <Feature Name>
  <Feature description>

  Background:
    Given <common precondition>

  Scenario: <Scenario Name>
    Given <precondition>
    When <action>
    Then <expected outcome>

  Scenario Outline: <Parameterized Scenario>
    Given <precondition with <parameter>>
    When <action with <parameter>>
    Then <expected outcome with <parameter>>

    Examples:
      | parameter |
      | value1    |
      | value2    |

Step Keywords

Keyword	Purpose	Example
`Given`	Setup preconditions	Given a user is logged in
`When`	Describe action	When the user clicks submit
`Then`	Assert outcome	Then the form is saved
`And`	Additional step (same type)	And an email is sent
`But`	Negative condition	But no error is shown

Writing Effective Scenarios

The Three A's Pattern

Gherkin maps to the Arrange-Act-Assert pattern:

Gherkin	AAA	Purpose
Given	Arrange	Set up the test context
When	Act	Perform the action under test
Then	Assert	Verify the expected outcome

Single Behavior Per Scenario

Good - One behavior:

Scenario: User login with valid credentials
  Given a registered user exists
  When the user enters valid credentials
  Then the user is logged in

Bad - Multiple behaviors:

Scenario: User login and profile update
  Given a registered user exists
  When the user enters valid credentials
  Then the user is logged in
  When the user updates their profile
  Then the profile is saved

Declarative vs Imperative Style

Declarative (Preferred) - What, not how:

Scenario: Successful checkout
  Given a customer with items in cart
  When the customer completes checkout
  Then the order is confirmed

Imperative (Avoid) - Too detailed:

Scenario: Successful checkout
  Given a customer is on the home page
  And the customer clicks "Products"
  And the customer clicks "Add to Cart" on item 1
  And the customer clicks "Cart" icon
  And the customer clicks "Checkout" button
  ...

Background Section

Use Background for common setup shared across all scenarios in a feature:

Feature: Shopping Cart

  Background:
    Given a customer is logged in
    And the product catalog is available

  Scenario: Add item to cart
    When the customer adds a product to cart
    Then the cart contains 1 item

  Scenario: Remove item from cart
    Given the cart contains a product
    When the customer removes the product
    Then the cart is empty

Background Guidelines

Keep Background short (1-3 steps)
Only include truly common setup
Don't include anything not needed by ALL scenarios
Consider splitting features if Background grows large

Scenario Outline

Use Scenario Outline for parameterized tests:

Scenario Outline: Validate email format
  Given a user registration form
  When the user enters email "<email>"
  Then the validation result is "<result>"

  Examples:
    | email              | result  |
    | user@example.com   | valid   |
    | invalid-email      | invalid |
    | @missing-local.com | invalid |
    | user@             | invalid |

When to Use Scenario Outline

Use for:

Testing same logic with different data
Boundary testing
Error message variations
Multiple valid/invalid inputs

Avoid when:

Scenarios have fundamentally different flows
Setup differs significantly between examples
Only 1-2 examples (use separate scenarios)

Category	Examples
Priority	@critical, @high, @medium, @low
Type	@smoke, @regression, @e2e
Feature	@authentication, @checkout, @search
State	@wip, @pending, @manual
Non-functional	@security, @performance, @accessibility

Integration with Canonical Spec

Gherkin acceptance criteria map to canonical specification:

requirements:
  - id: "REQ-001"
    text: "WHEN a user submits valid credentials, the system SHALL authenticate the user"
    priority: must
    ears_type: event-driven
    acceptance_criteria:
      - id: "AC-001"
        given: "a registered user with valid credentials"
        when: "the user submits the login form"
        then: "the user is authenticated"
        and:
          - "a session is created"
          - "the user is redirected to dashboard"

Mapping Rules

Canonical Field	Gherkin Element
`acceptance_criteria.given`	Given step(s)
`acceptance_criteria.when`	When step(s)
`acceptance_criteria.then`	Then step(s)
`acceptance_criteria.and`	Additional And/But steps

Best Practices

Scenario Naming

Good:

Describes the behavior being tested
Uses domain language
Specifies the outcome

Scenario: User receives confirmation email after registration
Scenario: Cart total updates when quantity changes
Scenario: Search returns relevant results sorted by relevance

Bad:

Generic or vague
Implementation-focused
Missing outcome

Scenario: Test registration
Scenario: Click add button
Scenario: Verify database

Step Reusability

Write steps that can be reused:

Reusable:

Given a user with role "<role>"
Given the user has "<count>" items in cart
When the user performs "<action>"

Not Reusable:

Given John Smith is logged in as admin
Given the user has 3 items in cart for checkout test
When the user clicks the blue submit button

Avoid Coupling to UI

Good - Behavior-focused:

When the user submits the form with invalid data
Then an error message is displayed

Bad - UI-coupled:

When the user clicks the red Submit button at the bottom
Then a red error div appears below the form

Reqnroll Integration (.NET)

Step Definition Example

[Binding]
public class LoginSteps
{
    private readonly ScenarioContext _context;

    public LoginSteps(ScenarioContext context)
    {
        _context = context;
    }

    [Given(@"a registered user exists")]
    public void GivenARegisteredUserExists()
    {
        var user = new User("test@example.com", "password123");
        _context["user"] = user;
    }

    [When(@"the user enters valid credentials")]
    public void WhenTheUserEntersValidCredentials()
    {
        var user = _context.Get<User>("user");
        var result = _authService.Login(user.Email, user.Password);
        _context["loginResult"] = result;
    }

    [Then(@"the user is logged in")]
    public void ThenTheUserIsLoggedIn()
    {
        var result = _context.Get<LoginResult>("loginResult");
        result.Success.Should().BeTrue();
    }
}

Project Setup

<PackageReference Include="Reqnroll" Version="2.*" />
<PackageReference Include="Reqnroll.NUnit" Version="2.*" />

Anti-Patterns to Avoid

Anti-Pattern	Problem	Fix
Feature-length scenarios	Hard to maintain	Split into focused scenarios
Imperative steps	Brittle, verbose	Use declarative style
Technical jargon	Not business-readable	Use domain language
Coupled to UI	Breaks on UI changes	Focus on behavior
No Background	Duplicated Given steps	Extract common setup
Too many Examples	Slow, redundant	Test boundary cases only

Validation Checklist

Before finalizing a Gherkin scenario:

References

Detailed Documentation:

Syntax Reference - Complete Gherkin syntax
Best Practices - BDD best practices

Related Skills:

canonical-spec-format - Canonical specification structure
spec-management - Specification workflow navigation
ears-authoring - EARS requirement patterns

Last Updated: 2025-12-24

gherkin-authoring