playwright-ts-template

Playwright + TypeScript starter for end-to-end test automation, with AI agent skills for Claude Code, Cursor, GitHub Copilot and Codex generated by wico-playwright-agent-skills (wico is the npm package name; the repository is qualiow-playwright-skills) and by Playwright itself.

What you get

• Playwright 1.64 with a config that loads .env, uses sensible timeouts, retries and traces on CI, and produces one merged HTML report from sharded runs.
• Page Object Model example (src/pages/home.page.ts), a fixtures file (src/fixtures/test-fixture.ts) that hands page objects to the tests, and an example spec that runs against https://playwright.dev (replace it with your own specs; a live third-party site is a flake source in CI).
• ESLint 10 with type-aware rules (typescript-eslint recommendedTypeChecked, so an un-awaited page action or assertion fails lint; eslint-plugin-playwright), Prettier, tsc --noEmit.
• GitHub Actions: a lint job, a two-shard test matrix, a merge job publishing the HTML report, and a Docker job that builds the image and runs the suite inside it.
• Dockerfile on the official Playwright image, pinned by tag and digest (CI checks the tag equals the installed @playwright/test version).
• Four agent skills, regenerated by one command and checked for drift in CI:
  • playwright-e2e — how to plan, write, debug and review tests in this project (wico).
  • playwright-cli, playwright-trace, playwright-component-testing — Playwright's official skills.

The tests target https://playwright.dev as a demo; point them at your application with BASE_URL.

Requirements

• Node.js ≥ 24 (.nvmrc pins 24.22, the version the Playwright Docker image ships; nvm use picks it up). .npmrc sets engine-strict, so older versions are refused at install.
• Docker only if you want to run the suite in a container.
• Recommended: the Playwright Test for VS Code extension (test explorer, trace viewer, locator picker).

Getting started

Click Use this template on GitHub (or clone the repository), then:

nvm use
npm ci                 # dependencies only — no browser download on install
npm run pw:setup       # installs the Playwright browsers (+ OS deps on Linux)
cp .env.example .env   # optional: BASE_URL for your application
npm test

Or, with the Makefile: make install && make test.

Running tests

Command	What it does
npm test	All projects (chromium, firefox, webkit), headless
npm run test:chromium	Chromium only
npm run test:headed	Visible browser
npm run test:ui	Playwright UI mode
npm run test:debug	Playwright inspector
npx playwright test --grep @smoke	Only tests tagged @smoke
npm run report	Open the last local HTML report
npm run report:merge	Merge blob reports from ./all-blob-reports into HTML

Every npm script has a make equivalent (make help lists them).

Debugging with an AI agent

npx playwright test --debug=cli pauses the test and prints a playwright-cli attach … command; the playwright-cli and playwright-trace skills teach the agent that loop, and .claude/skills/playwright-e2e/references/agent-debugging.md describes the workflow used in this project.

Docker

make docker-build   # docker build -t playwright-ts-template .
make docker-test    # runs the suite inside the image (--init --ipc=host), copies the HTML report to ./playwright-report, exits with the suite's status

The image is mcr.microsoft.com/playwright:v<version>-noble, where the version is the installed @playwright/test; the CI lint job fails when the two disagree, and the docker CI job builds the image and runs the suite in it. The FROM line also pins the image digest; Dependabot updates it. Tests run as the image's unprivileged pwuser, and BASE_URL from the host is passed through.

CI

.github/workflows/tests.yml runs on pushes to main and on every pull request:

1. lint — eslint, tsc --noEmit, prettier --check, npm run skills:check (generated skills must be in sync) and the Dockerfile tag check. No browsers are installed here.
2. test — a two-shard matrix (--shard=N/2), each uploading a blob report. Set a repository variable BASE_URL to test your application instead of the demo target.
3. merge-reports — downloads the blobs and publishes a single playwright-report artifact (7 days).
4. docker — builds the image from the Dockerfile and runs the whole suite inside it with make docker-test.

Report artifacts and sensitive data. Traces and HAR files record request headers (cookies, authorization), response bodies and screenshots of the application under test; videos show it on screen. On a public repository anyone signed in to GitHub can download workflow artifacts. Once BASE_URL points at a real application, keep the repository private, or drop the playwright-report upload and rely on the github reporter annotations instead.

Environment variables

playwright.config.ts loads a local .env (Node's process.loadEnvFile()); CI passes variables directly.

Variable	Description	Default
BASE_URL	Application base URL used by page.goto('/')	https://playwright.dev
CI	Set by CI: enables retries, forbids test.only, switches reporters	–

AI agent skills

npm run skills:sync    # regenerate everything below
npm run skills:check   # what CI runs: sync, then fail if anything changed

Path	Owner	Purpose
.claude/skills/playwright-e2e/, .agents/skills/playwright-e2e/	wico-playwright-agent-skills (init --platforms claude,cursor,copilot --packs core,templates)	Operating workflow, shared conventions (MUST/SHOULD/WON'T), delegation rules; test planning, generation, debugging, review; page-object and project conventions; fixtures/auth, locators/assertions, CI and flake triage, API testing, pass-rate analysis
.cursor/rules/playwright-e2e.mdc, .github/instructions/playwright-e2e.instructions.md, .github/copilot-instructions.md	wico	Cursor and Copilot pointers to the shared skill
.claude/skills/playwright-cli/, .agents/skills/playwright-cli/	npx playwright init-skills	Driving a browser and debugging tests with playwright-cli
.claude/skills/playwright-trace/, .agents/skills/playwright-trace/	npx playwright init-skills	Analysing traces with npx playwright trace
.claude/skills/playwright-component-testing/, .agents/…	npx playwright init-skills	Component testing

After creating a project from the template, search the playwright-e2e references for <!-- YOUR PROJECT: ... --> markers and fill in the details that are yours (application areas, test users, data strategy). Re-running skills:sync keeps those files — wico only rewrites what it generates.

Project structure

playwright-ts-template/
├── src/
│   ├── fixtures/              # test-fixture.ts: `test` extended with page-object fixtures, re-exports `expect`
│   ├── pages/                 # Page objects (*.page.ts) — components/ for shared pieces
│   ├── tests/                 # Specs (*.spec.ts) — import `test` and `expect` from `@fixtures/test-fixture`
│   ├── helpers/               # Utilities
│   └── test-data/             # Static test data
├── .claude/skills/            # Claude Code skills (playwright-e2e + official Playwright skills)
├── .agents/skills/            # The same skills for Cursor, Codex and Copilot
├── .cursor/rules/             # Cursor pointer rule
├── .github/
│   ├── workflows/tests.yml    # lint · sharded tests · merged report · docker
│   ├── instructions/          # Copilot pointer
│   └── copilot-instructions.md
├── playwright.config.ts
├── eslint.config.mjs · .prettierrc · tsconfig.json
├── Dockerfile · .dockerignore
├── Makefile
└── CHANGELOG.md

tsconfig.json declares the aliases @fixtures/*, @pages/*, @tests/*, @helpers/* and @test-data/*; Playwright resolves them.

Code quality

npm run lint          # eslint .
npm run lint:fix
npm run format        # prettier . --write
npm run format:check
npm run typecheck     # tsc --noEmit

Prettier and ESLint skip the generated skill directories — their formatting belongs to the generators.

Dependency updates

Dependabot (.github/dependabot.yml) opens weekly PRs for npm packages (minor and patch bumps grouped, @playwright/test on its own), the GitHub Actions (pinned to commit SHAs) and the Docker base image. A @playwright/test bump fails CI on purpose until the same PR also bumps the Dockerfile tag and re-runs npm run skills:sync.

.npmrc sets ignore-scripts=true (lifecycle scripts never run on install; npm run … and npx are unaffected) and engine-strict=true (installs refuse a Node version outside engines).

License

MIT