---
name: gherkin-spec
description: Gherkin specification syntax, keywords, Scenario Outline, best practices, and anti-patterns for writing behavioral feature files in Spec-Driven Development (SDD). Use when creating, reviewing, or refining .feature files and Gherkin scenarios.
---

# Gherkin Specification Skill

> Reference for writing effective Gherkin specifications in Coder Sura SDD workflow.

## Gherkin Syntax Overview

Gherkin is a business-readable DSL for describing software behavior without implementation details.

### Basic Structure

```gherkin
Feature: {Feature Title}
  {Optional description - 1-3 lines}

  Background:
    Given {shared precondition for all scenarios}

  Scenario: {Scenario Title}
    Given {precondition}
    When {action}
    Then {expected outcome}

  Scenario Outline: {Parameterized Scenario}
    Given {precondition with <variable>}
    When {action with <variable>}
    Then {outcome with <variable>}

    Examples:
      | variable | expected |
      | value1   | result1  |
      | value2   | result2  |
```

## Keywords Reference

### Feature
```gherkin
Feature: User Authentication
  As a registered user
  I want to log in to my account
  So that I can access my personalized dashboard
```

**Rules:**
- One feature per file
- Title should be a noun phrase
- Description uses "As a / I want / So that" format

### Background
```gherkin
Background:
  Given the user is on the login page
  And the system is available
```

**Rules:**
- Runs before EVERY scenario in the file
- Use sparingly - only for truly shared setup
- Avoid complex backgrounds (max 3 steps)

### Scenario
```gherkin
Scenario: Successful login with valid credentials
  Given the user has a valid account
  When the user enters correct credentials
  And the user clicks "Login"
  Then the user is redirected to the dashboard
  And a welcome message is displayed
```

### Scenario Outline (Parameterized)
```gherkin
Scenario Outline: Login validation
  Given the user enters "<username>" and "<password>"
  When the user attempts to login
  Then the system shows "<message>"

  Examples:
    | username | password | message              |
    | valid    | valid    | Welcome              |
    | invalid  | valid    | Invalid username     |
    | valid    | invalid  | Invalid password     |
    | empty    | empty    | Fields are required  |
```

**Use when:**
- Same behavior with different inputs
- Boundary value testing
- Equivalence class testing

## Step Keywords

### Given (Preconditions)
```gherkin
Given the user is logged in
Given there are 5 products in the cart
Given the current date is "2024-01-15"
```

**Purpose:** Set up initial state
**Tense:** Past or present
**Never:** Describe actions or assertions

### When (Actions)
```gherkin
When the user clicks the "Submit" button
When the user enters "john@example.com" in the email field
When the system processes the payment
```

**Purpose:** Describe the trigger action
**Tense:** Present
**One action:** Prefer single action per When

### Then (Assertions)
```gherkin
Then the order confirmation is displayed
Then the user receives an email notification
Then the total equals $125.00
```

**Purpose:** Describe expected outcome
**Tense:** Present or future
**Verifiable:** Must be testable

### And / But (Connectors)
```gherkin
Given the user is logged in
  And the user has admin privileges
  But the user is not the account owner

Then the order is created
  And an email confirmation is sent
  But the payment is not processed yet
```

## Best Practices

### 1. One Behavior Per Scenario
```gherkin
# ❌ Bad - Multiple behaviors
Scenario: User management
  Given a new user
  When user registers
  Then user is created
  When user logs in
  Then user sees dashboard
  When user updates profile
  Then profile is saved

# ✅ Good - Single behavior
Scenario: User registration
  Given a visitor on the registration page
  When the visitor submits valid registration data
  Then a new user account is created
  And a confirmation email is sent
```

### 2. Use Domain Language
```gherkin
# ❌ Bad - Technical jargon
Scenario: POST request creates DB record
  Given the API endpoint /users
  When POST with JSON payload
  Then HTTP 201 and record in users table

# ✅ Good - Business language
Scenario: New customer registration
  Given a prospective customer
  When the customer completes registration
  Then the customer account is created
  And the customer can log in
```

### 3. Avoid UI Details
```gherkin
# ❌ Bad - UI-specific
Scenario: Login
  Given the user is on login.html
  When the user types in input#username
  And clicks button.btn-primary
  Then div.welcome is visible

# ✅ Good - Behavior-focused
Scenario: Login
  Given a registered user
  When the user logs in with valid credentials
  Then the user sees their dashboard
```

### 4. Keep Scenarios Independent
```gherkin
# ❌ Bad - Dependent scenarios
Scenario: Step 1 - Create order
  When user creates order
  Then order ID is stored

Scenario: Step 2 - Pay order
  Given the order from previous scenario  # ← BAD
  When user pays
  Then payment succeeds

# ✅ Good - Independent
Scenario: Pay existing order
  Given an order with ID "ORD-123" exists
  When the user pays for order "ORD-123"
  Then the payment succeeds
```

### 5. Use Tables for Complex Data
```gherkin
Scenario: Order with multiple items
  Given the shopping cart contains:
    | product      | quantity | price  |
    | Laptop       | 1        | 999.00 |
    | Mouse        | 2        | 25.00  |
    | Keyboard     | 1        | 75.00  |
  When the user proceeds to checkout
  Then the order total is $1124.00
```

## Anti-Patterns

### 1. Incidental Details
```gherkin
# ❌ Bad
Given it is Monday, January 15, 2024 at 10:30 AM
And the weather is sunny
And the user's browser is Chrome v120
When the user clicks the blue "Submit" button...

# ✅ Good
Given a business day
When the user submits the form...
```

### 2. Imperative Steps
```gherkin
# ❌ Bad - Too procedural
Given I navigate to /login
And I enter "user" in field "username"
And I enter "pass" in field "password"
And I click element with id "submit"

# ✅ Good - Declarative
Given I am on the login page
When I log in as a registered user
```

### 3. Conjoined Scenarios
```gherkin
# ❌ Bad
Scenario: Order lifecycle
  Given...When...Then (create)
  And when...then (pay)
  And when...then (ship)
  And when...then (deliver)

# ✅ Good - Split
Scenario: Create order
Scenario: Pay order
Scenario: Ship order
Scenario: Deliver order
```

## File Organization

```
specs/
└── features/
    ├── authentication/
    │   ├── login.feature
    │   ├── logout.feature
    │   └── password-reset.feature
    ├── orders/
    │   ├── create-order.feature
    │   ├── cancel-order.feature
    │   └── order-history.feature
    └── payments/
        ├── credit-card.feature
        └── refund.feature
```

**Naming conventions:**
- Use kebab-case: `user-registration.feature`
- One feature per file
- Group by domain, not by page

## Scenario Quantity Guidelines

| Feature Complexity | Recommended Scenarios |
|-------------------|----------------------|
| Simple CRUD | 3-5 |
| Business workflow | 5-10 |
| Complex integration | 10-15 |
| **Maximum per file** | **15** |

If you need more than 15 scenarios, split by sub-feature.

## Tags

```gherkin
@critical @smoke
Feature: Payment Processing

  @happy-path
  Scenario: Successful payment
    ...

  @error-handling @wip
  Scenario: Payment timeout
    ...
```

**Common tags:**
- `@critical` - Business-critical scenarios
- `@smoke` - Quick sanity tests
- `@wip` - Work in progress (skip in CI)
- `@manual` - Requires manual testing
- `@slow` - Long-running tests

## Integration with Coder Sura

The **SDD Agency** uses this skill via:
- **Criteria Validator ✅**: Validates acceptance criteria are Gherkin-compatible
- **Scenario Designer 🎯**: Applies test design techniques to generate scenarios

```
Acceptance Criteria → Criteria Validator → Scenario Designer → Gherkin Files
```

## References

- Companion Skill: `test-design-techniques` (activate when deriving EP, BVA, Decision Table, or State Transition cases)
- [Cucumber Docs](https://cucumber.io/docs/gherkin/)