Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore(cli): make skill discoverable from `--help` (#40274)

Simon Knottef8a6bb0f041
diff --git a/.claude/skills/playwright-dev/dashboard.md b/.claude/skills/playwright-dev/dashboard.md
index adf51b4880..60d255468e 100644
--- a/.claude/skills/playwright-dev/dashboard.md
+++ b/.claude/skills/playwright-dev/dashboard.md
@@ -32,6 +32,6 @@ npx playwright cli video-stop
# afterwards, use ffmpeg to turn the video into mp4 for sharing.
```
-For using Playwright CLI, refer to the `packages/playwright-core/src/tools/cli-client/skill/SKILL.md` skill.
+For more about using Playwright CLI, look at `npx playwright cli --help` and the referenced Skill.
While developing in in this repo, it's important to use `npx playwright cli` instead of `playwright-cli`.
diff --git a/packages/playwright-core/src/cli/program.ts b/packages/playwright-core/src/cli/program.ts
index 63b7f6b228..59a95c3b06 100644
--- a/packages/playwright-core/src/cli/program.ts
+++ b/packages/playwright-core/src/cli/program.ts
@@ -239,6 +239,7 @@ export function decorateProgram(program: Command) {
.command('cli', { hidden: true })
.allowExcessArguments(true)
.allowUnknownOption(true)
+ .helpOption(false)
.action(async options => {
process.argv.splice(process.argv.indexOf('cli'), 1);
cliProgram().catch(logErrorAndExit);
diff --git a/packages/playwright-core/src/tools/cli-client/DEPS.list b/packages/playwright-core/src/tools/cli-client/DEPS.list
index 086f0c0e74..e67b27a71f 100644
--- a/packages/playwright-core/src/tools/cli-client/DEPS.list
+++ b/packages/playwright-core/src/tools/cli-client/DEPS.list
@@ -7,6 +7,7 @@
./output.ts
./session.ts
./registry.ts
+./utils.ts
[output.ts]
"strict"
@@ -30,3 +31,6 @@
[minimist.ts]
"strict"
+
+[utils.ts]
+"strict"
diff --git a/packages/playwright-core/src/tools/cli-client/program.ts b/packages/playwright-core/src/tools/cli-client/program.ts
index 606ab7b98c..83067b5709 100644
--- a/packages/playwright-core/src/tools/cli-client/program.ts
+++ b/packages/playwright-core/src/tools/cli-client/program.ts
@@ -20,11 +20,13 @@ import { execSync, spawn } from 'child_process';
import crypto from 'crypto';
import os from 'os';
+import path from 'path';
import { listChannelSessions } from './channelSessions';
import { JsonOutput, TextOutput } from './output';
import { clientKey, createClientInfo, explicitSessionName, Registry, resolveSessionName } from './registry';
import { Session } from './session';
+import { isCodingAgent } from './utils';
import { libPath } from '../../package';
import { serverRegistry } from '../../serverRegistry';
import { minimist } from './minimist';
@@ -92,8 +94,16 @@ export async function program(options?: { embedderVersion?: string}) {
}
const command = commandName && help.commands[commandName];
- if (args.help || args.h) {
- output.help(command ? command.help : 'playwright-cli - run playwright mcp commands from terminal\n\n' + help.global);
+ if (args.help || args.h || !commandName) {
+ if (command) {
+ output.help(command.help);
+ } else {
+ const lines = ['playwright-cli - run playwright mcp commands from terminal'];
+ if (isCodingAgent())
+ lines.push(`Agent skill: ${path.relative(process.cwd(), libPath('tools', 'cli-client', 'skill', 'SKILL.md'))}`);
+ lines.push(help.global);
+ output.help(lines.join('\n\n'));
+ }
process.exit(0);
}
diff --git a/packages/playwright-core/src/tools/cli-client/utils.ts b/packages/playwright-core/src/tools/cli-client/utils.ts
new file mode 100644
index 0000000000..fab068cada
--- /dev/null
+++ b/packages/playwright-core/src/tools/cli-client/utils.ts
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function guessClientName(): string {
+ if (process.env.CLAUDECODE)
+ return 'Claude Code';
+ if (process.env.COPILOT_CLI)
+ return 'GitHub Copilot';
+ return 'playwright-cli';
+}
+
+export function isCodingAgent(): boolean {
+ return !!process.env.CLAUDECODE || !!process.env.COPILOT_CLI;
+}
diff --git a/packages/playwright-core/src/tools/cli-daemon/DEPS.list b/packages/playwright-core/src/tools/cli-daemon/DEPS.list
index 2c911112cd..264a2f19da 100644
--- a/packages/playwright-core/src/tools/cli-daemon/DEPS.list
+++ b/packages/playwright-core/src/tools/cli-daemon/DEPS.list
@@ -2,6 +2,7 @@
../../package.ts
../utils/socketConnection.ts
../cli-client/registry.ts
+../cli-client/utils.ts
../backend/
../mcp/
@utils/**
diff --git a/packages/playwright-core/src/tools/cli-daemon/program.ts b/packages/playwright-core/src/tools/cli-daemon/program.ts
index 39c3e54d70..66c2137767 100644
--- a/packages/playwright-core/src/tools/cli-daemon/program.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/program.ts
@@ -27,6 +27,7 @@ import { setupExitWatchdog } from '../mcp/watchdog';
import { createBrowserWithInfo } from '../mcp/browserFactory';
import * as configUtils from '../mcp/config';
import { createClientInfo } from '../cli-client/registry';
+import { guessClientName } from '../cli-client/utils';
import { registry as browserRegistry } from '../../server/registry/index';
import type { Command } from 'commander';
@@ -80,14 +81,6 @@ export function decorateProgram(program: Command) {
});
}
-function guessClientName(): string {
- if (process.env.CLAUDECODE)
- return 'Claude Code';
- if (process.env.COPILOT_CLI)
- return 'GitHub Copilot';
- return 'playwright-cli';
-}
-
function defaultConfigFile(): string {
return path.resolve('.playwright', 'cli.config.json');
}
diff --git a/tests/mcp/cli-help.spec.ts b/tests/mcp/cli-help.spec.ts
index 346ed14ce9..0b3150c82f 100644
--- a/tests/mcp/cli-help.spec.ts
+++ b/tests/mcp/cli-help.spec.ts
@@ -16,12 +16,22 @@
import { test, expect } from './cli-fixtures';
-test('prints help by default', async ({ cli }) => {
+test('prints help', async ({ cli }) => {
const { output } = await cli('--help');
expect(output).toContain('Usage: playwright-cli <command>');
});
+test('prints help by default', async ({ cli }) => {
+ const { output } = await cli();
+ expect(output).toContain('Usage: playwright-cli <command>');
+});
+
test('prints command help', async ({ cli }) => {
const { output } = await cli('click', '--help');
expect(output).toContain('playwright-cli click <target> [button]');
});
+
+test('prints agent skill path when running under a coding agent', async ({ cli }) => {
+ const { output } = await cli('--help', { env: { CLAUDECODE: '1' } });
+ expect(output).toContain('Agent skill:');
+});