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 -g flag to install skills globally (#42099)
Pavel Feldman19630696cbe0
diff --git a/docs/src/getting-started-cli.md b/docs/src/getting-started-cli.mdindex e577933724..6c99fccbe5 100644--- a/docs/src/getting-started-cli.md+++ b/docs/src/getting-started-cli.md@@ -42,6 +42,12 @@ Coding agents like Claude Code and GitHub Copilot can use locally installed skilplaywright-cli install --skills```+To share the skills across all your projects, add the `-g` flag to install them into your home directory (`~/.claude/skills` or, with `--skills=agents`, `~/.agents/skills`):++```bash+playwright-cli install --skills -g+```+### Skills-less operationYou can also point your agent at the CLI directly and let it discover commands on its own:diff --git a/packages/playwright-core/src/tools/cli-client/output.ts b/packages/playwright-core/src/tools/cli-client/output.tsindex 1972f1862a..7dc38f04b5 100644--- a/packages/playwright-core/src/tools/cli-client/output.ts+++ b/packages/playwright-core/src/tools/cli-client/output.ts@@ -57,6 +57,7 @@ export interface Output {errorDetachNotAttached(session: string): never;errorBrowserNotOpenForTool(session: string): never;errorAttachNoTarget(): never;+ errorInstallGlobalRequiresSkills(): never;list(data: ListData): void;closeAll(sessions: string[]): void;@@ -126,6 +127,11 @@ export class TextOutput implements Output {return process.exit(1);}+ errorInstallGlobalRequiresSkills(): never {+ console.error(`Error: --global requires --skills`);+ return process.exit(1);+ }+list({ all, browsers, servers, channelSessions }: ListData): void {const byWorkspace = new Map<string, ListedBrowser[]>();for (const browser of browsers) {@@ -307,6 +313,11 @@ export class JsonOutput implements Output {return process.exit(1);}+ errorInstallGlobalRequiresSkills(): never {+ this._emit({ isError: true, error: `--global requires --skills` });+ return process.exit(1);+ }+list({ all, browsers, servers, channelSessions }: ListData): void {const payload: Record<string, unknown> = { browsers };if (all) {diff --git a/packages/playwright-core/src/tools/cli-client/program.ts b/packages/playwright-core/src/tools/cli-client/program.tsindex 6a087c48c1..ef0e82a34f 100644--- a/packages/playwright-core/src/tools/cli-client/program.ts+++ b/packages/playwright-core/src/tools/cli-client/program.ts@@ -65,8 +65,9 @@ const globalOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions))[] = ['session',];-const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean }))[] = [+const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean, g?: boolean }))[] = ['all',+ 'g','help','json','raw',@@ -85,6 +86,11 @@ export async function program(options?: { embedderVersion?: string}) {args.session = args.s;delete args.s;}+ // Normalize -g alias to --global+ if (args.g) {+ args.global = true;+ delete args.g;+ }const output: Output = args.json ? new JsonOutput() : new TextOutput();const commandName = args._?.[0];@@ -196,6 +202,8 @@ export async function program(options?: { embedderVersion?: string}) {return;}case 'install':+ if (args.global && !args.skills)+ output.errorInstallGlobalRequiresSkills();await runInitWorkspace(args, output);output.installed();return;@@ -315,7 +323,11 @@ async function runInSessionOrStop(entry: SessionFile, clientInfo: ClientInfo, arasync function runInitWorkspace(args: MinimistArgs, output: Output) {const cliPath = libPath('entry', 'cliDaemon.js');- const daemonArgs: string[] = [cliPath, '--init-workspace', ...(args.skills ? ['--init-skills', String(args.skills)] : [])];+ const daemonArgs: string[] = [+ cliPath,+ '--init-workspace',+ ...(args.skills ? [args.global ? '--init-skills-global' : '--init-skills', String(args.skills)] : []),+ ];await new Promise<void>((resolve, reject) => {const child = spawn(process.execPath, daemonArgs, {stdio: output.installStdio(),diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.tsindex 53cd564285..f1312ee5f9 100644--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts@@ -1114,6 +1114,7 @@ const install = declareCommand({args: z.object({}),options: z.object({skills: z.string().optional().describe('Install skills, possible values: claude (default), agents.'),+ global: z.boolean().optional().describe('Install skills into the home directory instead of the workspace (alias: -g). Requires --skills.'),}),toolName: '',toolParams: () => ({}),diff --git a/packages/playwright-core/src/tools/cli-daemon/program.ts b/packages/playwright-core/src/tools/cli-daemon/program.tsindex b57ce32118..07c216829a 100644--- a/packages/playwright-core/src/tools/cli-daemon/program.ts+++ b/packages/playwright-core/src/tools/cli-daemon/program.ts@@ -45,10 +45,11 @@ export function decorateProgram(program: Command) {.option('--endpoint <endpoint>', 'attach to a running Playwright browser endpoint').option('--init-workspace', 'initialize workspace').option('--init-skills <value>', 'install skills for the given agent type ("claude" or "agents")')+ .option('--init-skills-global <value>', 'install skills for the given agent type ("claude" or "agents") into the home directory').action(async (sessionName: string, options: any) => {if (options.initWorkspace) {- await initWorkspace(options.initSkills);+ await initWorkspace(options.initSkills, options.initSkillsGlobal);return;}@@ -85,16 +86,20 @@ function globalConfigFile(): string {return path.join(process.env['PWTEST_CLI_GLOBAL_CONFIG'] ?? os.homedir(), '.playwright', 'cli.config.json');}-export async function initWorkspace(initSkills: string | undefined) {- const cwd = process.cwd();- const playwrightDir = path.join(cwd, '.playwright');- await fs.promises.mkdir(playwrightDir, { recursive: true });- console.log(`✅ Workspace initialized at \`${cwd}\`.`);+export async function initWorkspace(initSkills: string | undefined, initSkillsGlobal?: string) {+ const globalSkills = !!initSkillsGlobal;+ if (!globalSkills) {+ const cwd = process.cwd();+ const playwrightDir = path.join(cwd, '.playwright');+ await fs.promises.mkdir(playwrightDir, { recursive: true });+ console.log(`✅ Workspace initialized at \`${cwd}\`.`);+ }- if (initSkills) {- const target = initSkills === 'agents' ? 'agents' : 'claude';+ const skills = initSkillsGlobal ?? initSkills;+ if (skills) {+ const target = skills === 'agents' ? 'agents' : 'claude';try {- await installSkills(['playwright-cli'], target);+ await installSkills(['playwright-cli'], target, { global: globalSkills });} catch (error) {console.error('❌', error instanceof Error ? error.message : error);// eslint-disable-next-line no-restricted-properties@@ -102,7 +107,8 @@ export async function initWorkspace(initSkills: string | undefined) {}}- await ensureConfiguredBrowserInstalled();+ if (!globalSkills)+ await ensureConfiguredBrowserInstalled();}async function ensureConfiguredBrowserInstalled() {diff --git a/packages/playwright-core/src/tools/utils/installSkills.ts b/packages/playwright-core/src/tools/utils/installSkills.tsindex 43d4978a69..4bcea607c2 100644--- a/packages/playwright-core/src/tools/utils/installSkills.ts+++ b/packages/playwright-core/src/tools/utils/installSkills.ts@@ -17,6 +17,7 @@/* eslint-disable no-console */import fs from 'fs';+import os from 'os';import path from 'path';import { libPath } from '../../package';@@ -26,14 +27,15 @@ export const allSkills = ['playwright-cli', 'playwright-component-testing', 'plaexport type SkillName = typeof allSkills[number];export type SkillTarget = 'claude' | 'agents';-export async function installSkills(skills: readonly SkillName[], target: SkillTarget = 'claude') {+export async function installSkills(skills: readonly SkillName[], target: SkillTarget = 'claude', options?: { global?: boolean }) {const cwd = process.cwd();+ const baseDir = options?.global ? os.homedir() : cwd;for (const skill of skills) {const sourceDir = libPath('tools', 'skills', skill);if (!fs.existsSync(sourceDir))throw new Error(`Skill source directory not found: ${sourceDir}`);- const destDir = path.join(cwd, `.${target}`, 'skills', skill);+ const destDir = path.join(baseDir, `.${target}`, 'skills', skill);await fs.promises.cp(sourceDir, destDir, { recursive: true });- console.log(`✅ Skill installed to \`${path.relative(cwd, destDir)}\`.`);+ console.log(`✅ Skill installed to \`${options?.global ? destDir : path.relative(cwd, destDir)}\`.`);}}diff --git a/tests/mcp/cli-misc.spec.ts b/tests/mcp/cli-misc.spec.tsindex 67ba1e0040..750f34c1a5 100644--- a/tests/mcp/cli-misc.spec.ts+++ b/tests/mcp/cli-misc.spec.ts@@ -60,6 +60,32 @@ test('install workspace w/--skills=agents', async ({ cli }, testInfo) => {expect(fs.existsSync(skillFile)).toBe(true);});+test('install w/--skills -g installs into the home directory', async ({ cli }, testInfo) => {+ const fakeHome = testInfo.outputPath('fake-home');+ await fs.promises.mkdir(fakeHome, { recursive: true });+ const { output } = await cli('install', '--skills', '-g', { env: { HOME: fakeHome, USERPROFILE: fakeHome } });+ expect(output).toContain('Skill installed to');+ expect(output).not.toContain('Workspace initialized');++ const skillFile = path.join(fakeHome, '.claude', 'skills', 'playwright-cli', 'SKILL.md');+ expect(fs.existsSync(skillFile)).toBe(true);+});++test('install w/--skills=agents --global installs into the home directory', async ({ cli }, testInfo) => {+ const fakeHome = testInfo.outputPath('fake-home');+ await fs.promises.mkdir(fakeHome, { recursive: true });+ await cli('install', '--skills=agents', '--global', { env: { HOME: fakeHome, USERPROFILE: fakeHome } });++ const skillFile = path.join(fakeHome, '.agents', 'skills', 'playwright-cli', 'SKILL.md');+ expect(fs.existsSync(skillFile)).toBe(true);+});++test('install -g without --skills errors', async ({ cli }) => {+ const result = await cli('install', '-g');+ expect(result.exitCode).toBe(1);+ expect(result.error).toContain('--global requires --skills');+});+test('install handles browser detection', async ({ cli }) => {const { output } = await cli('install');// Verify that one of the browser detection outcomes occurred