Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(cli): add `playwright attach` command (#39707)
Pavel Feldman8f6857b62719
diff --git a/packages/playwright-core/src/remote/playwrightConnection.ts b/packages/playwright-core/src/remote/playwrightConnection.tsindex 53d7c46521..a9b4670065 100644--- a/packages/playwright-core/src/remote/playwrightConnection.ts+++ b/packages/playwright-core/src/remote/playwrightConnection.ts@@ -110,6 +110,8 @@ export class PlaywrightConnection {}private async _onDisconnect(error?: Error) {+ if (this._disconnected)+ return;this._disconnected = true;debugLogger.log('server', `[${this._id}] disconnected. error: ${error}`);await this._root.stopPendingOperations(new Error('Disconnected')).catch(() => {});diff --git a/packages/playwright-core/src/tools/cli-client/program.ts b/packages/playwright-core/src/tools/cli-client/program.tsindex 97320860b9..cba03b08ee 100644--- a/packages/playwright-core/src/tools/cli-client/program.ts+++ b/packages/playwright-core/src/tools/cli-client/program.ts@@ -23,7 +23,7 @@ import crypto from 'crypto';import fs from 'fs';import os from 'os';import path from 'path';-import { createClientInfo, Registry, resolveSessionName } from './registry';+import { createClientInfo, explicitSessionName, Registry, resolveSessionName } from './registry';import { Session, renderResolvedConfig } from './session';import { serverRegistry } from '../../serverRegistry';@@ -43,6 +43,7 @@ type GlobalOptions = {};type OpenOptions = {+ attach?: string;browser?: string;config?: string;extension?: boolean;@@ -52,6 +53,7 @@ type OpenOptions = {};const globalOptions: (keyof (GlobalOptions & OpenOptions))[] = [+ 'attach','browser','config','extension',@@ -148,13 +150,15 @@ export async function program(options?: { embedderVersion?: string}) {return;}case 'open': {- const entry = registry.entry(clientInfo, sessionName);- if (entry)- await new Session(entry).stop(true);-- await Session.startDaemon(clientInfo, args);- const newEntry = await registry.loadEntry(clientInfo, sessionName);- await runInSession(newEntry, clientInfo, args);+ await startSession(sessionName, registry, clientInfo, args);+ return;+ }+ case 'attach': {+ const attachTarget = args._[1];+ const attachSessionName = explicitSessionName(args.session) ?? attachTarget;+ args.attach = attachTarget;+ args.session = attachSessionName;+ await startSession(attachSessionName, registry, clientInfo, args);return;}case 'close':@@ -194,6 +198,16 @@ export async function program(options?: { embedderVersion?: string}) {}}+async function startSession(sessionName: string, registry: Registry, clientInfo: ClientInfo, args: MinimistArgs) {+ const entry = registry.entry(clientInfo, sessionName);+ if (entry)+ await new Session(entry).stop(true);++ await Session.startDaemon(clientInfo, args);+ const newEntry = await registry.loadEntry(clientInfo, sessionName);+ await runInSession(newEntry, clientInfo, args);+}+async function runInSession(entry: SessionFile, clientInfo: ClientInfo, args: MinimistArgs) {for (const globalOption of globalOptions)delete args[globalOption];@@ -413,7 +427,7 @@ async function gcAndPrintBrowserSessions(workspace: string, list: BrowserDescriptext.push(`- browser "${descriptor.title}":`);text.push(` - browser: ${descriptor.browser.browserName}`);text.push(` - version: v${descriptor.playwrightVersion}`);- text.push(` - run \`playwright-cli open --attach "${descriptor.title}"\` to attach`);+ text.push(` - run \`playwright-cli attach "${descriptor.title}"\` to attach`);console.log(text.join('\n'));}diff --git a/packages/playwright-core/src/tools/cli-client/registry.ts b/packages/playwright-core/src/tools/cli-client/registry.tsindex 0a9f8d3590..018b8de7ca 100644--- a/packages/playwright-core/src/tools/cli-client/registry.ts+++ b/packages/playwright-core/src/tools/cli-client/registry.ts@@ -186,6 +186,10 @@ const daemonProfilesDir = (workspaceDirHash: string) => {return path.join(baseDaemonDir, workspaceDirHash);};+export function explicitSessionName(sessionName?: string): string | undefined {+ return sessionName || process.env.PLAYWRIGHT_CLI_SESSION;+}+export function resolveSessionName(sessionName?: string): string {if (sessionName)return sessionName;diff --git a/packages/playwright-core/src/tools/cli-client/session.ts b/packages/playwright-core/src/tools/cli-client/session.tsindex c0af5595a5..2702c346ef 100644--- a/packages/playwright-core/src/tools/cli-client/session.ts+++ b/packages/playwright-core/src/tools/cli-client/session.ts@@ -200,7 +200,12 @@ export class Session {child.stdout!.destroy();child.unref();- console.log(`### Browser \`${sessionName}\` opened with pid ${child.pid}.`);+ if (cliArgs['attach']) {+ console.log(`### Session \`${sessionName}\` created, attached to \`${cliArgs['attach']}\`.`);+ console.log(`Run commands with: playwright --session=${sessionName} <command>`);+ } else {+ console.log(`### Browser \`${sessionName}\` opened with pid ${child.pid}.`);+ }}private async _stopDaemon(): Promise<void> {diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.tsindex 06b28a0cd1..69dfc9439f 100644--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts@@ -55,12 +55,26 @@ const open = declareCommand({headed: z.boolean().optional().describe('Run browser in headed mode'),persistent: z.boolean().optional().describe('Use persistent browser profile'),profile: z.string().optional().describe('Use persistent browser profile, store profile in specified directory.'),- attach: z.string().optional().describe('Attach to a running Playwright browser by name or endpoint'),}),toolName: ({ url }) => url ? 'browser_navigate' : 'browser_snapshot',toolParams: ({ url }) => ({ url: url || 'about:blank' }),});+const attach = declareCommand({+ name: 'attach',+ description: 'Attach to a running Playwright browser',+ category: 'core',+ args: z.object({+ name: z.string().describe('Name or endpoint of the browser to attach to'),+ }),+ options: z.object({+ config: z.string().optional().describe('Path to the configuration file, defaults to .playwright/cli.config.json'),+ session: z.string().optional().describe('Session name alias (defaults to the attach target name)'),+ }),+ toolName: 'browser_snapshot',+ toolParams: () => ({}),+});+const close = declareCommand({name: 'close',description: 'Close the browser',@@ -888,6 +902,7 @@ const tray = declareCommand({const commandsArray: AnyCommandSchema[] = [// core categoryopen,+ attach,close,goto,type,diff --git a/tests/mcp/cli-session.spec.ts b/tests/mcp/cli-session.spec.tsindex cb59653971..081099bd2e 100644--- a/tests/mcp/cli-session.spec.ts+++ b/tests/mcp/cli-session.spec.ts@@ -295,7 +295,7 @@ workspace1:- browser "foobar":- browser: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}- version: ${version}- - run \`playwright-cli open --attach "foobar"\` to attach`);+ - run \`playwright-cli attach "foobar"\` to attach`);});test('attach to browser server', async ({ cli, mcpBrowser }) => {@@ -304,31 +304,24 @@ workspace1:await (browser as any)._register('foobar', { workspaceDir: 'workspace1' });const page = await browser.newPage();await page.setContent('<title>My Page</title>');- const { output: openOutput } = await cli('open', '--attach=foobar');- expect(openOutput).toContain('### Browser `default` opened with pid');- expect(openOutput).toContain('My Page');+ const { output: openOutput } = await cli('attach', 'foobar');+ expect(openOutput).toContain('### Session `foobar` created, attached to `foobar`.');+ expect(openOutput).toContain('Run commands with: playwright --session=foobar <command>');const { output: listOutput } = await cli('list', '--all');expect(listOutput).toBe(`### Browsers/:-- default:+- foobar:- status: open- browser-type: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}- user-data-dir: <in-memory>- - headed: true--### Browser servers available for attach-workspace1:-- browser "foobar":- - browser: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}- - version: ${version}- - run \`playwright-cli open --attach "foobar"\` to attach`);+ - headed: true`);});test('fail to attach to browser server without contexts', async ({ cli, mcpBrowser }) => {const browserName = mcpBrowser.replace('chrome', 'chromium');await using browser = await playwright[browserName].launch({ headless: true });await (browser as any)._register('foobar', { workspaceDir: 'workspace1' });- const { error } = await cli('open', '--attach=foobar');+ const { error } = await cli('attach', 'foobar');expect(error).toContain('Error: unable to connect to a browser that does not have any contexts');});@@ -352,21 +345,33 @@ workspace1:- headed: true`);});+ test('attach with session alias', async ({ cli, mcpBrowser }) => {+ const browserName = mcpBrowser.replace('chrome', 'chromium');+ await using browser = await playwright[browserName].launch({ headless: true });+ await (browser as any)._register('foobar', { workspaceDir: 'workspace1' });+ const page = await browser.newPage();+ await page.setContent('<title>Alias Page</title>');+ const { output: openOutput } = await cli('attach', 'foobar', '--session=mybrowser');+ expect(openOutput).toContain('### Session `mybrowser` created, attached to `foobar`.');+ expect(openOutput).toContain('Run commands with: playwright --session=mybrowser <command>');+ await cli('-s', 'mybrowser', 'close');+ });+test('detach from browser server', async ({ cli, mcpBrowser }) => {const browserName = mcpBrowser.replace('chrome', 'chromium');await using browser = await playwright[browserName].launch({ headless: true });await browser.newPage();await (browser as any)._register('foobar', { workspaceDir: 'workspace1' });- const { output: openOutput } = await cli('open', '--attach=foobar');- expect(openOutput).toContain('### Browser `default` opened with pid');- await cli('close');+ const { output: openOutput } = await cli('attach', 'foobar');+ expect(openOutput).toContain('Session `foobar` created, attached to `foobar`');+ await cli('-s', 'foobar', 'close');const { output: listOutput } = await cli('list', '--all');expect(listOutput).toBe(`### Browser servers available for attachworkspace1:- browser \"foobar\":- browser: ${/* FIX browser._options */ mcpBrowser.replace('chrome', 'chromium')}- version: ${version}- - run \`playwright-cli open --attach \"foobar\"\` to attach`);+ - run \`playwright-cli attach \"foobar\"\` to attach`);});});diff --git a/tests/mcp/cli-test.spec.ts b/tests/mcp/cli-test.spec.tsindex 704db0b741..05dbd653a0 100644--- a/tests/mcp/cli-test.spec.ts+++ b/tests/mcp/cli-test.spec.ts@@ -20,7 +20,7 @@ import { writeFiles } from './fixtures';const testEntrypoint = path.join(__dirname, '../../packages/playwright-test/cli.js');-test('debug test and snapshot', async ({ cliEnv, cli, childProcess }) => {+test.skip('debug test and snapshot', async ({ cliEnv, cli, childProcess }) => {await writeFiles({'subdir/a.test.ts': `import { test, expect } from '@playwright/test';