/execute-bdd-scenario

name: Execute BDD scenarios
description: Execute BDD test scenarios from .feature files using browser automation.
user-invocable: false
effort: medium

Execute BDD scenarios

Instructions

• Use `mcp__plugin_story-flow_playwright__*` tools to manipulate browser to EXECUTE the BDD scenarios directly without generating any Playwright test file.
• **Test Execution Protocol:**
• **Before executing:** Read the feature file and confirm the exact line numbers, scenario title, background sections and all "Then" and "And" assertions.
• **Execution order is CRITICAL:**

1. **Scenario tags FIRST** (e.g., `@purge-data`) 2. **Background steps SECOND** (setup prerequisites) 3. **Scenario steps THIRD** (Given/When/Then)

• **Execute all Background steps:** Background sections (both global and rule-specific) in feature files define prerequisite setup steps. **EVERY** step MUST be completed before executing the scenario steps, including both UI interactions and API calls by curl.
• **During execution:** Compare actual behavior against expected behavior at each assertion step.
• **On failure:** STOP immediately and provide a summary including:
• Expected behavior (with line numbers from feature file)
• Actual behavior (with evidence from page snapshot)
• Root cause analysis
• **CRITICAL: Do NOT continue to subsequent test steps after a failure**
• **Executing Multiple Scenarios:**

When executing multiple scenarios (e.g., "Execute all scenarios in @path/to/file.feature", "Execute ARMR-01,ARMR-02 scenarios in @path/to/file.feature"): 1. Read the feature file to identify all scenario IDs and titles 2. For each scenario, use the **Task tool** with `subagent_type="general-purpose"` to run it in isolated context sequentially:

     Load skills in this order using the Skill tool:
     1. First: `story-flow:execute-bdd-scenario` (plugin - general BDD framework)
     2. Then: `execute-bdd-scenario` if it exists (project-level - overrides/extends the plugin)
     3. Confirm which skills are loaded before continuing with the execution.

     Execute BDD scenario <SCENARIO-ID> in @path/to/file.feature [--record if recording mode is active].

**IMPORTANT:** Replace `<SCENARIO-ID>` with the individual scenario ID (e.g., `ARMR-01`), NOT "all". Each subagent executes exactly one scenario. **Recording Mode:** When executing multiple scenarios with `--record`, pass the `--record` flag to each subagent prompt. Each subagent is responsible for generating/updating the `.spec.js` file after executing its scenario — do NOT defer spec file generation to the parent orchestrator. 3. Wait for subagent completion, record PASS/FAIL result 4. **If the scenario FAILED:** STOP immediately and print the summary table with remaining scenarios marked as "⊘ SKIPPED". Do NOT proceed to the next scenario. 5. Print summary table:

     | Scenario | Title | Result |
     |----------|-------|--------|
     | SMG-01   | Display available languages | ✓ PASSED |
     | SMG-02   | Search and filter strings   | ✗ FAILED |
     | SMG-03   | Inline edit a string value  | ⊘ SKIPPED |

• Save `.feature` files in the same folder as the stories.
• If a BDD scenario has the `@screenshots` tag, take one screenshot per **assertion group** — a maximal run of consecutive assertion steps with no action or wait step between them, since nothing re-renders in between — captured after the group's **last** UI assertion so every asserted condition has settled, and, in `--record` mode when VRT is configured, emit one visual regression tracking call per group (see [Visual Regression Testing (VRT)](#visual-regression-testing-vrt)). Command and polling assertion steps (S3/CLI/API checks) assert outside the viewport: they take no screenshot and do not break the group. Pass `browser_take_screenshot` a filename explicitly prefixed with `.playwright-mcp/` — e.g. `.playwright-mcp/SMG-01-i-should-see-the-dashboard.png` so it lands in the `.playwright-mcp` output folder — never an absolute path, which writes to the project root.
• If a BDD scenario doesn't have the `@screenshots` tag, do not take any screenshot.
• If a BDD scenario has the `@purge-data` tag, restore the seed data first (before the Background steps) by executing the `make reseed` command.
• If a BDD scenario does not have the `@purge-data` tag, do not restore the seed data before running the scenario.
• If a BDD scenario has the `@timeout-*` tag, extend the scenario and expect timeout to be longer. e.g. `@timeout-600s` means timeout for the scenario and every expect step is 600s(10m).
• Use `mcp__plugin_story-flow_playwright__browser_run_code_unsafe` to set the browser offline.
• Reference the @Makefile for local development workflows.
• Navigate relative to the base URL from `BASE_URL`, falling back to `use.baseURL` in the project's @playwright.config.js. Never hardcode a host.

Mobile App Instructions

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | `APPIUM_DEVICE_NAME` | Local device name or emulator | `emulator-5554` (Android) | | `APPIUM_UDID` | Local iOS device or simulator UDID | - | | `APPIUM_APP_PACKAGE` | Local Android app package unique identifier | - | | `APPIUM_APP_ACTIVITY` | Local Android app launcher activity | `.MainActivity` | | `APPIUM_BUNDLE_ID` | Local iOS app bundle identifier | - | | `BROWSERSTACK_USERNAME` | BrowserStack username | - | | `BROWSERSTACK_ACCESS_KEY` | BrowserStack access key | - | | `BROWSERSTACK_APP_ID` | Uploaded app ID (`bs://...`) | - |

**Mode detection**: When all 3 BrowserStack variables are set, use BrowserStack. Otherwise, use local Appium.

Local Appium Configuration (Default)

Start Appium server: `npx appium server --port 4723`. Appium ships no drivers — install `uiautomator2` for Android, `xcuitest` (with Xcode) for iOS.

A hybrid app's webview needs no extra driver: switch with `driver.switchContext(