Gherkin Spec Writer

Gherkin Spec Writer

Purpose

Generate clean, structured, executable Gherkin .feature files from any requirement. Ready to use with Cucumber, Behave, Karate, or any BDD framework.

Input Accepted

• User Story (As a / I want / So that)
• Acceptance criteria (bullet points or draft Given/When/Then)
• Plain feature description in natural language
• Existing test cases to convert to Gherkin format
• API endpoint or UI flow description

Generation Process

Step 1 — Extract Scenarios

Identify each distinct test scenario:

• Minimum: 1 happy path
• 1 negative per business rule
• 1 boundary scenario per numeric or date field
• 1 security/auth scenario if authentication is involved

Step 2 — Identify Shared Context

Extract repeated Given steps shared by all scenarios → move to Background. If a precondition applies only to some scenarios, keep it inside those scenarios.

Step 3 — Group Data-Driven Cases

Identify 3+ similar scenarios that differ only by input values → use Scenario Outline + Examples.

Step 4 — Apply Tags

Tag each scenario using the convention in references/gherkin-tags.md.

Gherkin Structure

Feature: [Short feature name — noun phrase]
  As a [role]
  I want [action]
  So that [benefit]

  Background:
    Given [shared precondition — max 3 steps]
    And   [shared precondition]

  @smoke @critical
  Scenario: [Descriptive title — what is being tested]
    Given [initial state — system or user context]
    When  [single action performed by the actor]
    Then  [observable, verifiable outcome]
    And   [additional outcome if needed]

  @negative @high
  Scenario: [Negative case title]
    Given [context]
    When  [invalid action or bad condition]
    Then  [error or rejection outcome]

  @boundary @regression
  Scenario Outline: [Title with <variable>]
    Given [context with <variable>]
    When  [action with <variable>]
    Then  [result is <expected>]

    Examples:
      | variable | expected |
      | value1   | result1  |
      | value2   | result2  |
      | value3   | result3  |

Step Writing Rules

Never:

• Put technical/database details in Then
• Combine multiple actions in one When
• Write Then the system saves the record → write Then the transaction is visible in the history

Output Format

Generate a complete .feature file including:

1. Feature header with role/goal description
2. Background (if shared preconditions exist)
3. All scenarios, tagged and ordered: Happy Path → Negative → Boundary → Security → Edge
4. Scenario Outlines with complete Examples tables

Always end with a comment block:

# Generated by QIOS gherkin-spec-writer
# Total scenarios: [N]
# Tags: @smoke [N]  @regression [N]  @critical [N]  @negative [N]

References

• references/gherkin-best-practices.md — Complete style guide and rules
• references/gherkin-tags.md — Full tagging strategy and conventions
• ../../_shared/gherkin-style-guide.md — Shared source of truth
• examples/input-requirement.md — Example input
• examples/output-transfer.feature — Complete real-world example
• examples/output-login.feature — Second complete example