Playwright · API reference · all subjects

out of scope - ci/cd integration

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Playwright CLI storage state save command

The playwright-cli state-save command saves the complete browser state including cookies and storage. It can be called with no arguments to save to an auto-generated filename (storage-state-{timestamp}.json) or with a specific filename argument.

Playwright CLI storage state load command

The playwright-cli state-load command restores storage state from a file, loading cookies and localStorage from a previously saved storage state file.

playwright-cli generates TypeScript code from actions

Every action performed with playwright-cli generates corresponding Playwright TypeScript code. The code appears in the output and can be copied directly into test files. For example, filling a form field with playwright-cli fill generates an await page.getByRole() statement.

Seed test purpose in Playwright test generation

A seed test is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start after the seed. The --debug=cli debugger pauses inside the seed test, so the seed is where every planning and generation session begins.

Using fixtures to share setup across tests

The preferred pattern is to push navigation into a fixture so scenario tests reuse it. Import the custom test instance from a fixtures file (e.g., './fixtures') and extend the base test, yielding the page after custom setup. This avoids duplication across scenario tests.

Test file organization rules

One test per file. File path, describe name, and test name come verbatim from the spec minus the ordinal. Prefix each numbered step with a // N. <step text> comment before its actions. Use the describe group name verbatim from the spec without the ordinal.

playwright-cli commands for exploration and code generation

Key playwright-cli commands include: playwright-cli snapshot to see element structure; playwright-cli fill <ref> "value" to fill form fields; playwright-cli click <ref> to click elements; playwright-cli press <key> to send keyboard input; playwright-cli generate-locator <ref> to produce a locator expression; playwright-cli eval "<js>" <ref> to evaluate JavaScript; playwright-cli console to see app errors; playwright-cli requests to view network requests.

Spec file structure for test planning

Spec files should be saved under specs/<feature>.plan.md. The structure includes: Feature Test Plan heading, Application Overview section with one paragraph, Test Scenarios section with numbered groups, each group containing Seed reference and numbered scenarios. Each scenario includes: File path, Steps list with numbered user-level steps, each step followed by expect bullets for observable outcomes.

Scenario naming and structure rules

Each scenario is independent and starts from the seed's fresh state; never chain scenarios. Scenario names use kebab-case and match the test file name (e.g., should-add-single-todo → should-add-single-todo.spec.ts). Write steps at the user level (Type 'Buy milk' into the input), not the API level (call fill). Cover happy path, edge cases, validation, negative flows, and persistence.

Seed test must be run through test runner, not directly opened

Always go through the test to capture any custom setup done there. Do not just open the app URL with playwright-cli directly, as this skips custom setup in the seed test.

Generate scenarios sequentially not in parallel

When generating multiple scenarios, process them one at a time, restarting the seed between each so every test starts from a clean page. Never generate scenarios in parallel as scenarios share the seed session.

Common causes of test failures during heal phase

Common causes of failing tests include: selector drift, new wrapper element, label or ARIA rename, timing issues (transitions, async loads), assertion text updated in the app, and test data leaking between runs.

Never use sleep or networkidle as test fixes

When fixing failing tests, never skip hooks or add sleeps as a fix. Never use networkidle in tests.

Spec reconciliation after test fixes

After fixing a test, open the spec and locate the matching scenario. If the fix was purely technical (locator drift, better assertion shape) and the spec's user-level behaviour still matches the app, leave the spec alone. If the fix changed user-visible steps, inputs, order, or expected outcomes that the spec describes, update the spec to match reality while keeping the scenario id and file path stable.

Playwright workspace prerequisites

Before test generation, check the workspace has Playwright installed by running: test -f playwright.config.ts || test -f playwright.config.js or npx --no-install playwright --version. If no Playwright install exists, bootstrap one with npm init playwright@latest.

Using --raw flag with playwright-cli commands

The --raw flag can be used with playwright-cli commands like generate-locator and eval to produce raw output suitable for use in assertions. For example, playwright-cli --raw generate-locator <ref> produces just the locator expression, and playwright-cli --raw eval "<js>" <ref> produces just the evaluated result.

playwright-cli attach for interactive debugging

Run playwright test with --debug=cli in the background, then use playwright-cli attach tw-XXXX (where XXXX is the session name) to drive the paused page interactively. The session name appears in the Debugging Instructions output.

PLAYWRIGHT_HTML_OPEN environment variable

Set PLAYWRIGHT_HTML_OPEN=never when running Playwright tests with --debug=cli to prevent the HTML report from opening automatically.

Give your agent this brain