Skip to content
Closed
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
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,18 @@ playwright-cli close # close the browser
playwright-cli delete-data # delete user data for default session
```

Extension sessions control only their own tabs and place them in a tab group. Use a session name
and color to tell groups apart:

```bash
playwright-cli attach --extension=chrome --session=finance --session-color=blue
playwright-cli -s=finance goto https://example.com
playwright-cli -s=finance detach --close-tabs
```

By default, `detach` leaves the tabs open. For extension sessions, `--close-tabs` closes all tabs
of the session, including tabs the user selected when connecting, but leaves other tabs open.

### Snapshots

After each command, playwright-cli provides a snapshot of the current browser state.
Expand Down
28 changes: 14 additions & 14 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,12 @@
"test": "playwright test"
},
"devDependencies": {
"@playwright/test": "1.66.0-alpha-1794252756000",
"@playwright/test": "1.66.0-alpha-2026-11-16",
"@types/node": "^25.2.1"
},
"dependencies": {
"playwright": "1.66.0-alpha-1794252756000",
"playwright-core": "1.66.0-alpha-1794252756000"
"playwright": "1.66.0-alpha-2026-11-16",
"playwright-core": "1.66.0-alpha-2026-11-16"
},
"bin": {
"playwright-cli": "playwright-cli.js"
Expand Down
12 changes: 8 additions & 4 deletions skills/playwright-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -285,8 +285,12 @@ playwright-cli open --persistent
# Use persistent profile with custom directory
playwright-cli open --profile=/path/to/profile

# Connect to browser via Playwright Extension
playwright-cli attach --extension=chrome
# Connect to the browser profile of the user via Playwright Extension (chrome, msedge, ...).
# The session name is the title of the tab group; pick a color to tell sessions apart.
playwright-cli attach --extension=chrome --session=finance --session-color=blue
playwright-cli -s=finance goto https://example.com
# Detach and close the tabs of the session, when the user does not need them
playwright-cli -s=finance detach --close-tabs

# Connect to a running Chrome or Edge by channel name
playwright-cli attach --cdp=chrome
Expand Down Expand Up @@ -403,7 +407,7 @@ playwright-cli kill-all

Package installation and custom `npm` scripts may require separate approval.

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`. It needs Playwright 1.59 or newer:

```bash
npx --no-install playwright --version
Expand Down Expand Up @@ -484,7 +488,7 @@ See [references/pr-attachments.md](references/pr-attachments.md) for alt text, i
* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
* **Running Playwright code** [references/running-code.md](references/running-code.md)
* **Browser session management** [references/session-management.md](references/session-management.md)
* **Browser session management, attaching to the browser of the user** [references/session-management.md](references/session-management.md)
* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
* **Test generation (plan / generate / heal)** [references/test-generation.md](references/test-generation.md)
* **Tracing** [references/tracing.md](references/tracing.md)
Expand Down
35 changes: 32 additions & 3 deletions skills/playwright-cli/references/session-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,12 +143,41 @@ playwright-cli attach --cdp=http://localhost:9222

### Attach via browser extension

Connect to a browser with the Playwright extension installed:
Connect to the everyday browser profile of the user: their tabs, logins and cookies. The browser must have the Playwright Extension installed. Name the browser, because the extension can be in Edge and not in Chrome:

```bash
playwright-cli attach --extension
playwright-cli attach --extension=chrome
playwright-cli attach --extension=msedge
```

When the extension is not installed in that browser, `attach` fails with `Playwright Extension not found in "<profile path>"`. Try the other browser, or ask the user to install the extension.

The session controls only its own tabs: the tabs that the user picked on the connect page, and the tabs that the session opened. The extension puts them into a tab group. Give the session a name for the task, and optionally a color:

```bash
# The tab group has the title "finance" and the color blue.
# Colors: blue, red, yellow, green, pink, purple, cyan, orange.
playwright-cli attach --extension=msedge --session=finance --session-color=blue

# Each next command names the session
playwright-cli -s=finance goto https://example.com
playwright-cli -s=finance snapshot
```

Without `--session`, the session has the name of the browser (`chrome`, `msedge`). Without `--session-color`, the group takes the first color that no other session uses. Pass `--no-tab-group` to leave the tabs where the user has them.

When the work is done, detach. The browser of the user keeps running:

```bash
# Leave the tabs open. The tab group stays and turns gray, and the user can continue in it.
playwright-cli -s=finance detach

# Close the tabs of the session. Use it to clean up tabs that the user does not need any more.
playwright-cli -s=finance detach --close-tabs
```

`--close-tabs` closes all tabs of the session, also the tabs that the user picked for it. It never closes other tabs of the user.

### Detach

Tear down an attached session without affecting the external browser:
Expand All @@ -161,7 +190,7 @@ playwright-cli detach
playwright-cli -s=msedge detach
```

`detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`.
`detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`. `detach --close-tabs` only works on sessions created via `attach --extension`.

## Default Browser Session

Expand Down
18 changes: 16 additions & 2 deletions tests/integration.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,12 @@ async function runCli(args: string[], env: Record<string, string> = {}): Promise
});
}

test('open data URL', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-cli/issues/502' } }, async ({}) => {
test('open data URL', {
annotation: [
{ type: 'issue', description: 'https://github.com/microsoft/playwright-cli/issues/502' },
{ type: 'issue', description: 'https://github.com/microsoft/playwright-cli/issues/540' },
],
}, async ({}) => {
const argumentError = "boolean option '--headed' should not be passed with '=value', use '--headed' or '--no-headed' instead";
expect(await runCli(['open', '--headed=false'])).toEqual({
output: '',
Expand All @@ -121,11 +126,20 @@ test('open data URL', { annotation: { type: 'issue', description: 'https://githu
exitCode: 1,
});

expect(await runCli(['open', 'data:text/html,hello', '--persistent'])).toEqual(expect.objectContaining({
const browsersPath = test.info().outputPath('empty-browsers');
expect(await runCli(['open', 'data:text/html,hello', '--persistent'], {
PLAYWRIGHT_BROWSERS_PATH: browsersPath,
})).toEqual(expect.objectContaining({
output: expect.stringContaining('hello'),
exitCode: 0,
}));

const missingFfmpeg = await runCli(['video-start', 'video.webm']);
expect(missingFfmpeg.output).toContain('FFmpeg is not installed');
expect(missingFfmpeg.output).toContain(`expected executable at ${browsersPath}`);
expect(missingFfmpeg.output).toContain('playwright-cli install-browser ffmpeg');
expect(missingFfmpeg.output).not.toContain('npx playwright install ffmpeg');

expect(await runCli(['--json', 'screenshot', '--filename'])).toEqual({
output: JSON.stringify({ isError: true, error: "error: '--filename' option: expected string, received boolean" }, null, 2),
error: '',
Expand Down
Loading