Playwright CLI - the day-to-day commands

1First-day CLI - init, install, test, show-report

Four commands that get a brand-new project from zero to a green test against TTACart. Memorise these; you'll type them every time you bootstrap a new repo.

npm init playwright@latest walks you through a wizard - TS vs JS, GitHub Actions yes/no, browsers chromium/firefox/webkit. The output is a complete repo: tests/, playwright.config.ts, tsconfig.json, and a .gitignore that excludes node_modules and test-results. The --with-deps flag on install installs OS-level libraries (helpful on Linux CI runners that don't ship X11 dependencies by default).

2Codegen - record selectors + actions

A browser opens, you click around, Playwright writes the spec for you. Best for two things: learning the locator API (you see what selector Playwright would pick), and bootstrapping a draft spec against a brand-new page.

Codegen picks locators in a defined order: getByRole first, then getByLabel, then getByText, with CSS as a last resort. Treat the generated file as a draft - rename it, extract page objects, dedupe waits, fold into a real spec. It is not production code, it is a transcript of what you did.

3Trace viewer - npx playwright show-trace

A standalone DevTools-like viewer for a Playwright trace.zip. Time-travel through every action, see the DOM at each step, replay network calls, watch the console. The single most useful tool for debugging flakes.

Configure trace capture in playwright.config.ts via use: { trace: 'on-first-retry' }. on-first-retry is the production default (capture trace only when a retry runs) - it keeps your test-results folder small but still ships you the data you need when something goes wrong. The viewer also runs at trace.playwright.dev if you want to share a trace with a teammate over Slack.

4Headed + debug mode

Run with a visible browser, step through with the Playwright Inspector, drop a page.pause() to break right before the spot you care about. The fastest local debugging loop in browser automation.

--debug opens the Playwright Inspector window alongside the test - you see the spec on the left, the browser on the right, and a step-over button at the top. Drop await page.pause() anywhere in your spec to set a breakpoint without restarting the run. --slowmo=500 inserts a half-second delay between every action - useful for recording screencasts, not for actual debugging (it just hides race conditions).

5Sharding + parallelism

Two knobs control how much of the suite runs at once. --workers=N sets in-process parallelism. --shard=k/n sets cross-process / cross-CI-job parallelism.

--workers is local parallelism inside one CLI invocation. Use it on your laptop, use it on a single CI runner. --shard=1/4 is for splitting the suite across four separate CI jobs - each job runs a quarter of the specs in parallel. You collect the four blob reports and run merge-reports to get a single combined HTML output.

6Filters - --grep, --project, --reporter

Run only the specs you care about. --grep filters by name, --project filters by browser / device, --reporter picks the output format.

Tag specs with strings in the title - test('add to cart @smoke', ...) - then --grep '@smoke' selects them. --grep-invert is its mirror - useful for "run everything except known-flakes on a hotfix branch". --project matches the name field from playwright.config.ts's projects array, so you can ship a green chromium pipeline while iterating on a flaky firefox case.

7UI mode - npx playwright test --ui

A long-running watcher that re-runs specs on file change, lets you time-travel through actions, edit + re-run inline, and pin watch on a single test. The replacement for "save, switch terminal, type, hit up-arrow".

UI mode is the right default for local dev. You launch it once at the start of your morning, change a spec, hit Cmd-S, and Playwright re-runs only the affected test. Failed runs show the same trace viewer panels you'd get from show-trace - same time-travel, same DOM snapshots, same network panel - inline. Use the Pick Locator button to grab a selector from any DOM snapshot frame.

8Updating snapshots - visual regression

Playwright captures screenshots and DOM snapshots; expect(page).toHaveScreenshot() compares against a baseline. When the UI legitimately changes, you regenerate the baselines with --update-snapshots.

Visual regression is the most-mistaken use case for Playwright. Two rules: (1) update snapshots only when the UI change is intentional - and review the resulting diff in the PR like any other code change. (2) Cap maxDiffPixels so that a 1-pixel anti-aliasing difference doesn't fail your CI. Anti-aliasing differs between OS versions, so visual specs that pass on a dev Mac may fail on a Linux CI runner.

9Reports - html, json, allure-playwright

Playwright ships HTML, JSON, JUnit, line, list, dot, and blob reporters out of the box. Plus community add-ons (allure-playwright, ortoni-report). Pick the right reporter for the right consumer.

html for humans, json for dashboards, junit for CI surface (GitHub Actions picks junit up automatically and renders it in the Checks tab), blob for sharded runs that need merging. list / line / dot are terminal-only and useful in CI logs. Custom reporters live in our own framework - see the Advance framework page for the CustomTTAReporter.ts walkthrough.

10CI integration - GitHub Actions, Jenkins, Docker

Running the same CLI inside CI as you do locally. Three patterns: GitHub Actions matrix + sharding, Jenkins pipeline + parallel stages, and Docker image for any-runner reproducibility.

The official mcr.microsoft.com/playwright image ships every browser preinstalled and pinned to a Playwright version. Match the image tag to your @playwright/test version - mismatches cause "executable doesn't exist at ..." errors at runtime. In GitHub Actions, a 4-shard matrix runs 4 parallel jobs that each upload a blob reporter artefact, then a final merge-reports job stitches them together.

Two mini-projects (scope only)

The lecture batch ships two CLI-focused projects. The directions are summarised here; the actual code lives in your own repo - this is the "what should I build" spec, not a copy of the upstream project.

Diagrams - command tree and CI pipeline

Two mermaid diagrams. First: the npx playwright command tree, grouped by use case. Second: a sharded CI pipeline that uses 6 of the commands above.

flowchart TB
  ROOT[npx playwright] --> SETUP[setup]
  ROOT --> AUTHOR[author]
  ROOT --> RUN[run]
  ROOT --> DEBUG[debug]

  SETUP --> S1[init]
  SETUP --> S2[install]
  SETUP --> S3[install --with-deps]

  AUTHOR --> A1[codegen url]
  AUTHOR --> A2[codegen --device]
  AUTHOR --> A3[codegen --save-storage]

  RUN --> R1[test]
  RUN --> R2[test --workers N]
  RUN --> R3[test --shard k/n]
  RUN --> R4[test --grep tag]
  RUN --> R5[test --project name]
  RUN --> R6[test --reporter list]
  RUN --> R7[merge-reports]

  DEBUG --> D1[test --headed]
  DEBUG --> D2[test --debug]
  DEBUG --> D3[test --ui]
  DEBUG --> D4[show-trace zip]
  DEBUG --> D5[show-report]

  classDef setup fill:#fef3c7,stroke:#f59e0b,color:#111
  classDef author fill:#fde68a,stroke:#d97706,color:#111
  classDef run fill:#d1fae5,stroke:#16a34a,color:#111
  classDef debug fill:#ede9fe,stroke:#8b5cf6,color:#111
  class S1,S2,S3 setup
  class A1,A2,A3 author
  class R1,R2,R3,R4,R5,R6,R7 run
  class D1,D2,D3,D4,D5 debug
            

flowchart LR
  PUSH[git push] --> CI[GitHub Actions]
  CI --> M[matrix.shard=1..4]

  M --> J1[Job 1
test --shard=1/4
--reporter=blob]
  M --> J2[Job 2
test --shard=2/4
--reporter=blob]
  M --> J3[Job 3
test --shard=3/4
--reporter=blob]
  M --> J4[Job 4
test --shard=4/4
--reporter=blob]

  J1 --> UP[upload artefact]
  J2 --> UP
  J3 --> UP
  J4 --> UP

  UP --> MERGE[merge-reports
--reporter=html]
  MERGE --> ART[final HTML artefact]
  ART --> PR[PR comment + link]

  classDef ci fill:#d1fae5,stroke:#16a34a,color:#111
  classDef art fill:#fef9c3,stroke:#f59e0b,color:#111
  class J1,J2,J3,J4,MERGE ci
  class UP,ART,PR art