Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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.md
index 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
## Prerequisites
Before 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):
```bash
npm install -g @playwright/cli@latest
playwright-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 skills
Coding 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 --extension
This 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 Next
diff --git a/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md b/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md
index 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-cli
description: 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`:
```bash
npx --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:
```bash
npm install -g @playwright/cli@latest
diff --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.md
index 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/TS
PLAYWRIGHT_HTML_OPEN=never npx playwright test
-
-# Run all tests through a custom npm script
PLAYWRIGHT_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/TS
PLAYWRIGHT_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 -s
playwright-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 location
where 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.