Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
docs(cli): cover Python pytest CLI debug in skills and coding-agents guide (#42165)
Simon Knottb71e999e4119
diff --git a/docs/src/getting-started-cli.md b/docs/src/getting-started-cli.mdindex 6c99fccbe5..c02edabbe1 100644--- a/docs/src/getting-started-cli.md+++ b/docs/src/getting-started-cli.md@@ -15,25 +15,30 @@ Playwright comes with `playwright-cli`, a command-line interface for browser aut## PrerequisitesBefore you begin, make sure you have the following installed:-- [Node.js](https://nodejs.org/) 20 or newer+- Playwright for your language, **or** [Node.js](https://nodejs.org/) 20+ for the standalone `@playwright/cli` package- A coding agent: Claude Code, GitHub Copilot, or similar## Installation-Install `playwright-cli` globally:+Install the standalone CLI globally (works with any language):```bashnpm install -g @playwright/cli@latestplaywright-cli --help```-Alternatively, install `@playwright/cli` as a local dependency and use `npx`:+Or use the CLI bundled with your Playwright install:```bash-npm install -D @playwright/cli@latest-npx playwright-cli --help+# JavaScript / TypeScript+npx playwright cli --help++# Python+python -m playwright cli --help```+When using a bundled entry point, replace `playwright-cli` with `npx playwright cli` or `python -m playwright cli` in the commands below.+### Installing skillsCoding agents like Claude Code and GitHub Copilot can use locally installed skills for richer context about available commands:@@ -294,11 +299,29 @@ playwright-cli attach --extensionThis requires the [Playwright Extension](https://github.com/microsoft/playwright/blob/main/packages/extension/README.md) to be installed.+## Debugging tests++Coding agents can pause a test at the start, attach with `playwright-cli`, and explore the live browser — useful for diagnosing and fixing failures.++```bash+# JavaScript / TypeScript+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli+# → Debugging Instructions with session name, e.g. tw-abcdef+playwright-cli attach tw-abcdef++# Python (pytest-playwright; -s keeps the attach line visible)+pytest --playwright-debug=cli -s+playwright-cli attach tw-abcdef+```++Keep the test running in the background while you attach. The installed skill documents this workflow for agents.+## Quick Reference| Action | Command || ------------------------- | --------------------------------------------------- || **Install CLI** | `npm install -g @playwright/cli@latest` |+| **Use bundled CLI** | `npx playwright cli …` / `python -m playwright cli …` || **Install skills** | `playwright-cli install --skills` || **Open a page** | `playwright-cli open https://example.com` || **Click an element** | `playwright-cli click e15` |@@ -308,6 +331,8 @@ This requires the [Playwright Extension](https://github.com/microsoft/playwright| **Run headed** | `playwright-cli open https://example.com --headed` || **Use Firefox** | `playwright-cli open --browser=firefox` || **Monitor sessions** | `playwright-cli show` |+| **Debug JS test** | `npx playwright test --debug=cli` |+| **Debug Python test** | `pytest --playwright-debug=cli -s` |## What's Nextdiff --git a/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md b/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.mdindex 6f34a18759..4f7970aa0d 100644--- a/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md+++ b/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md@@ -1,7 +1,7 @@---name: playwright-clidescription: Automate browser interactions, test web pages and work with Playwright tests.-allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*) Bash(pytest:*) Bash(python:*) Bash(python3:*)---# Browser Automation with playwright-cli@@ -342,13 +342,14 @@ playwright-cli kill-all## Installation-If global `playwright-cli` command is not available, try a local version via `npx playwright cli`:+If global `playwright-cli` command is not available, try a local version via `npx playwright cli` or `python -m playwright cli`:```bashnpx --no-install playwright --version+python -m playwright --version```-When local version is available, use `npx playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:+When a local version is available, use `npx playwright cli` / `python -m playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:```bashnpm install -g @playwright/cli@latestdiff --git a/packages/playwright-core/src/tools/skills/playwright-cli/references/playwright-tests.md b/packages/playwright-core/src/tools/skills/playwright-cli/references/playwright-tests.mdindex bec2ec90e4..269a23be99 100644--- a/packages/playwright-core/src/tools/skills/playwright-cli/references/playwright-tests.md+++ b/packages/playwright-core/src/tools/skills/playwright-cli/references/playwright-tests.md@@ -1,31 +1,34 @@# Running Playwright Tests-To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.+To run Playwright tests, use the project's test runner (or a package manager script). For JS/TS, set `PLAYWRIGHT_HTML_OPEN=never` to avoid opening the interactive html report.```bash-# Run all tests+# JS/TSPLAYWRIGHT_HTML_OPEN=never npx playwright test--# Run all tests through a custom npm scriptPLAYWRIGHT_HTML_OPEN=never npm run special-test-command++# Python+pytest```# Debugging Playwright Tests-To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.+To debug a failing Playwright test, run it with the CLI debug option for your runner. This pauses the test at the start and prints the debugging instructions.**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.```bash-# Run the test+# JS/TSPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli# ...# ... debugging instructions for "tw-abcdef" session ...# ...+playwright-cli attach tw-abcdef-# Attach to the test+# Python+pytest --playwright-debug=cli -splaywright-cli attach tw-abcdef```@@ -33,7 +36,7 @@ Keep the test running in the background while you explore and look for a fix.The test is paused at the start, so you should step over or pause at a particular locationwhere the problem is most likely to be.-Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.+Every action you perform with `playwright-cli` generates corresponding Playwright code.This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.After fixing the test, stop the background test run. Rerun to check that test passes.