TypeScript End-to-End Testing

An e2e test proves the whole stack works together the way a user experiences it: the browser, the Next.js app, Supabase, and Stripe all in one flow. These are the tests that catch "the button does nothing" and "checkout 500s on deploy" — things unit and API tests miss. They're also the slowest and flakiest, so the craft is in writing flows that are stable: resilient selectors, explicit waits on state, and no reliance on timing.

Setup

If the project has no Playwright yet, scaffold it:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/e2e/scaffold.sh

This installs @playwright/test, drops a playwright.config.ts tuned for Next.js + Vercel preview URLs (reads BASE_URL, retries on CI, traces on first retry), and creates e2e/ with a fixtures file. If Playwright already exists, skip the scaffold and just add specs under the existing test dir.

Writing stable tests

The difference between a test suite people trust and one they ignore is flakiness. Follow these because each one removes a class of flake:

• Select by role or test id, not CSS. getByRole('button', { name: /book now/i })

survives restyling; .btn-primary-2 does not. Add data-testid to elements that have no accessible name. Selectors coupled to layout are the #1 source of flake.

• Wait on state, never on time. Use web-first assertions

(await expect(page.getByText('Booking confirmed')).toBeVisible()) which auto-retry. Never waitForTimeout — it's either too short (flake) or too long (slow suite).

• Isolate auth. Log in once in a setup project and reuse storageState so each

test starts authenticated without re-running the login UI. See the fixtures file.

• Own your test data. Create the listing/booking the test needs (via API or a

seed) and tear it down, so tests don't depend on each other or on prod data.

The booking flow — the spec that matters most

Wanderlust Stays' core journey. Encode it as one readable test:

1. Search a destination + dates from the homepage.
2. Open a listing from results.
3. Select dates and proceed to checkout.
4. Complete payment using Stripe test mode (card 4242 4242 4242 4242, any

future expiry, any CVC). Handle the Stripe iframe with frameLocator.

1. Assert the confirmation page shows the booking reference, and (optionally) that

the booking now appears in the user's trips.

See references/playwright.md for a complete annotated example of this flow, including how to drive the Stripe Elements iframe and how to stub it when you only want to test the app's own logic.

Running

npx playwright test                 # all specs, headless
npx playwright test booking         # one flow
npx playwright test --ui            # interactive debugging
BASE_URL=https://<preview>.vercel.app npx playwright test   # against a deploy

Report results plainly: which flows passed, which failed, and for a failure point the user at the trace (npx playwright show-trace) rather than guessing.

When to hand off to the agent

For "build a full e2e suite" or "test all the critical flows", delegate to the e2e-test-runner agent — it maps the app's routes, scaffolds Playwright, writes the specs, runs them, and returns a pass/fail report with traces for failures.