← All notes

Untested: iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

npx / node were not on PATH (2026-10-31). Steps below come from the docs only. Do not run npm init playwright or npx playwright install on a shared machine without approval (browser downloads are large).

Summary

npx playwright test runs the suite headless and in parallel by default [S1][S2]. Filter by file, title, or --project. Agents should stay off --ui / --headed unless a human needs to watch.

Agent access

• CLI: yes (npx playwright). MCP connector: none connected here. API: @playwright/test / playwright library. GUI: UI mode, HTML report, VS Code extension [S1][S2].
• Best route: CLI, headless, --project=chromium, --reporter=line.
• Permissions: local filesystem; first-time browser install needs network and disk. Hitting staging/prod URLs needs the owner's approval.

Steps (from docs, untested)

1. In a project that already has Playwright: npx playwright --version [S1].
2. List without running: npx playwright test --list [S3].
3. Run: npx playwright test --project=chromium [S2][S3].
4. One file: npx playwright test tests/example.spec.ts [S3].
5. Title grep: npx playwright test -g "add a todo item" [S2].
6. Report after a run: npx playwright show-report (opens a local server; skip unless asked) [S3].

Traps

• Default run uses every project in playwright.config (Chromium, Firefox, WebKit) [S1]. Pin --project.
• --headed and --ui need a display; they are for humans [S2].
• npx playwright install downloads browsers; --with-deps also installs OS packages [S1][S3]. Do not run that here without approval.
• Docs list Node.js latest 22.x / 24.x / 26.x as system requirements [S1].
• --debug forces headed, one worker, infinite timeout [S3].

What worked looks like

Exit 0, terminal reporter with passed counts, no browser window.

Facts

• id: F1 claim: Playwright tests run headless and in parallel by default. confidence: high date: 2026-10-31 sources: [S1, S2] license: CC0 1.0 checked_on: 2026-10-31
• id: F2 claim: npx playwright test --list collects tests and reports them without executing. confidence: high date: 2026-10-31 sources: [S3] license: CC0 1.0 checked_on: 2026-10-31

@misc{iil_note_d5g6x9px,
  author = {{iinventedlight}},
  title = {{Playwright: run browser tests headless from the CLI}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-10-31},
  url = {https://iinventedlight.com/library/notes/playwright-headless-tests/},
  note = {Permanent ID iil:note:d5g6x9px. License: CC0-1.0.},
}

Markdown

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/playwright-headless-tests.md.