Learn Playwright: Movies App

Appearance

Agent guide (humans and AI) ​

House style for Playwright work in this repository. Full learning path: Testing guide and hands-on labs on the course home. AI tool choice: AI testing.

Learning: open a coding agent on this repo and say which module you are on (for example, "I'm on 01") using the learn-lab-coach skill. Do not teach Codegen or an IDE Testing UI as the course path.

Maintainer QA: after changing learn/, say “dogfood the learn path” to use the learn-dogfood skill (docs walk, fresh clone setup, practice steps), or the thin prompt learn-dogfood.prompt.md on GitHub. That is not learner coaching.

Preferred tool path ​

  1. Coding agents writing or fixing tests: npx playwright cli + movies-playwright / playwright-cli / playwright-trace skills; traces when debugging.
  2. Structured coverage: Playwright test agents: planner, generator, healer (thin prompts in .github/prompts/ on GitHub).
  3. MCP: persistent explore / official agent tool loops; not required for every small edit.
  4. Regenerate official agents/skills after Playwright upgrades (--loop=vscode is definition format, not “use VS Code”):
bash
npx playwright init-agents --loop=vscode --prompts   # also: claude, copilot, codex, opencode
npx playwright init-skills --loop=agents             # → .agents/skills (adds official playwright-* skills)
npx playwright init-skills --loop=claude             # → .claude/skills

After init-skills --loop=claude: re-copy or restore the teaching skills movies-playwright, learn-lab-coach, and learn-dogfood into .claude/skills/ if the command overwrote that folder. They are not regenerated by Playwright.

Project teaching skills (keep across regenerations): movies-playwright, learn-lab-coach, learn-dogfood.

Style contract ​

  • Locators: getByRole, getByLabel, getByText with accessible names. Avoid CSS/XPath as the primary strategy.
  • Assertions: web-first (toBeVisible, toHaveText, toHaveURL, toHaveCount, toMatchAriaSnapshot).
  • Forbidden: waitForTimeout, force: true, waitForLoadState('networkidle'), sync .count() for waits.
  • List tests: import test / expect from tests/helpers/list-fixtures.ts and request the lightest fixture (emptyListPage → listWithMoviesPage → listPage).
  • Reuse tests/helpers/list-utilities.ts (createList, addMovie, openLists, selectCoverImage, …).
  • Prefer helpers and list fixtures. One optional POM teaching example lives at tests/pages/search-page.ts and tests/logged-out/lessons/pom-search.spec.ts (logged-out search only). Do not POM list flows.
  • Prefer test.step for multi-step flows so traces stay readable.
  • Generated suites: tag with @agent. Learn style from manage-lists-*, not from dense @agent coverage.
  • Seeds and plans must reference tests/logged-in/seed.spec.ts and list-fixtures, not deprecated list-test.ts.
  • Do not use Codegen / the test recorder as the authoring path.

Healing ​

  • Inspect a trace or live snapshot before changing locators.
  • Prefer fixing the test or app over skipping.
  • test.fixme() only with a comment of observed vs expected behavior when the product is wrong.

Review checklist ​

See the rubric in AI testing.