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 generate-locator command (#40313)
Dmitry Gozman91e034e183df
diff --git a/packages/playwright-cli-stub/playwright-cli-stub.js b/packages/playwright-cli-stub/playwright-cli-stub.jsindex d33211f9be..59772a7ce8 100755--- a/packages/playwright-cli-stub/playwright-cli-stub.js+++ b/packages/playwright-cli-stub/playwright-cli-stub.js@@ -15,7 +15,7 @@* limitations under the License.*/-const { program } = require('playwright-core/lib/coreBundle').cli;+const { program } = require('playwright-core/lib/tools/cli-client/program');program().catch(e => {console.error(e.message);diff --git a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md b/packages/playwright-core/src/tools/cli-client/skill/SKILL.mdindex 8a22932e73..bd4fdc308a 100644--- a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md+++ b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md@@ -162,6 +162,9 @@ playwright-cli video-stop# wait for the user to pick an element in the browser, print its ref and locatorplaywright-cli pick+# generate a Playwright locator for an element from its ref or selector+playwright-cli generate-locator e5 --raw+# show a persistent highlight overlay for an element, optionally with a custom styleplaywright-cli highlight e5playwright-cli highlight e5 --style="outline: 3px dashed red"diff --git a/packages/playwright-core/src/tools/cli-client/skill/references/test-generation.md b/packages/playwright-core/src/tools/cli-client/skill/references/test-generation.mdindex 7a09df387f..a045c55d6e 100644--- a/packages/playwright-core/src/tools/cli-client/skill/references/test-generation.md+++ b/packages/playwright-core/src/tools/cli-client/skill/references/test-generation.md@@ -77,12 +77,58 @@ playwright-cli click e5### 3. Add Assertions Manually-Generated code captures actions but not assertions. Add expectations in your test:+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:++- `toBeVisible()` — element is rendered and visible+- `toHaveText(text)` — element text content matches+- `toHaveValue(value) / toBeEmpty()` — input/select value matches+- `toBeChecked() / toBeUnchecked()` — checkbox state matches+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot++Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.++When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.++Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.++```bash+# Get a stable locator for an element ref to use in the assertion+playwright-cli --raw generate-locator e5+# getByRole('button', { name: 'Submit' })++# Capture expected text content for toHaveText+playwright-cli --raw eval "el => el.textContent" e5++# Capture expected input value for toHaveValue/toBeEmpty+playwright-cli --raw eval "el => el.value" e5++# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked+# (whole page, or use a ref to scope to a region)+playwright-cli --raw snapshot+playwright-cli --raw snapshot e5+``````typescript// Generated actionawait page.getByRole('button', { name: 'Submit' }).click();-// Manual assertion-await expect(page.getByText('Success')).toBeVisible();+// Manual assertions using the outputs above:+await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();+await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');+await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('[email protected]');+await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();++// toMatchAriaSnapshot on the whole page, finds a matching region+await expect(page).toMatchAriaSnapshot(`+ - heading "Welcome, user"+ - link /\\d+ new messages?/+ - button "Sign out"+`);++// toMatchAriaSnapshot scoped to a region+await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`+ - link "Home"+ - link /\\d+ new messages?/+ - link "Profile"+`);```diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.tsindex 34dd5da7ec..9267dc725d 100644--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts@@ -354,6 +354,17 @@ const pick = declareCommand({toolParams: () => ({}),});+const generateLocator = declareCommand({+ name: 'generate-locator',+ description: 'Generate a Playwright locator for the given element',+ category: 'devtools',+ args: z.object({+ target: z.string().describe(elementTargetDescription),+ }),+ toolName: 'browser_generate_locator',+ toolParams: ({ target }) => ({ target }),+});+const highlight = declareCommand({name: 'highlight',description: 'Show (or with --hide, remove) a highlight overlay for an element; `--hide` without a target hides all page highlights.',@@ -1075,6 +1086,7 @@ const commandsArray: AnyCommandSchema[] = [resume,stepOver,pick,+ generateLocator,highlight,// session categorydiff --git a/tests/mcp/cli-devtools.spec.ts b/tests/mcp/cli-devtools.spec.tsindex 4f190104c8..9fc80b456f 100644--- a/tests/mcp/cli-devtools.spec.ts+++ b/tests/mcp/cli-devtools.spec.ts@@ -207,6 +207,15 @@ test('pick activates dashboard session', async ({ cdpServer, cli, server, startDexpect(output).toContain(`locator: getByRole('button', { name: 'Submit' })`);});+test('generate-locator', async ({ cli, server }) => {+ server.setContent('/', `<button>Submit</button>`, 'text/html');+ await cli('open', server.PREFIX);+ await cli('snapshot');++ const { output } = await cli('generate-locator', 'e2', '--raw');+ expect(output).toContain(`getByRole('button', { name: 'Submit' })`);+});+test('highlight', async ({ cdpServer, cli, server }) => {server.setContent('/', `<button>Submit</button>`, 'text/html');const browserContext = await cdpServer.start();