Explore App

When to use

• After ingest-spec has populated parsed-spec.md with scenarios
• Once per scenario — run separately for each scenario in the test plan
• When running as part of run-testing-session pipeline (Stage 2, per scenario)
• When exploration is stale after a UI change

Inputs

• Scenario name and slug (from parsed-spec.md)
• Base URL (from project-context.md or user-provided)
• docs/playwright-spec-testing/project-context.md (for baseURL only)
• docs/playwright-spec-testing/parsed-spec.md (this scenario's section)

What it does

Walk through the app in a browser, performing each step of the scenario, and capture real selectors, URLs, and behavior. No selector is invented — every selector in the exploration report must come from what you observe.

Phase 1: Open the browser

./node_modules/.bin/playwright open [BASE_URL]

Phase 2: Walk through each step

For EACH step in the scenario:

1. Perform the action
2. Capture after each action:
   • Current URL
   • Element interacted with: tag, role, visible text, best selector
   • Any visible text changes (success messages, errors)

Selector priority (most to least preferred):

1. page.getByRole('button', { name: 'Sign In' }) — role + accessible name
2. page.getByLabel('Email') — label
3. page.getByPlaceholder('Enter email') — placeholder
4. page.getByTestId('login-button') — data-testid
5. page.locator('.login-btn') — CSS (last resort, fragile)

Phase 3: Capture expected outcome

After the final step, capture:

• Resulting URL
• Element/text confirming the expected outcome
• Its selector

Phase 4: Write exploration report

Save to docs/playwright-spec-testing/exploration/[SCENARIO_SLUG].md:

# Exploration: [Scenario Name]

_Explored on [DATE]_
_Base URL: [url]_

## Step N: [Step description]

**Action:** [what was done]
**Selector:** `[exact Playwright selector]`
**URL after:** [url]
**Expected state after:** `[selector]` shows "[text]" / count is [N] / URL is [url]
**Notes:** [anything unusual]

## Step N: ...

## Expected Outcome

**Assertion target:** `[selector]`
**Visible text:** "[text]"
**URL:** [url]

Phase 5: Update parsed-spec.md

For this scenario, fill in:

### Exploration Report
`docs/playwright-spec-testing/exploration/[SCENARIO_SLUG].md`

### Status
- [x] Planned
- [x] Explored
- [ ] Generated
- [ ] Passing

Key Rules

• NEVER invent a selector — if you can't find the element, report NEEDS_CONTEXT
• NEVER leave Expected state after: blank. If no element changes, write URL changes to [url] or No visible state change.
• Use the same selector-first discipline for Expected state after: — observable evidence only, no inference.
• NEVER run against production — use local dev URL only
• One exploration report per scenario

Output

• docs/playwright-spec-testing/exploration/[SCENARIO_SLUG].md
• Updated docs/playwright-spec-testing/parsed-spec.md

Report when done:

• Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
• Number of steps explored
• Any selectors that required CSS fallback
• Any elements that could not be found