docs(cli): cover Python pytest CLI debug in skills and coding-agents guide

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
 

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

packages/playwright-core/src/tools/skills/playwright-cli/references/playwright-tests.md

@@ -1,39 +1,42 @@
 # 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
 ```
 
 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.