Gherkin acceptance criteria authoring. Use when writing Given/When/Then scenarios, feature files, or BDD-style specifications. Provides syntax reference, best practices, and Reqnroll integration guidance.
Provides Gherkin/BDD syntax guidance for writing Given/When/Then scenarios and feature files. Use when creating acceptance criteria, converting requirements to executable specifications, or setting up Reqnroll tests.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install spec-driven-development@melodic-softwareThis skill is limited to using the following tools:
references/best-practices.mdreferences/syntax-reference.mdGherkin/BDD acceptance criteria authoring for executable specifications.
Keywords: Gherkin, Given/When/Then, BDD, behavior-driven development, feature files, scenarios, acceptance criteria, Reqnroll, Cucumber, SpecFlow, executable specifications
Use this skill when:
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 |
| 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 |
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 |
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 (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
...
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
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 |
Use for:
Avoid when:
Organize and filter scenarios with tags:
@smoke @authentication
Feature: User Login
@happy-path
Scenario: Successful login
...
@security @negative
Scenario: Account lockout after failed attempts
...
| Category | Examples |
|---|---|
| Priority | @critical, @high, @medium, @low |
| Type | @smoke, @regression, @e2e |
| Feature | @authentication, @checkout, @search |
| State | @wip, @pending, @manual |
| Non-functional | @security, @performance, @accessibility |
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"
| 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 |
Good:
Scenario: User receives confirmation email after registration
Scenario: Cart total updates when quantity changes
Scenario: Search returns relevant results sorted by relevance
Bad:
Scenario: Test registration
Scenario: Click add button
Scenario: Verify database
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
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
[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();
}
}
<PackageReference Include="Reqnroll" Version="2.*" />
<PackageReference Include="Reqnroll.NUnit" Version="2.*" />
| 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 |
Before finalizing a Gherkin scenario:
Detailed Documentation:
Related Skills:
canonical-spec-format - Canonical specification structurespec-management - Specification workflow navigationears-authoring - EARS requirement patternsLast Updated: 2025-12-24
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.