Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 5 additions & 30 deletions docs/src/getting-started-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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` |
Expand All @@ -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

Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -1,42 +1,39 @@
# 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
```

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.