diff --git a/docs/src/getting-started-cli.md b/docs/src/getting-started-cli.md index c02edabbe1ff2..6c99fccbe5b36 100644 --- a/docs/src/getting-started-cli.md +++ b/docs/src/getting-started-cli.md @@ -15,30 +15,25 @@ Playwright comes with `playwright-cli`, a command-line interface for browser aut ## Prerequisites Before you begin, make sure you have the following installed: -- Playwright for your language, **or** [Node.js](https://nodejs.org/) 20+ for the standalone `@playwright/cli` package +- [Node.js](https://nodejs.org/) 20 or newer - A coding agent: Claude Code, GitHub Copilot, or similar ## Installation -Install the standalone CLI globally (works with any language): +Install `playwright-cli` globally: ```bash npm install -g @playwright/cli@latest playwright-cli --help ``` -Or use the CLI bundled with your Playwright install: +Alternatively, install `@playwright/cli` as a local dependency and use `npx`: ```bash -# JavaScript / TypeScript -npx playwright cli --help - -# Python -python -m playwright cli --help +npm install -D @playwright/cli@latest +npx 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: @@ -299,29 +294,11 @@ 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` | @@ -331,8 +308,6 @@ Keep the test running in the background while you attach. The installed skill do | **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 ec4f96042439e..b7c883842d260 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:*) Bash(pytest:*) Bash(python:*) Bash(python3:*) +allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*) --- # Browser Automation with playwright-cli @@ -347,14 +347,13 @@ playwright-cli kill-all ## Installation -If global `playwright-cli` command is not available, try a local version via `npx playwright cli` or `python -m playwright cli`: +If global `playwright-cli` command is not available, try a local version via `npx playwright cli`: ```bash npx --no-install playwright --version -python -m playwright --version ``` -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: +When local version is available, use `npx 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 269a23be99295..bec2ec90e4adb 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,34 +1,31 @@ # Running Playwright Tests -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. +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. ```bash -# JS/TS +# Run all tests PLAYWRIGHT_HTML_OPEN=never npx playwright test -PLAYWRIGHT_HTML_OPEN=never npm run special-test-command -# Python -pytest +# Run all tests through a custom npm script +PLAYWRIGHT_HTML_OPEN=never npm run special-test-command ``` # Debugging Playwright Tests -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. +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. **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 -# JS/TS +# Run the test PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli # ... # ... debugging instructions for "tw-abcdef" session ... # ... -playwright-cli attach tw-abcdef -# Python -pytest --playwright-debug=cli -s +# Attach to the test playwright-cli attach tw-abcdef ``` @@ -36,7 +33,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 code. +Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript 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.