A self-paced, hands-on workshop that teaches modern end-to-end testing with Cucumber + Playwright against a real, fully-functional reference app. You write features, step definitions, page objects, and fixtures — and watch a real browser drive a real full-stack app.
Target audience: developers new to E2E testing, or comfortable with Playwright but new to BDD and modern patterns like API-seeded data, storage state, and parallel isolation.
apps/api/— a NestJS REST API (users, projects, tasks, JWT auth) backed by SQLite via Prisma. Seeds itself with dev users on boot. Exposes an env-guarded/test/*seam for fast E2E fixture creation.apps/web/— a React + Vite + Tailwind app. Master-detail project management UI (projects list → detail with inline task CRUD, users list + detail, login/profile).apps/web-e2e/— the E2E project. Built withplaywright-bdd, which compiles Gherkin.featurefiles into Playwright tests. 53 scenarios, parallel-safe, finishes in ~30s.modules/— the workshop itself. 12 modules, each a focused README that walks you from empty E2E suite to full reference suite.docs/concepts.md— high-level reference of every pattern used in the suite, with links to where each pattern lives in the code.
New to git or E2E testing? Read the gentle, step-by-step participant workflow guide first. It walks through your first module from "I just cloned the repo" to "my tests are green," with no assumed git knowledge.
# 1. Install Node 20 (matches .nvmrc)
nvm install 20 && nvm use 20
# 2. Install dependencies
npm ci
# 3. Install Playwright browsers (one-time, ~150MB)
npx playwright install chromiumYou're already on main. The tip of main is the opinionated reference: the complete app + the complete E2E suite, post-curriculum polish included. Tag 12-complete marks the canonical "workshop graduate" state — that's what your work should resemble when you finish the modules. Tags 00-setup through 12-complete are the 25 checkpoints between "starting point" and "graduate."
To start the workshop, run npm run module:begin 00. The script handles the git mechanics for you.
npm startBoots the API on http://localhost:3000 and the web app on http://localhost:4200. Open http://localhost:4200 and sign in:
| Password | Role | |
|---|---|---|
admin@example.com |
Admin123! |
admin |
alice@example.com |
Password1! |
member |
bob@example.com |
Password1! |
member |
If you can log in and see the projects list, you're ready. Ctrl+C stops the servers.
npm run e2e— run the E2E suite (auto-boots api + web)npm run e2e:smoke— quick sanity subsetnpm run e2e:auth/:projects/:tasks/:users— single feature areanpm run e2e:ui— Playwright's interactive UI modenpm run e2e:headed— watch the tests drive a visible browsernpm run e2e:report— open the HTML report from the last runnpm run e2e:flaky— reproduce the deliberate flake demo (Module 09)npm run db:reset— wipe + reseed the dev database
13 modules numbered 00 through 12. Each module is a 30–60 minute focused chunk. Module 00 is environment setup (no code). Modules 01–12 each have you write a small piece of the test suite.
Each module has two git tags (think: named bookmarks):
NN-start— the state you begin in. The reference app is fully working; the test code you're about to write is missing.NN-complete— the canonical answer key. Compare against this when you're done.
Per-module loop:
# 1. Begin the module — drops you into a fresh `my/03` branch from 03-start
npm run module:begin 03
# 2. Read modules/03-fixtures-hooks-world/README.md and follow the walkthrough.
# Run your tests as you go:
npm run e2e -- --grep @module-03
# 3. When green, see how the canonical answer compares:
npm run module:compare 03
# 4. Move to the next module. Your `my/03` branch stays — come back any time.
npm run module:begin 04Other useful commands:
npm run module:status— where am I right now?npm run module:reset 03— discard my work on this module, start over
The module:* scripts are thin wrappers around git. You can do the same with raw git if you prefer — see the participant workflow guide for equivalents and recovery recipes.
| # | Module | What you build |
|---|---|---|
| 00 | Setup & app tour | Verify the environment, explore the app |
| 01 | First feature + step defs | login.feature — 2 scenarios, green |
| 02 | Page objects + locator strategy | LoginPage, BasePage, refactor steps to POM |
| 03 | Fixtures, hooks, world | scenarioWorld, seedUser fixture, cleanup |
| 04 | Tagging, outlines, data tables | @smoke, Scenario Outline, ` |
| 05 | Auth & storage state | storageState per role, login-once-per-worker |
| 06 | API + UI hybrid | Seed data via /test/seed/*, assert via UI |
| 07 | Network mocking | page.route stubs: slow, error, offline |
| 08 | Custom commands / step composition | Given I am logged in as {role} |
| 09 | Parallel, retries, flake | fullyParallel, --repeat-each, the @flaky demo |
| 10 | Debugging | UI mode, trace viewer, test.step(), page.pause() |
| 11 | Reporting | HTML report, cucumber JSON, optional Allure |
| 12 | Env config + capstone | .env/config, write a feature solo |
Total time: a focused pass through all 12 modules takes 6–10 hours. Do it over a couple of evenings or a weekend.
If you want the "why behind the patterns" without following the modules linearly:
→ docs/concepts.md — every pattern in the suite, with pointers to the actual files.
| Layer | Pick |
|---|---|
| Monorepo | Nx 22 |
| Node | 20 LTS (pinned via .nvmrc + engines) |
| API | NestJS 11 + Prisma 6 + SQLite + JWT + class-validator |
| Web | React 19 + Vite + Tailwind v4 + react-router |
| E2E | @playwright/test + playwright-bdd (compiles .feature → Playwright tests) |
| Browser | Chromium only (multi-browser matrix is out of scope for v1) |
| Platform | macOS + Linux first-class; Windows via WSL2 |
Build-time scaffolding (PLAN.md, etc.) lives under _internal/ — it's preserved for the curious, not for users.
MIT. See LICENSE.