@vardot/varbase-e2e 2.0.0

package/docs/11-debugging.md

@@ -0,0 +1,129 @@
+# Debugging
+
+When a scenario fails, you have several layers of evidence to inspect.
+
+## Auto-screenshot on failure
+
+Every failed step automatically writes a screenshot under `screenshots/` with a timestamped filename. Configure in `cucumber.js`:
+
+```js
+worldParameters: {
+  screenshot: {
+    dir: './screenshots',
+    onFailed: true,
+    failedPrefix: 'failed_',
+    filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
+    filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
+  }
+}
+```
+
+Override per-run via env vars:
+
+| Variable | Effect |
+| --- | --- |
+| `VARBASE_E2E_SCREENSHOT_DIR` | Output directory |
+| `VARBASE_E2E_SCREENSHOT_PURGE` | `1` to wipe `dir` at the start of the run |
+| `VARBASE_E2E_SCREENSHOT_ON_FAILED` | `0` to disable failure screenshots |
+| `VARBASE_E2E_SCREENSHOT_ON_EVERY_STEP` | `1` to screenshot every step |
+| `VARBASE_E2E_SCREENSHOT_FULLSCREEN` | `1` to always full-page |
+
+## Headed mode
+
+```bash
+HEADLESS=false SLOW_MO=800 npm test
+# or
+npm run test:headed
+```
+
+Browser opens, every action is delayed by `SLOW_MO` ms so you can watch.
+
+## Console + page errors
+
+JS errors surface in two ways:
+
+1. **Always tracked** — every scenario captures `pageerror` and `console.error`. Inspect inside a custom step via `this._jsErrors`.
+2. **Auto-fail** — tag a scenario `@javascript` to assert "no errors" at scenario end. Suppress with `@js-errors`.
+
+Explicit assertion at any point:
+
+```gherkin
+Then there should be no JavaScript errors
+```
+
+## HTML / PDF report
+
+After every run, `tests/reports/cucumber_report.html` is regenerated. Open it for a clickable summary of features, scenarios, durations, screenshots, and per-step output.
+
+Disable: `VARBASE_E2E_REPORT_DISABLE=1`.
+
+### Export to PDF
+
+```bash
+# HTML + PDF in one shot
+npx generate-reports --format all
+
+# PDF only — Letter, landscape, slim margin
+npx generate-reports --format pdf --pdf-format Letter --pdf-landscape --pdf-margin 10mm
+
+# Branded PDF with header / footer
+npx generate-reports --format pdf \
+  --pdf-header '<div style="font-size:10px;width:100%;text-align:center;">Acme Q3 Regression</div>' \
+  --pdf-footer '<div style="font-size:10px;width:100%;text-align:center;"><span class="pageNumber"></span>/<span class="totalPages"></span></div>'
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--format html\|pdf\|all` | Repeatable. Default `html`. |
+| `--pdf-format` | `Letter`, `Legal`, `A3`, `A4`, `A5`, … (default `A4`) |
+| `--pdf-landscape` | Landscape orientation |
+| `--pdf-margin` | CSS margin for all sides (default `20mm`) |
+| `--pdf-header` / `--pdf-footer` | HTML templates (use `<span class="pageNumber">` / `<span class="totalPages">`) |
+| `--pdf-no-background` | Disable print backgrounds |
+| `--pdf-scale` | Scale factor 0.1–2.0 |
+| `--pdf-out` | Override PDF output path |
+
+PDF generation uses Playwright (already installed) — no extra setup. Every panel auto-expanded and colors preserved (`print-color-adjust: exact`).
+
+## Scenario timing
+
+```bash
+time npx cucumber-js
+```
+
+For per-scenario breakdown, parse the JSON report:
+
+```bash
+node -e "
+const r = require('./tests/reports/cucumber_report.json');
+const s = [];
+r.forEach(f => f.elements.forEach(sc => {
+  const ms = sc.steps.reduce((a,b)=>a+(b.result?.duration||0),0)/1e6;
+  s.push({n: sc.name, ms});
+}));
+s.sort((a,b)=>b.ms-a.ms).slice(0,10).forEach(x =>
+  console.log(x.ms.toFixed(0).padStart(6), 'ms', x.n));
+"
+```
+
+## Trace viewer
+
+Varbase E2E does not enable Playwright traces by default (they are heavy). To opt in for a single run, edit `playwright.config.ts`:
+
+```ts
+contextOptions: {
+  ...,
+  recordVideo: { dir: './videos' },
+  // tracing requires manual start/stop in a hook — see Playwright docs.
+}
+```
+
+## Common diagnoses
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Passes locally, fails in CI | Timing | Use web-first assertion or edge wait |
+| Flickering — sometimes passes | Race condition | `wait for "selector" to appear` instead of `wait Ns` |
+| `Modal dialog is visible, but it should not be` | Stale modal selector | Register a `modal` selector in your CMS preset |
+| `page.goto: net::ERR_CONNECTION_REFUSED` | Dev server not started | `npm start` in another terminal |
+| `function has 0 arguments, should have 3` | Step regex captures missing in callback | Add the captured group params in the callback signature |

package/docs/12-ai-agent-guide.md

@@ -0,0 +1,338 @@
+# AI Agent Guide — Wisdom from the Recipes Book
+
+This page distills the canonical guidance from
+**Varbase-E2E-Recipes v1.0.30** (583 pages, 35 chapters, 340+ recipes) into
+a compact reference for AI coding assistants working on any varbase-e2e
+project.
+
+The wisdom here is the product of years of BDD practice — Kent Beck's
+TDD revolution, Dan North's BDD reframing, Martin Fowler / Thoughtworks
+SPDD, and the daily reality of automated browser testing. Read it once.
+Apply it on every change.
+
+---
+
+## The First Principle
+
+> **AI generates. Humans validate. Tests verify.**
+
+AI does not know what "correct" means for the business. It can write
+code that compiles, runs, and looks reasonable — but only the test
+suite can prove the code does what the business actually needs. That is
+why varbase-e2e scenarios exist: they are the executable contract.
+
+Three corollaries:
+
+1. **The person who writes the tests controls the quality.**
+2. **The person who controls the quality controls the product.**
+3. **Code is the artifact. The prompt and the tests are the source of truth.**
+
+---
+
+## Test-Drive-Develop (TDD's evolution for the AI age)
+
+Traditional TDD: write a test, make it pass, refactor.
+
+Test-Drive-Develop (TDD AI): a closed loop where humans specify, AI
+implements, tests verify.
+
+```
+TEST   →  human writes the feature file (Gherkin = the contract).
+DRIVE  →  human prompts AI: "implement what passes these scenarios".
+DEVELOP → AI writes code. Tests pass → ship. Tests fail → iterate.
+```
+
+The varbase-e2e suite is the verification step. If green, AI produced
+code matching the structured prompt. If red, AI iterates against the
+failing scenario name + step + expected/actual — no human bottleneck.
+
+---
+
+## SPDD — Structured Prompt-Driven Development
+
+Coined by Thoughtworks. Treats prompts as first-class delivery
+artifacts: version-controlled, reviewed, reused.
+
+### The REASONS canvas
+
+Every prompt should pass through these seven sections:
+
+| Letter | Section | Purpose |
+| --- | --- | --- |
+| **R** | Requirements | Problem statement + definition of done |
+| **E** | Entities | Domain nouns + relationships |
+| **A** | Approach | Strategy to meet the requirements |
+| **S** | Structure | Components, pages, routes, dependencies |
+| **O** | Operations | Concrete testable steps with signatures |
+| **N** | Norms | Cross-cutting engineering standards (i18n, a11y, perf, logging) |
+| **S** | Safeguards | Non-negotiable boundaries (security, privacy, rate limits, failure modes) |
+
+Varbase E2E feature files are SPDD prompts in disguise. Map:
+
+| REASONS | Varbase E2E artifact |
+| --- | --- |
+| Requirements | `Feature:` + `As / I want / So that` |
+| Entities | Domain nouns in step text |
+| Approach | `Background` + scenario outlines |
+| Structure | `tests/` layout + `cucumber.js` |
+| Operations | Individual `Given / When / Then` steps |
+| Norms | `worldParameters` + locale / a11y scenarios |
+| Safeguards | Tags (`@critical`, `@security`), assertion scenarios |
+
+### The cardinal SPDD rule
+
+> **When reality diverges from the prompt, fix the prompt first. Then
+> update the code.**
+
+A code-first fix forgets to update the spec. Six months later, a
+refactor removes the fix, the spec says nothing about it, and the bug
+returns. Prompt-first fixes prevent decay.
+
+### The three SPDD skills
+
+1. **Alignment** — lock intent before writing code. Show the `Feature:` narrative to product / design / security. Get nods. Then write scenarios.
+2. **Abstraction-First** — design before generating. Define Background + named selectors before per-scenario steps.
+3. **Iterative Review** — never let AI run unattended for more than one feature at a time. Review after every generation.
+
+---
+
+## What BDD Actually Tests
+
+| Question | TDD answer | BDD answer |
+| --- | --- | --- |
+| Tests what? | Components (classes / functions) | Features (user actions / business behaviour) |
+| Written by? | Developers | Team (Three Amigos) |
+| Language? | Programming language | Gherkin (plain text) |
+| Audience? | Developers | Everyone |
+| Granularity? | Function / class | User story / feature |
+| On failure? | Knows which component | Knows which feature |
+| Documentation? | Code comments | Living specification |
+
+Use **both**. BDD at the feature level, TDD at the component level.
+They complement each other.
+
+---
+
+## The Three Amigos
+
+A 15–30 minute conversation format BEFORE coding starts:
+
+```
+Product Owner  ─►  describes intent
+QA / Tester    ─►  writes scenarios
+Developer      ─►  implements steps
+                          │
+                          ▼
+                Executable specification
+                      (.feature files)
+```
+
+When you (an AI agent) are asked to add a new feature, simulate the
+Three Amigos: list the Product / QA / Dev questions a human team would
+ask. Answer them in the feature description before writing any
+scenarios.
+
+---
+
+## DAMP, KISS, YAGNI
+
+* **DAMP** — Descriptive And Meaningful Phrases. Every scenario must be
+  understandable without context. No abbreviations. No undefined nouns.
+* **KISS** — Keep It Simple, Stupid. Write the simplest test that could
+  fail. Write the simplest code that makes it pass.
+* **YAGNI** — You Ain't Gonna Need It. Do NOT write tests for features
+  nobody asked for. Every scenario must trace to a real business need.
+
+The MMF principle (Minimum Marketable Feature): ship the smallest
+piece of behaviour that delivers value. Add the next one only when the
+first one is verified green.
+
+---
+
+## The Anti-Patterns Hall of Fame
+
+| Anti-pattern | Symptom | Fix |
+| --- | --- | --- |
+| **Sleep-driven testing** | `wait 3s` after every action | BBR smart waits — wait for the EVENT, not the clock |
+| **God step** | `Given the system is fully set up with admin user and products and orders` | Decompose into specific composable steps |
+| **Coupled scenarios** | Scenario 2 assumes scenario 1's data exists | Each scenario creates its own test data |
+| **Implementation testing** | `Then the database should have a record in users table` | Test what the user experiences, not how the code works |
+| **Brittle selectors** | Tests break when CSS changes | Named selectors + accessible role locators |
+| **Over-trusting AI output** | AI generates 500 tests, none cover the business edge case | AI generates, human validates against requirements |
+| **God scenario** | One scenario tests login + search + checkout | One behaviour per scenario |
+| **Sleep-then-check** | `wait 5s` then assertion | Web-first matcher with `within N seconds` |
+
+---
+
+## The Golden Rules of varbase-e2e Testing
+
+These ten rules emerged from years of BDD practice. Internalise them.
+
+1. Write tests BEFORE code (or at least before you ship).
+2. One scenario = one behaviour.
+3. Each scenario creates its own test data.
+4. **Wait for events, not time.** (BBR — see `docs/02-bbr-smart-waits.md`)
+5. Test behaviour, not implementation.
+6. Use business language, not developer jargon.
+7. Decouple from CSS / HTML structure (named selectors + roles).
+8. Make tests deterministic. No flaky `@flaky` allowed long-term.
+9. Tag scenarios. `@critical` for the smoke set; `@security` / `@a11y` for boundary scenarios.
+10. **Fix the prompt before the code** when reality diverges.
+
+---
+
+## Recipes for AI Agents
+
+### Recipe AI-1: Generate a feature file from a user story
+
+When asked to author a varbase-e2e `.feature` file:
+
+1. Read `templates/spdd-feature.md` if it exists, or use the REASONS
+   canvas from this guide.
+2. Fill **every** section before writing any Gherkin.
+3. Place the filled-in REASONS canvas as `#` comments at the top of the
+   `.feature` file.
+4. Generate one scenario per Operations item.
+5. Tag every scenario with the relevant Norm / Safeguard category
+   (`@critical`, `@auth`, `@a11y`, `@security`, `@i18n`).
+6. Use `Background:` for setup steps shared across scenarios.
+
+### Recipe AI-2: Generate a step definition
+
+When asked to add a custom step:
+
+1. Search `tests/step-definitions/*.steps.js` for an existing matching
+   step. If one exists, do NOT add a duplicate — point the user at it.
+2. Pick the file whose topic matches (see `CLAUDE.md` §3 source map).
+3. Use a regex with `(I |we )*` — never `'I ...'` Cucumber Expressions
+   unless the step genuinely cannot start with a pronoun.
+4. Add a JSDoc block with at least 5 `Example #N:` Gherkin lines that
+   match the step pattern.
+5. Use plain English in the step text. No camelCase identifiers.
+6. Run the audit: every example must match its step pattern.
+
+### Recipe AI-3: Maintain tests after a UI change
+
+The UI changed. 30 tests are red.
+
+1. Run the suite. Capture every failure: scenario name + failing step +
+   expected / actual.
+2. Group failures by root cause. Usually 2–3 causes drive 90% of the red.
+3. Find-and-replace step text where the change is purely cosmetic
+   ("Sign in" → "Log in").
+4. For structural changes, update the named selector preset, NOT every
+   feature file.
+5. Re-run the suite. Iterate until green.
+6. Commit prompt + code + selector changes together.
+
+### Recipe AI-4: Debug a flaky test
+
+A test passes locally but fails in CI.
+
+1. Check the failing step. Does it run an action? Is the next step a
+   read assertion? If yes, suspect timing.
+2. Replace `wait Ns` with an edge-driven wait — `wait until the URL
+   contains "..."`, `wait for ".success" to appear`, web-first matchers
+   with `within N seconds`.
+3. Verify no shared state — does the test depend on a previous
+   scenario's side-effects? Make it self-contained.
+4. Run with `HEADLESS=false SLOW_MO=800` to watch what really happens.
+5. Inspect screenshots in `screenshots/failed_*.png`.
+
+### Recipe AI-5: When tests go bad
+
+| Symptom | Probable cause | Fix |
+| --- | --- | --- |
+| Passes sometimes, fails other times | Timing | Smart waits / BBR |
+| Breaking when unrelated code changes | Coupling to CSS structure | Named selectors / roles |
+| Taking too long | Too many browser tests for API-testable logic | Move to API level |
+| Hard to understand | Imperative style | Declarative language |
+| Depending on other tests | Shared state | Each scenario creates own data |
+| Testing CSS classes / DOM | Implementation testing | Test visible behaviour |
+| Hardcoded waits everywhere | Sleep-driven testing | `wait for AJAX to finish`, web-first |
+| Giant `Background:` section | Setup overload | Move setup to dedicated steps |
+| Asserting too many things per scenario | Multi-behaviour scenario | One behaviour per scenario |
+| Checking database state directly | Implementation coupling | Check UI / API instead |
+
+---
+
+## What changes in the AI age
+
+| Activity | Before AI | With AI |
+| --- | --- | --- |
+| Code generation | Skill | Commodity |
+| Test writing | Skill | Amplified — humans guide, AI assists |
+| Business understanding | Premium | Premium-er |
+| Quality assurance | Critical | Critical (AI output needs validation) |
+
+The economic shift: code is cheaper to produce, but specification and
+verification are MORE valuable. Varbase E2E positions you on the
+valuable side — Gherkin is the spec, step definitions are the
+verification.
+
+---
+
+## Pitfalls of AI-Generated Tests
+
+1. **Over-trusting output.** AI can generate tests that look correct
+   but assert the wrong thing. Always review against business
+   requirements.
+2. **Testing implementation, not behaviour.** AI tends to test what the
+   code does. Human oversight keeps tests behaviour-focused.
+3. **Missing edge cases.** AI generates the happy path well. Business
+   edge cases need a domain expert.
+4. **False confidence.** "We have 500 AI-generated tests!" means
+   nothing if they don't cover what matters.
+
+> **The rule:** AI generates. Humans validate.
+
+---
+
+## When to use SPDD vs vibe-code
+
+**Use SPDD (REASONS canvas + structured prompts):**
+
+* Regulated systems (finance, healthcare, government).
+* Enterprise CMS where business logic accumulates over years.
+* Customer-facing flows with security or accessibility requirements.
+* Any feature whose behaviour must remain stable across releases.
+
+**Skip SPDD (vibe coding is fine):**
+
+* Throwaway prototypes.
+* One-off internal scripts.
+* UI explorations where you have not decided what the feature does.
+
+The cost of SPDD is the time to fill the canvas. The benefit is years
+of preserved intent. Pick the projects where the benefit clears the cost.
+
+---
+
+## The Future-Proof Mindset
+
+Before SPDD: **code is primary, specs are documentation.**
+After SPDD: **prompts are primary, code is the artifact the prompt produces.**
+
+This is not academic. It changes how you debug. It changes how you
+onboard. It changes how AI-driven refactors stay safe over years.
+
+Varbase E2E was built for this world. Every step definition is a verb.
+Every feature file is a contract. Stack SPDD on top, and you have a
+system where:
+
+* Prompts are committed.
+* Tests are executable.
+* AI generates code.
+* Tests verify.
+* Failures point at the prompt, not at the engineer's coffee intake.
+
+Master the loop.
+
+---
+
+## Source
+
+This page summarises *Varbase-E2E-Recipes v1.0.30* — chapters 1, 7, 21,
+24, 26, 29, 30, 31, 33, 34, 35 plus appendices. The full PDF lives at
+`/home/rajab/Desktop/w-book/Varbase-E2E-Recipes-v1.0.30.pdf`. The
+chapter Markdown sources live at `/home/rajab/Desktop/w-book/chapters/`.

package/docs/13-faq.md

@@ -0,0 +1,236 @@
+# FAQ
+
+Common questions for newcomers.
+
+## How is varbase-e2e different from raw Playwright?
+
+Playwright is a browser-automation library. Varbase E2E is a **BDD layer on
+top of Playwright + Cucumber-js** with:
+
+* 280+ pre-built Gherkin steps (so you write English, not JavaScript).
+* BBR-style smart waits (no `sleep`).
+* Named selector registry (`primary button` instead of
+  `button.btn-primary[type=submit]`).
+* CMS / framework selector presets (Drupal, WordPress, Bootstrap, …).
+* Auto-screenshot on failure, auto-HTML-report after every run.
+
+You still get every Playwright primitive when you need it — `this.page`
+inside any custom step is a real Playwright Page.
+
+## Do I need to write JavaScript?
+
+For most tests, no. Use the built-in steps. Write JavaScript only when
+your business has a step that no preset covers — and even then, place
+it in `tests/step-definitions/<topic>.steps.js`, not in feature files.
+
+## Why no `wait 5 seconds` in the example tests?
+
+Varbase E2E installs a smart-settle hook that runs after every
+state-changing step. The hook waits for: DOM ready, no in-flight
+fetch/XHR, no pending `setTimeout`, and a 250 ms DOM-quiet window. That
+covers the cases that historically needed manual sleeps. Read
+[BBR smart waits](02-bbr-smart-waits.md) for the full story.
+
+## My test passes locally but fails in CI. Help.
+
+Common causes, in order of likelihood:
+
+1. **Race condition** — replace `wait Ns` with an edge wait
+   (`wait until the URL contains "..."`,
+   `wait for ".success" to appear`, web-first matcher with
+   `within N seconds`).
+2. **Different viewport** — CI defaults differ. Pin a breakpoint:
+   `Given I set the viewport to the "desktop" breakpoint`.
+3. **Different browser** — set `BROWSER=firefox npm test` locally to
+   reproduce.
+4. **CI is slower** — bump the budget on smart waits explicitly,
+   `Then "<#dashboard>" should be visible within 15 seconds`.
+5. **Auth state expired** — re-run the auth-setup feature.
+
+## How do I see what the browser is doing?
+
+```bash
+npm run test:headed        # opens a real browser, slow-mo 800ms
+HEADLESS=false npm test    # same, default slow-mo
+```
+
+Failed scenarios save a PNG under `screenshots/failed_*.png`. The
+filename embeds the feature, scenario line, and timestamp.
+
+## How do I run a single feature / scenario?
+
+```bash
+# One feature.
+npx cucumber-js tests/features/login.feature
+
+# One scenario by name match.
+npx cucumber-js --name "Successful login"
+
+# Tagged scenarios.
+npx cucumber-js --tags "@critical"
+npx cucumber-js --tags "@critical and not @flaky"
+```
+
+## How do I skip a scenario without deleting it?
+
+Tag it `@wip` and run with `--tags "not @wip"`. Or use a `Cucumber`
+disabled step prefix (`Skip:` is not standard; tags are).
+
+## How do I share setup between scenarios?
+
+```gherkin
+Feature: Admin dashboard
+
+  Background:
+    Given I restore the auth state from "tests/auth/admin.json"
+     And I am on "/admin"
+
+  Scenario: Lists users
+    Then I should see "Users"
+
+  Scenario: Lists products
+    When I follow "Products"
+    Then I should see "Products"
+```
+
+The `Background:` block runs before every scenario in the file. Keep
+it short — 3-5 lines.
+
+## How do I parameterise a scenario?
+
+```gherkin
+Scenario Outline: Login fails with bad input
+  Given I am on "/login"
+  When I fill in "Email" with "<email>"
+   And I fill in "Password" with "<password>"
+   And I press "Sign in"
+  Then I should see "<error>"
+
+  Examples:
+    | email           | password | error                      |
+    | not-an-email    | secret   | Email is not valid         |
+    |                 | secret   | Email is required          |
+    | a@b.c           |          | Password is required       |
+```
+
+Each row becomes a separate scenario.
+
+## How do I assert what the user sees, not the implementation?
+
+Avoid:
+
+```gherkin
+Then the database should have a row in users    # ❌ implementation
+```
+
+Prefer:
+
+```gherkin
+Then I should see "Welcome, Alice"               # ✅ user behaviour
+ And the URL should be "/dashboard"
+```
+
+Behaviour-tested code is refactor-friendly. Implementation-tested code
+breaks every time the schema changes.
+
+## How do I name selectors I'll reuse?
+
+In `tests/selectors/my-app.json`:
+
+```json
+{
+  "css": {
+    "primary cta": "main .hero button.cta-primary"
+  }
+}
+```
+
+Wire it in `cucumber.js`:
+
+```js
+worldParameters: {
+  selectors: { files: ['my-app.json'] }
+}
+```
+
+Then in features:
+
+```gherkin
+When I add "primary cta" selector for "main .hero button.cta-primary" css selector
+# (or skip the inline registration since the JSON file is loaded)
+Then I see visible primary cta
+```
+
+Better yet, use a CMS preset that already names the common parts —
+see [03 Selector registry](03-selector-registry.md).
+
+## How do I mock an external API?
+
+```gherkin
+Given the URL "**/api/users" returns the JSON:
+  """
+  {"users": [{"id": 1, "name": "Alice"}]}
+  """
+When I am on "/users"
+Then "<#user-list>" should have a count of 1 within 5 seconds
+```
+
+Full reference: [06 Networking & dialogs](06-network-and-dialogs.md).
+
+## How do I test as a logged-in user without retyping the login?
+
+One-time setup feature saves the session. Every other feature restores it.
+
+```gherkin
+@auth-setup
+Scenario: Save admin auth state
+  Given I am on "/login"
+  When I fill in "Email" with "admin@example.com"
+   And I fill in "Password" with "..."
+   And I press "Sign in"
+   And I wait until the URL contains "/dashboard"
+  Then I save the auth state to "tests/auth/admin.json"
+```
+
+Run once: `npx cucumber-js --tags @auth-setup`.
+
+In every other feature:
+
+```gherkin
+Background:
+  Given I restore the auth state from "tests/auth/admin.json"
+```
+
+Saves 1-3 seconds per scenario. Full reference: [07 Auth state](07-auth-state.md).
+
+## How do I run accessibility audits?
+
+```gherkin
+Scenario: Page passes WCAG AA
+  Given I am on "/checkout"
+  Then the page should pass an accessibility audit at level "AA"
+```
+
+Layered approach in [10 Accessibility](10-accessibility.md). Combine
+custom probes (heading order, skip link, ARIA validity) with axe-core
+full audits.
+
+## How do I make CI fast?
+
+```bash
+SLOW_MO=0 npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky
+```
+
+Set `--parallel 4` (or however many cores) to fan scenarios across
+processes. Each scenario gets its own browser context — no shared
+state, safe to parallelise.
+
+## I want AI to write tests for me.
+
+Read [12 AI agent guide](12-ai-agent-guide.md) and follow the
+Test-Drive-Develop loop: human writes the feature file (the
+specification), AI implements code, tests verify. The varbase-e2e
+suite is the validation layer that prevents AI from "looking right"
+while doing the wrong thing.
+
+For a structured prompt template, see Recipe AI-1 in that page.