/learn-bdd-scenarios

name: Learn what defines effective BDD scenarios
description: Interactive guidance on writing complete, effective BDD scenarios for story-flow.
user-invocable: false

What Defines Effective, Complete BDD Scenarios

Overview

This learning module helps junior developers understand how to write BDD (Behavior-Driven Development) scenarios that are effective for story-flow's automated testing workflow.

Instructions

Present the following content interactively. After each section, use `AskUserQuestion` to offer 3 options:

• "Continue to next section"
• "Show more examples"
• "I have a question"

---

Section 1: The Purpose of BDD Scenarios

Explain that in story-flow, BDD scenarios serve two purposes:

1. **Executable specifications** - Claude uses Playwright MCP to execute these scenarios directly in a browser 2. **Regression test generation** - With `--record` flag, scenarios become Playwright `.spec.js` files

This means scenarios must be:

• **Precise enough** for automated execution
• **Complete enough** to verify the feature works correctly
• **Structured correctly** so Claude can follow them step-by-step

---

Section 2: Anatomy of an Effective BDD Scenario

Present this structure with explanations:

Feature: [Feature name matching the story]

Background:
  # Shared setup steps that run before EVERY scenario
  Given I am logged in as "test@example.com"
  And I am on the settings page

@purge-data
Scenario: FEAT-01: [Clear, descriptive title]
  # Given - Initial state/context
  Given there are 3 images in the gallery

  # When - The action being tested
  When I click the "Delete" button on the first image
  And I confirm the deletion in the dialog

  # Then - Expected outcome (assertions)
  Then I should see 2 images in the gallery
  And the deleted image should not be visible
  And the image should be removed from S3 bucket

**Key elements:**

| Element | Purpose | Example | |---------|---------|---------| | `Feature:` | Groups related scenarios | `Feature: Image Gallery Management` | | `Background:` | Shared setup (runs before each scenario) | Login, navigation, seed data | | `@tags` | Control execution behavior, or label tests for filtering | `@purge-data`, `@screenshots`, `@staging` | | `Scenario: ID:` | Unique identifier + descriptive title | `FEAT-01: Delete single image` | | `Given` | Preconditions/initial state | `Given there are 3 images` | | `When` | User actions | `When I click "Delete"` | | `Then` | Expected outcomes | `Then I should see 2 images` |

---

Section 3: The Five Qualities of Effective Scenarios

1. Specific and Unambiguous

Show the difference:

# BAD - Vague, Claude won't know what to do
When I update the settings
Then it should work

# GOOD - Specific actions and outcomes
When I enter "John Doe" in the "Display Name" field
And I click the "Save" button
Then I should see "Settings saved successfully" message
And the "Display Name" field should show "John Doe"

2. Complete Assertions

Every scenario should verify:

• **Visual feedback** - What the user sees
• **Data persistence** - That changes are saved (API, S3, database)
• **Error states** - When applicable

# INCOMPLETE - Only checks UI
Then I should see "Image deleted" message

# COMPLETE - Checks UI + data layer
Then I should see "Image deleted" message
And the image should be removed from S3 bucket "apps" at "{appId}/assets/image1.png"
And the gallery should show 2 images

3. Independence at the Right Level

**Feature files should be independent** - Each `.feature` file should not rely on another feature file running first. Use `@purge-data` on the first scenario to ensure clean state.

**Scenarios within a feature CAN depend on each other** - For realistic user journeys, scenarios can build on previous ones:

This approach:

• Tests realistic user flows end-to-end
• Reduces repetitive setup steps
• Makes feature files self-contained and runnable in isolation

@purge-data  # Ensures clean state for this feature file
Scenario: FEAT-01: Create a new project
  When I click "New Project"
  And I enter "My App" in the "Project Name" field
  And I click "Create"
  Then I should see "My App" in the project list

Scenario: FEAT-02: Add an image to the project
  # Builds on FEAT-01 - "My App" already exists
  Given I am viewing the "My App" project
  When I upload "logo.png"
  Then the image should appear in the gallery

Scenario: FEAT-03: Delete the project
  # Builds on previous scenarios
  When I click "Delete Project" on "My App"
  And I confirm the deletion
  Then "My App" should not appear in the project list

4. Uses Concrete Values

# BAD - Abstract
Given some images exist
When I enter a name
Then it should be saved

# GOOD - Concrete
Given there are 3 images in the gallery
When I enter "Product Photo 1" in the "Image Name" field
Then the first image should be named "Product Photo 1"

5. Covers Happy Path AND Edge Cases

A complete feature should have scenarios for:

| Type | Example | |------|---------| | Happy path | User successfully completes the action | | Validation errors | User enters invalid data | | Empty states | No data exists yet | | Boundary conditions | Max length, first/last items | | Error recovery | Network failure, timeout |

---

Section 4: Supported Tags

Explain the supported tags:

| Tag | Effect | When to Use | |-----|--------|-------------| | `@purge-data` | Runs `make reseed` before scenario | When scenario needs clean/known state | | `@screenshots` | Takes one screenshot per assertion group — consecutive assertions with no action between them share a shot | For visual verification or debugging | | `@timeout-*` | Extends the scenario timeout, e.g. `@timeout-600s` for 10 minutes | When a scenario is genuinely slow, not to paper over flakiness | | Any other tag | No effect on execution; carried into the generated Playwright test name | Labels for `--grep` filterin