playwright-e2e-mcp 0.1.0

package/dist/tools/validate-selector.js

@@ -0,0 +1,93 @@
+/**
+ * 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?
+ */
+import { z } from 'zod';
+import { assertHttpUrl, clipLines, guard, resolveProjectRoot, runBrowserScript, toolError, toolText, } from './shared.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'),
+    projectRoot: z
+        .string()
+        .optional()
+        .describe("Project whose Playwright install launches the browser; defaults to the server working directory"),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1_000)
+        .max(300_000)
+        .optional()
+        .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;
+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.',
+    inputSchema: validateSelectorSchema,
+    handler: async (args, ctx) => guard('validate-selector', async () => {
+        const url = assertHttpUrl(args.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'));
+        }
+        const timeoutMs = args.timeoutMs ?? 45_000;
+        const root = await resolveProjectRoot(args.projectRoot, ctx);
+        const outcome = await runBrowserScript({
+            mode: 'validate',
+            projectRoot: root,
+            url,
+            selector,
+            gotoTimeout: Math.max(5_000, timeoutMs - 5_000),
+            startedAt: Date.now(),
+        }, { timeoutMs, signal: ctx.signal });
+        if (!outcome.ok) {
+            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'));
+        }
+        const lines = [];
+        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.');
+            return toolText(lines.join('\n'));
+        }
+        lines.push(`## ✅ VALID — ${data.matchCount} match${data.matchCount === 1 ? '' : 'es'}`, '');
+        lines.push(`**URL:** ${url}`, '');
+        const matches = data.elements;
+        for (let i = 0; i < matches.length; i += 1) {
+            const element = matches[i];
+            const box = element.box ? `${element.box.width}×${element.box.height} at (${element.box.x},${element.box.y})` : 'no box';
+            lines.push(`${i + 1}. \`${element.selector}\` — **${element.tag}** · ${element.visible ? 'visible' : 'hidden'} · ${box}`);
+            if (element.text)
+                lines.push(`   text: "${clipLines(element.text, 1, 140)}"`);
+        }
+        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.`, '');
+        }
+        const hidden = matches.filter((element) => !element.visible).length;
+        if (hidden > 0 && hidden === matches.length) {
+            lines.push('> ⚠️ All sampled matches are **hidden** — `toBeVisible()` will fail. Check parent elements for `display: none` / `visibility: hidden`.', '');
+        }
+        return toolText(lines.join('\n'));
+    }),
+};
+//# sourceMappingURL=validate-selector.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,344 @@
+/**
+ * Shared TypeScript interfaces and error types for playwright-e2e-mcp.
+ *
+ * Everything that other modules need to agree on lives here: tool
+ * contracts, Playwright JSON report shapes, run/inspect results, and the
+ * error taxonomy used to turn failures into actionable MCP responses.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export type LogContext = Record<string, unknown>;
+export interface Logger {
+    readonly level: LogLevel;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    child(bindings: LogContext): Logger;
+}
+/**
+ * Machine-readable failure categories. Tools map these to clear user
+ * facing messages instead of dumping raw stack traces.
+ */
+export type ErrorKind = 'NO_PLAYWRIGHT' | 'NO_CONFIG' | 'MULTIPLE_CONFIGS' | 'INVALID_PATH' | 'SERVER_NOT_RUNNING' | 'TIMEOUT' | 'BROWSER_CRASH' | 'SYNTAX_ERROR' | 'DISK_FULL' | 'CLIENT_DISCONNECT' | 'SPAWN_FAILED' | 'REPORT_MISSING' | 'UNKNOWN';
+export interface PlaywrightMcpErrorOptions {
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+}
+/**
+ * Error type carrying an ErrorKind so the MCP layer can render a
+ * helpful remediation hint instead of a raw exception.
+ */
+export declare class PlaywrightMcpError extends Error {
+    readonly kind: ErrorKind;
+    readonly hint?: string;
+    readonly details?: string;
+    constructor(message: string, kind?: ErrorKind, options?: PlaywrightMcpErrorOptions);
+}
+/** Wrap an unknown thrown value into a PlaywrightMcpError. */
+export declare function toPlaywrightMcpError(err: unknown, fallbackKind?: ErrorKind): PlaywrightMcpError;
+/** Result of the most recent run-test invocation (feeds get-failure). */
+export interface LastRunRecord {
+    projectRoot: string;
+    result: RunTestResult;
+    at: number;
+}
+/** Minimal cross-tool state held by the server. */
+export interface ToolStore {
+    lastRun: LastRunRecord | null;
+    setLastRun(record: LastRunRecord): void;
+}
+/** Per-invocation context passed from the server into each tool. */
+export interface ToolContext {
+    logger: Logger;
+    /**
+     * Aborted when the MCP client disconnects or cancels the request.
+     * Tools must kill child processes / browsers when this fires.
+     */
+    signal?: AbortSignal;
+    store: ToolStore;
+    /** Default project root (server cwd or PW_MCP_PROJECT_ROOT). */
+    projectRoot: string;
+}
+/**
+ * MCP tool return value (content blocks + optional structured payload).
+ * The index signature keeps it assignable to the SDK's CallToolResult.
+ */
+export interface ToolResponse {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'unknown';
+export interface ProjectDetection {
+    /** Directory the search started from (normalized, absolute). */
+    startDir: string;
+    /** Project root: directory containing playwright.config.* if found. */
+    root: string;
+    /** Absolute path of the selected config, or null when none exists. */
+    configPath: string | null;
+    /** Every config found in the chosen directory (ask user if >1). */
+    configCandidates: string[];
+    /** Whether @playwright/test or playwright is resolvable in node_modules. */
+    hasPlaywright: boolean;
+    /** Which package satisfied the check: '@playwright/test' | 'playwright'. */
+    playwrightPackage: string | null;
+    playwrightVersion: string | null;
+    /** Best-effort testDir parsed from the config file text. */
+    testDir: string | null;
+    packageManager: PackageManager;
+}
+export interface ReportStats {
+    expected: number;
+    unexpected: number;
+    flaky: number;
+    skipped: number;
+    duration: number;
+}
+export interface ReportError {
+    message?: string;
+    stack?: string;
+    codeframe?: string;
+    expected?: unknown;
+    actual?: unknown;
+    location?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+export interface ReportSpec {
+    title: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    ok?: boolean;
+    tags?: string[];
+    tests?: ReportTestCase[];
+}
+export interface ReportTestCase {
+    projectName?: string;
+    status?: string;
+    results?: ReportTestResult[];
+}
+export interface ReportTestResult {
+    status?: string;
+    retry?: number;
+    workerIndex?: number;
+    duration?: number;
+    startTime?: string;
+    error?: ReportError;
+    errors?: ReportError[];
+    expected?: string;
+    expectedStatus?: string;
+    actual?: string;
+    /** Trace/screenshot/console attachments produced for this attempt. */
+    attachments?: Array<{
+        name?: string;
+        path?: string;
+        contentType?: string;
+    }>;
+    /** Raw test console output captured by the JSON reporter. */
+    stdout?: unknown[];
+    stderr?: unknown[];
+}
+export interface ReportSuite {
+    title?: string;
+    file?: string;
+    line?: number;
+    suites?: ReportSuite[];
+    specs?: ReportSpec[];
+}
+export interface PlaywrightJsonReport {
+    config?: {
+        rootDir?: string;
+        configFile?: string;
+        projects?: Array<{
+            name?: string;
+        }>;
+    };
+    suites?: ReportSuite[];
+    errors?: ReportError[];
+    stats?: ReportStats;
+}
+export type BrowserName = 'chromium' | 'firefox' | 'webkit';
+export interface RunTestOptions {
+    /** Absolute project root (already sanitized by the caller). */
+    projectRoot: string;
+    configPath?: string;
+    /** Test files/paths relative to the project root, already sanitized. */
+    testFiles?: string[];
+    /** Playwright --grep expression. */
+    grep?: string;
+    browser?: BrowserName;
+    headed?: boolean;
+    /** Hard wall-clock limit for the whole run; process group is killed. */
+    timeoutMs?: number;
+    /** Per-test timeout passed to Playwright (--timeout). */
+    testTimeoutMs?: number;
+    workers?: number;
+    retries?: number;
+    /** Extra CLI args appended verbatim (caller-sanitized). */
+    extraArgs?: string[];
+    /**
+     * Automatically retry failed tests once before reporting failure
+     * (default true — injected as --retries=1 when the config does not
+     * already enable retries).
+     */
+    retryOnFailure?: boolean;
+    /**
+     * Playwright --last-failed: only re-run tests that failed in the
+     * previous run — the fast fix → re-run loop.
+     */
+    lastFailed?: boolean;
+    /** Abort when the MCP client disconnects. */
+    signal?: AbortSignal;
+}
+export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'flaky' | 'unknown';
+export type FailureKind = 'assertion' | 'timeout' | 'browser-crash' | 'syntax' | 'config' | 'server-unreachable' | 'unknown';
+export interface TestFailure {
+    /** Project-relative file path, posix separators. */
+    file: string;
+    line?: number;
+    /** Full test title path joined with ' › '. */
+    title: string;
+    project?: string;
+    status: TestStatus;
+    failureKind: FailureKind;
+    retry?: number;
+    message: string;
+    stack?: string;
+    codeframe?: string;
+    expected?: string;
+    actual?: string;
+    durationMs?: number;
+    /** Absolute path of the Playwright trace.zip captured for this attempt. */
+    tracePath?: string;
+    /** Test console output (stdout) captured for this attempt. */
+    stdout?: string;
+}
+export interface RunTestResult {
+    ok: boolean;
+    exitCode: number | null;
+    signalName: string | null;
+    durationMs: number;
+    /** The wrapper timeout fired: process was killed, results are partial. */
+    timedOut: boolean;
+    killed: boolean;
+    /** True when results are incomplete (timeout/crash/missing report). */
+    partial: boolean;
+    stats: ReportStats | null;
+    failures: TestFailure[];
+    stdoutTail: string;
+    stderrTail: string;
+    truncatedOutput: boolean;
+    reportPath?: string;
+    configPath?: string;
+    command: string;
+    /** True when more failures occurred than were included in `failures`. */
+    failuresTruncated?: boolean;
+    /** Server injected --retries=1 so flaky tests pass before reporting. */
+    autoRetry?: boolean;
+    /** Run was restricted to previously failed tests (--last-failed). */
+    lastFailed?: boolean;
+    errorKind?: ErrorKind;
+    errorMessage?: string;
+    hint?: string;
+}
+export interface ListTestsOptions {
+    projectRoot: string;
+    configPath?: string;
+    testDir?: string | null;
+    /** Case-insensitive substring filter applied to "file › title". */
+    filter?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface DiscoveredTest {
+    file: string;
+    title: string;
+    line?: number;
+    projects?: string[];
+}
+export interface ListTestsResult {
+    tests: DiscoveredTest[];
+    total: number;
+    truncated: boolean;
+    testDir: string | null;
+    source: 'playwright-list' | 'file-scan';
+    /** Why Playwright could not list tests, when the fallback scan was used. */
+    error?: {
+        kind: ErrorKind;
+        message: string;
+        hint?: string;
+    };
+}
+export interface ElementInfo {
+    /** Stable CSS selector that uniquely addresses the element. */
+    selector: string;
+    tag: string;
+    id?: string;
+    classes: string[];
+    role?: string;
+    text?: string;
+    attributes: Record<string, string>;
+    visible: boolean;
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface ConsoleMessageInfo {
+    type: string;
+    text: string;
+}
+export interface InspectPageOptions {
+    projectRoot: string;
+    url: string;
+    /** When set, inspect matches for this selector instead of the whole DOM. */
+    selector?: string;
+    /** Extra wait condition: CSS selector or "text=..." to await first. */
+    waitFor?: string;
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+    includeHtml?: boolean;
+    maxHtmlChars?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface PageInspection {
+    requestedUrl: string;
+    finalUrl: string;
+    title: string;
+    elementCount: number;
+    elements: ElementInfo[];
+    html?: string;
+    htmlTruncated?: boolean;
+    consoleMessages: ConsoleMessageInfo[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    durationMs: number;
+}
+export interface ValidateSelectorOptions {
+    projectRoot: string;
+    url: string;
+    selector: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ValidateSelectorResult {
+    selector: string;
+    valid: boolean;
+    matchCount: number;
+    /** First few matches, capped for readability. */
+    matches: ElementInfo[];
+    parseError?: string;
+    hint?: string;
+}

package/dist/types/index.js

@@ -0,0 +1,51 @@
+/**
+ * Shared TypeScript interfaces and error types for playwright-e2e-mcp.
+ *
+ * Everything that other modules need to agree on lives here: tool
+ * contracts, Playwright JSON report shapes, run/inspect results, and the
+ * error taxonomy used to turn failures into actionable MCP responses.
+ */
+/**
+ * Error type carrying an ErrorKind so the MCP layer can render a
+ * helpful remediation hint instead of a raw exception.
+ */
+export class PlaywrightMcpError extends Error {
+    kind;
+    hint;
+    details;
+    constructor(message, kind = 'UNKNOWN', options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'PlaywrightMcpError';
+        this.kind = kind;
+        this.hint = options.hint;
+        this.details = options.details;
+    }
+}
+/** Wrap an unknown thrown value into a PlaywrightMcpError. */
+export function toPlaywrightMcpError(err, fallbackKind = 'UNKNOWN') {
+    if (err instanceof PlaywrightMcpError)
+        return err;
+    if (err instanceof Error) {
+        const wrapped = new PlaywrightMcpError(err.message, classifyMessage(err.message, fallbackKind), {
+            cause: err,
+        });
+        wrapped.stack = err.stack;
+        return wrapped;
+    }
+    return new PlaywrightMcpError(String(err), fallbackKind);
+}
+function classifyMessage(message, fallbackKind) {
+    const m = message.toLowerCase();
+    if (m.includes('enoent') && m.includes('playwright'))
+        return 'NO_PLAYWRIGHT';
+    if (m.includes('syntaxerror') || m.includes('unexpected token'))
+        return 'SYNTAX_ERROR';
+    if (m.includes('enospc') || m.includes('no space left'))
+        return 'DISK_FULL';
+    if (m.includes('timed out') || m.includes('timeout'))
+        return 'TIMEOUT';
+    if (m.includes('target closed') || m.includes('browser has been closed'))
+        return 'BROWSER_CRASH';
+    return fallbackKind;
+}
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgDH;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAY;IAChB,IAAI,CAAU;IACd,OAAO,CAAU;IAE1B,YACE,OAAe,EACf,OAAkB,SAAS,EAC3B,UAAqC,EAAE;QAEvC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB,CAClC,GAAY,EACZ,eAA0B,SAAS;IAEnC,IAAI,GAAG,YAAY,kBAAkB;QAAE,OAAO,GAAG,CAAC;IAClD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE;YAC9F,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,eAAe,CAAC,OAAe,EAAE,YAAuB;IAC/D,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAChC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,eAAe,CAAC;IAC7E,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,cAAc,CAAC;IACvF,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;QAAE,OAAO,WAAW,CAAC;IAC5E,IAAI,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACvE,IAAI,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAAE,OAAO,eAAe,CAAC;IACjG,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/utils/change-analyzer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Change + selector analysis for the generate-e2e-test tool.
+ *
+ * "Look at the agent's recent file changes, identify the components,
+ * and scaffold a test using the correct selectors" (blueprint). This
+ * module answers the first two parts: which files changed (git working
+ * tree, last commit, or mtime fallback) and which locators those files
+ * actually declare (data-testid, roles, labels, ids…).
+ */
+export type SelectorKind = 'test-id' | 'role' | 'aria' | 'placeholder' | 'id' | 'name' | 'text';
+export interface SelectorCandidate {
+    kind: SelectorKind;
+    /** The raw value (test id, label, role name…). */
+    value: string;
+    /** Ready-to-paste Playwright locator fragment. */
+    locator: string;
+    file: string;
+    line: number;
+}
+export interface ChangedFile {
+    /** Project-relative posix path. */
+    path: string;
+    source: 'git' | 'mtime';
+}
+export interface ChangeAnalysis {
+    changeSource: 'git-status' | 'git-last-commit' | 'mtime';
+    files: ChangedFile[];
+    selectors: SelectorCandidate[];
+    scanned: number;
+    truncated: boolean;
+}
+/** Extract locators declared in one source file. */
+export declare function extractSelectors(source: string, file: string): SelectorCandidate[];
+export interface AnalyzeOptions {
+    /** Max files to read and scan. */
+    limit?: number;
+    /** mtime window for the non-git fallback. */
+    windowMs?: number;
+}
+export declare function analyzeRecentChanges(projectRoot: string, options?: AnalyzeOptions): Promise<ChangeAnalysis>;
+export interface EntryUrl {
+    baseURL?: string;
+    webServerUrl?: string;
+}
+/** Pull `baseURL` / `webServer.url` out of a playwright.config source. */
+export declare function detectEntryUrl(configSource: string): EntryUrl;