---
title: "Playwright: run browser tests headless from the CLI"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/playwright-headless-tests.md
upstream_source: https://playwright.dev/docs/intro
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "Playwright docs; restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, playwright, browser, headless, tests
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "Installation"
    publisher: Playwright / Microsoft
    url: https://playwright.dev/docs/intro
    accessed: 2026-10-31
    license: "restated"
  - id: S2
    title: "Running and debugging tests"
    publisher: Playwright / Microsoft
    url: https://playwright.dev/docs/running-tests
    accessed: 2026-10-31
    license: "restated"
  - id: S3
    title: "Command line"
    publisher: Playwright / Microsoft
    url: https://playwright.dev/docs/test-cli
    accessed: 2026-10-31
    license: "restated"
---
# Playwright: run browser tests headless from the CLI

> **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