gherkin-authoring

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>"

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)

Tags

Organize and filter scenarios with tags:

@smoke @authentication Feature: User Login

@happy-path Scenario: Successful login ...

@security @negative Scenario: Account lockout after failed attempts ...

Common Tag Categories

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&#x3C;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&#x3C;LoginResult>("loginResult");
    result.Success.Should().BeTrue();
}

}

Project Setup

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:

Single behavior per scenario
Declarative, not imperative
Uses domain language
Given establishes context only
When contains single action
Then asserts observable outcomes
No implementation details
Scenario name describes behavior

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

Version History

v1.0.0 (2025-12-26): Initial release

gherkin-authoring

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

design-thinking

plantuml-syntax

system-prompt-engineering