Skip to content

Create BDD Scenarios in Gherkin with AI

Updated 2026-06-08·basic·Test Design

Reads a user story and returns Cucumber-compatible Gherkin scenarios covering happy path, error scenarios, and at least two edge cases. Uses Scenario Outline with Examples tables when 2+ data variations exist. Forbids UI implementation detail in Then steps.

When to use it

  • You have a user story (As a... I want... So that...) and need first-draft acceptance tests.
  • You're moving a feature into a BDD workflow (Cucumber, SpecFlow, Behat) and need scaffolds.
  • You want a shared-language artifact between PM, dev, and QA before development starts (3 amigos).
  • You need to expand thin acceptance criteria into testable scenarios.

The prompt

XML-tagged — best for Claude 4.x

<role>
You are a BDD practitioner with 5+ years writing Gherkin for Cucumber projects. You write scenarios that read like business language, never like UI scripts.
</role>

<context>
The team uses Cucumber with step definitions in TypeScript. Scenarios live in .feature files. We follow these rules: Given describes state, When describes a single user action, Then describes observable outcome (never UI implementation). We use Scenario Outline + Examples table when 2+ data variations exist.
</context>

<task>
Convert the user story below into 4-6 Gherkin scenarios covering:
1. The happy path (one scenario)
2. At least one error/negative scenario
3. At least two edge cases (boundary, race, unusual input)
4. Use Scenario Outline + Examples whenever the same flow has 2+ data variations
</task>

<input>
User story: {user_story}
Acceptance criteria (if any): {acceptance_criteria}
Out-of-scope constraints (if any): {constraints}
</input>

<constraints>
- Gherkin keywords: Feature, Scenario, Scenario Outline, Background (only if 3+ scenarios share state), Given, When, Then, And, But.
- Then steps describe observable outcomes — NEVER UI implementation ("button is blue", "modal slides in").
- When steps describe ONE action; chain via "And" only if it's the same user intent.
- Use Scenario Outline + Examples for data variations, never copy-paste scenarios with different inputs.
- Tags: prefix the Feature with @feature-name; tag negative scenarios with @negative.
</constraints>

<output_format>
A single .feature file as a code block, followed by a 1-2 sentence "Notes" paragraph listing any out-of-scope items the user might want to test in a separate feature.
</output_format>

Think through which steps are reusable across scenarios (Background candidates) before writing.

Example

Common pitfalls

  • Model often leaks UI detail into Then ('I see a red error banner') — keep the no-UI-language constraint.
  • Without acceptance criteria, edge cases default to generic 'invalid input' rather than scenario-specific (rate limit, race).
  • Background is over-used when only 1-2 scenarios actually share state — review whether it improves readability.
  • Scenario Outline values can become unrealistic placeholders if you don't provide a domain example.

Tips

  • Always include any acceptance criteria you have — the model generates much sharper edge cases when criteria spell out limits.
  • If output has a 'Scenario Outline' with only one Example row, refactor it to a regular Scenario.
  • Add the tag @smoke to the happy path scenario manually after generation — model rarely tags consistently.
  • Run scenarios past a non-engineer stakeholder. If they can't understand them, the BDD is failing its main job.

FAQ

Use Outline when the same flow (Given/When/Then) is exercised with 2+ data variations. Use separate Scenarios when the flow is fundamentally different — e.g., a happy path and an expired-link path have different Given/Then, not just different data.

Related prompts

Use with these tools