playwright-e2e-mcp 0.1.4 → 0.2.0

package/dist/tools/validate-selector.d.ts

@@ -1,31 +1,108 @@
 /**
- * Tool 5 — validate-selector: verify a CSS selector against a live page:
- * is it syntactically valid, how many elements match, and what do the
- * matches look like?
+ * Tool 5 — validate-selector: verify a selector or Playwright locator
+ * against a live page: does it parse, how many elements match (Playwright
+ * actions need exactly one), what do the matches look like, and which
+ * sturdier locator addresses the same element?
+ *
+ * Accepts CSS, every Playwright selector engine (text=, role=, xpath=, >>)
+ * and locator expressions such as getByRole('button', { name: 'Save' }).
+ * Expressions are parsed into a whitelisted call chain, never evaluated.
  */
 import { z } from 'zod';
 import type { ToolContext, ToolResponse } from '../types/index.js';
 declare const validateSelectorInput: z.ZodObject<{
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            fill: "fill";
+            goto: "goto";
+            click: "click";
+            dblclick: "dblclick";
+            hover: "hover";
+            press: "press";
+            check: "check";
+            uncheck: "uncheck";
+            select: "select";
+            wait: "wait";
+        }>;
+        locator: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     url: z.ZodString;
     selector: z.ZodString;
     projectRoot: z.ZodOptional<z.ZodString>;
-    timeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ValidateSelectorInput = z.infer<typeof validateSelectorInput>;
 export declare const validateSelectorSchema: z.ZodObject<{
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            fill: "fill";
+            goto: "goto";
+            click: "click";
+            dblclick: "dblclick";
+            hover: "hover";
+            press: "press";
+            check: "check";
+            uncheck: "uncheck";
+            select: "select";
+            wait: "wait";
+        }>;
+        locator: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     url: z.ZodString;
     selector: z.ZodString;
     projectRoot: z.ZodOptional<z.ZodString>;
-    timeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const validateSelectorTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                fill: "fill";
+                goto: "goto";
+                click: "click";
+                dblclick: "dblclick";
+                hover: "hover";
+                press: "press";
+                check: "check";
+                uncheck: "uncheck";
+                select: "select";
+                wait: "wait";
+            }>;
+            locator: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        storageState: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         url: z.ZodString;
         selector: z.ZodString;
         projectRoot: z.ZodOptional<z.ZodString>;
-        timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
     handler: (args: ValidateSelectorInput, ctx: ToolContext) => Promise<ToolResponse>;
 };

package/dist/tools/validate-selector.js

@@ -1,18 +1,29 @@
 /**
- * Tool 5 — validate-selector: verify a CSS selector against a live page:
- * is it syntactically valid, how many elements match, and what do the
- * matches look like?
+ * Tool 5 — validate-selector: verify a selector or Playwright locator
+ * against a live page: does it parse, how many elements match (Playwright
+ * actions need exactly one), what do the matches look like, and which
+ * sturdier locator addresses the same element?
+ *
+ * Accepts CSS, every Playwright selector engine (text=, role=, xpath=, >>)
+ * and locator expressions such as getByRole('button', { name: 'Save' }).
+ * Expressions are parsed into a whitelisted call chain, never evaluated.
  */
 import { z } from 'zod';
-import { assertHttpUrl, clipLines, guard, resolveProjectRoot, runBrowserScript, toolError, toolText, } from './shared.js';
+import { PlaywrightMcpError } from '../types/index.js';
+import { assertHttpUrl, bestLocator, clipLines, describePageState, guard, loginHint, pageStateShape, resolvePageState, resolveProjectRoot, runBrowserScript, toolError, toolText, } from './shared.js';
 import { assertUrlAllowed } from '../utils/url-policy.js';
+import { formatLocator, isLocatorExpression, parseLocator } from '../utils/locator-expr.js';
 const validateSelectorInput = z.object({
     url: z.string().describe('Full URL of the live page to test against (http/https)'),
-    selector: z.string().min(1).describe('CSS selector to validate'),
+    selector: z
+        .string()
+        .min(1)
+        .describe("Selector or locator, e.g. getByRole('button', { name: 'Save' })"),
     projectRoot: z
         .string()
         .optional()
-        .describe("Project whose Playwright install launches the browser; defaults to the server working directory"),
+        .describe('Project whose Playwright launches the browser (default: server root)'),
+    ...pageStateShape,
     timeoutMs: z
         .number()
         .int()
@@ -22,31 +33,49 @@ const validateSelectorInput = z.object({
         .describe('Overall limit in ms (default 45000)'),
 });
 export const validateSelectorSchema = validateSelectorInput;
-const ENGINE_RE = /^(text|xpath|id|css|pierce|nth|visible|has-text)=|>>|:has-text\(|:text\(/i;
+/** Brittle CSS: positional chains and long descendant paths break on any layout change. */
+function isBrittle(selector, chain) {
+    if (chain.length !== 1 || chain[0].method !== 'locator')
+        return false;
+    return /:nth-(of-type|child)\(|(\s>\s.*){3,}/.test(selector) || /^\/\/|^xpath=/.test(selector);
+}
+function invalid(selector, reason) {
+    return toolText([
+        `## ❌ INVALID — \`${selector}\``,
+        '',
+        `**Parse error:** \`${reason}\``,
+        '',
+        "**How to fix:** pass valid CSS (`#save`, `[data-testid=\"save\"]`), a Playwright selector (`text=Save`, `role=button[name=\"Save\"]`) or a locator (`getByRole('button', { name: 'Save' })`). Common mistakes: unescaped `#`/`.` in ids, a stray `>`, unbalanced quotes.",
+        '',
+        "Use **inspect-page** with `view: 'locators'` to see verified locators for the live elements.",
+    ].join('\n'));
+}
 export const validateSelectorTool = {
     name: 'validate-selector',
-    description: 'Check a CSS selector against a live page: syntax validity, match count, and a sample of matched elements (tag, visibility, box, text). Also flags Playwright-only selector engines (text=, xpath=, >>, :has-text()) that are not valid CSS.',
+    description: "Check a CSS selector, Playwright selector or locator (getByRole/getByTestId…, .first(), .filter()) on a live page: validity, match count (actions need exactly 1), sample matches and a sturdier verified locator for each. Accepts storageState/headers/actions.",
     inputSchema: validateSelectorSchema,
     handler: async (args, ctx) => guard('validate-selector', async () => {
         const url = assertHttpUrl(args.url);
         await assertUrlAllowed(url);
         const selector = args.selector.trim();
-        if (ENGINE_RE.test(selector)) {
-            return toolText([
-                `## ⚠️ \`${selector}\` is not a CSS selector`,
-                '',
-                'It uses a **Playwright selector engine** (`text=`, `xpath=`, `>>`, `:has-text()` …). Those are valid *inside Playwright tests* but cannot be validated as CSS here, and Playwright CSS syntax is otherwise a subset of what the browser accepts.',
-                '',
-                '**How to fix:** rewrite it as plain CSS (e.g. `text=Login` → `[role="button"]:has-text("Login")` is still Playwright-only — prefer `[data-testid="login-button"]`), then re-validate.',
-            ].join('\n'));
+        let chain;
+        try {
+            chain = parseLocator(selector);
+        }
+        catch (err) {
+            if (err instanceof PlaywrightMcpError)
+                return invalid(selector, err.message.replace(/^Cannot parse locator: /, ''));
+            throw err;
         }
         const timeoutMs = args.timeoutMs ?? 45_000;
         const root = await resolveProjectRoot(args.projectRoot, ctx);
+        const state = await resolvePageState(args, root, url, ctx);
         const outcome = await runBrowserScript({
+            ...state,
             mode: 'validate',
             projectRoot: root,
             url,
-            selector,
+            selectorChain: chain,
             gotoTimeout: Math.max(5_000, timeoutMs - 5_000),
             startedAt: Date.now(),
         }, { timeoutMs, signal: ctx.signal });
@@ -54,25 +83,26 @@ export const validateSelectorTool = {
             return toolError(outcome.kind ?? 'UNKNOWN', `Could not validate "${selector}" on ${url}: ${outcome.error ?? 'unknown error'}`, outcome.hint, outcome.stderrTail);
         }
         const data = outcome.data;
-        if (data.parseError) {
-            return toolText([
-                `## ❌ INVALID — \`${selector}\``,
-                '',
-                `**Parse error:** \`${data.parseError}\``,
-                '',
-                '**How to fix:** only CSS selectors are supported (`document.querySelectorAll` semantics). Common mistakes: unescaped `#`/`.` in ids/classes, stray `>`, or a Playwright engine prefix like `text=`.',
-                '',
-                'Use **inspect-page** to see the actual selectors of the live elements.',
-            ].join('\n'));
-        }
+        if (data.parseError)
+            return invalid(selector, data.parseError);
+        const kind = isLocatorExpression(selector) ? 'locator' : 'selector';
         const lines = [];
+        const stateLine = describePageState(state, root);
         if (data.matchCount === 0) {
-            lines.push(`## ✅ VALID — 0 matches`, '', `\`${selector}\` is syntactically valid but matched nothing on ${url}.`, '');
-            lines.push('**How to fix:** confirm the element exists at this URL (app may render after an interaction). Run **inspect-page** with the same URL to list real selectors, or add `waitFor` there.');
+            lines.push(`## ✅ VALID — 0 matches`, '', `\`${selector}\` is a valid ${kind} but matched nothing on ${url}.`, '');
+            if (stateLine)
+                lines.push(`**Page state:** ${stateLine}`, '');
+            const login = loginHint(data.finalUrl, state);
+            if (login)
+                lines.push(`> 🔒 ${login}`, '');
+            lines.push("**How to fix:** confirm the element exists in this state (it may appear only after an interaction: pass `actions`). Run **inspect-page** with `view: 'locators'` on the same URL to list real, verified locators.");
             return toolText(lines.join('\n'));
         }
         lines.push(`## ✅ VALID — ${data.matchCount} match${data.matchCount === 1 ? '' : 'es'}`, '');
-        lines.push(`**URL:** ${url}`, '');
+        lines.push(`**URL:** ${url}${kind === 'locator' ? `  |  **Parsed as:** \`${formatLocator(chain)}\`` : ''}`);
+        if (stateLine)
+            lines.push(`**Page state:** ${stateLine}`);
+        lines.push('');
         const matches = data.elements;
         for (let i = 0; i < matches.length; i += 1) {
             const element = matches[i];
@@ -80,10 +110,19 @@ export const validateSelectorTool = {
             lines.push(`${i + 1}. \`${element.selector}\` — **${element.tag}** · ${element.visible ? 'visible' : 'hidden'} · ${box}`);
             if (element.text)
                 lines.push(`   text: "${clipLines(element.text, 1, 140)}"`);
+            const best = bestLocator(element);
+            if (best && best !== formatLocator(chain))
+                lines.push(`   unique locator: \`${best}\``);
         }
         lines.push('');
         if (data.matchCount > 1) {
-            lines.push(`> ${data.matchCount} elements match. If you need exactly one, scope it: \`#id ${selector}\` or use the unique selector shown above.`, '');
+            lines.push(`> ⚠️ ${data.matchCount} elements match, so a Playwright action on it throws a strict mode violation. Use the unique locator of the element you mean (above), or add \`.first()\` / \`.filter({ hasText: '…' })\` deliberately.`, '');
+        }
+        else if (isBrittle(selector, chain)) {
+            const best = bestLocator(matches[0]);
+            if (best && !best.startsWith('locator(')) {
+                lines.push(`> 💡 \`${selector}\` depends on page structure and breaks on layout changes. Prefer \`${best}\`, which targets the same element.`, '');
+            }
         }
         const hidden = matches.filter((element) => !element.visible).length;
         if (hidden > 0 && hidden === matches.length) {

package/dist/tools/validate-selector.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-selector.js","sourceRoot":"","sources":["../../src/tools/validate-selector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate-selector.js","sourceRoot":"","sources":["../../src/tools/validate-selector.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -64,6 +64,11 @@ export interface ToolContext {
      * or run project code, and callers may not pick another project root.
      */
     restricted?: boolean;
+    /**
+     * Report progress to the client (MCP notifications/progress), when it
+     * asked for it with a progress token.
+     */
+    progress?: (progress: number, total?: number, message?: string) => void;
 }
 /**
  * MCP tool return value (content blocks + optional structured payload).
@@ -180,6 +185,8 @@ export interface RunTestOptions {
     /** Playwright --grep expression. */
     grep?: string;
     browser?: BrowserName;
+    /** Exact Playwright project name (e.g. the project a failure ran in); wins over `browser`. */
+    project?: string;
     headed?: boolean;
     /** Hard wall-clock limit for the whole run; process group is killed. */
     timeoutMs?: number;
@@ -202,6 +209,16 @@ export interface RunTestOptions {
     lastFailed?: boolean;
     /** Abort when the MCP client disconnects. */
     signal?: AbortSignal;
+    /** Called with Playwright's line-reporter progress while the run is going. */
+    onProgress?: (progress: RunProgress) => void;
+}
+/** Live progress of a run, parsed from the line reporter. */
+export interface RunProgress {
+    done: number;
+    total?: number;
+    failed: number;
+    /** Title of the most recently finished test. */
+    last?: string;
 }
 export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'flaky' | 'unknown';
 export type FailureKind = 'assertion' | 'timeout' | 'browser-crash' | 'syntax' | 'config' | 'server-unreachable' | 'unknown';
@@ -226,8 +243,22 @@ export interface TestFailure {
     /** Test console output (stdout) captured for this attempt. */
     stdout?: string;
 }
+/** One test's final outcome in a run (every test, not only failures). */
+export interface TestOutcome {
+    file: string;
+    line?: number;
+    title: string;
+    project?: string;
+    status: TestStatus;
+    durationMs?: number;
+    failureKind?: FailureKind;
+    /** First line of the error, for failed/flaky tests. */
+    message?: string;
+}
 export interface RunTestResult {
     ok: boolean;
+    /** Final outcome of every test in the run (feeds run history). */
+    outcomes?: TestOutcome[];
     exitCode: number | null;
     signalName: string | null;
     durationMs: number;
@@ -300,6 +331,15 @@ export interface ElementInfo {
         width: number;
         height: number;
     };
+    /** Accessible name, when the element has a role. */
+    name?: string;
+    /**
+     * Playwright locators proven (in the same page) to resolve to exactly this
+     * element, best first: role + name, test id, label, placeholder, text, CSS.
+     */
+    locators?: import('../utils/locator-expr.js').LocatorCall[][];
+    /** heal mode: how closely the element matches the broken locator. */
+    score?: number;
 }
 export interface ConsoleMessageInfo {
     type: string;

package/dist/utils/locator-expr.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Safe parsing of Playwright locator expressions.
+ *
+ * Agents and tests speak in locators — `getByRole('button', { name: 'Save' })`,
+ * `getByTestId('cart')`, `locator('#cta').first()` — not just CSS. This module
+ * turns such an expression into a plain JSON chain of whitelisted method calls
+ * that the browser child script replays against a real page. Nothing is ever
+ * evaluated as code: the parser accepts only string, number, boolean, regex
+ * and flat object literals, and only the methods listed in LOCATOR_METHODS.
+ *
+ * A bare string that is not a call chain (`#cta`, `text=Buy`, `role=button`)
+ * becomes `locator(<string>)`, so every Playwright selector engine works too.
+ */
+/** A JSON-safe regex literal (RegExp does not survive JSON.stringify). */
+export interface RegexValue {
+    $regex: string;
+    flags: string;
+}
+export type LocatorArg = string | number | boolean | RegexValue | {
+    [key: string]: LocatorArg;
+};
+export interface LocatorCall {
+    method: LocatorMethod;
+    args: LocatorArg[];
+}
+export declare const LOCATOR_METHODS: readonly ["getByRole", "getByText", "getByLabel", "getByPlaceholder", "getByAltText", "getByTitle", "getByTestId", "locator", "first", "last", "nth", "filter"];
+export type LocatorMethod = (typeof LOCATOR_METHODS)[number];
+/** True when the input looks like a call chain rather than a selector string. */
+export declare function isLocatorExpression(input: string): boolean;
+/**
+ * Parse a locator expression or selector into a whitelisted call chain.
+ * Throws INVALID_PATH with a usable hint on anything else.
+ */
+export declare function parseLocator(input: string): LocatorCall[];
+/** Single-quoted JS string literal. */
+export declare function quote(text: string): string;
+/** Render a chain back to source, e.g. `getByRole('button', { name: 'Save' })`. */
+export declare function formatLocator(calls: LocatorCall[]): string;