playwright-e2e-mcp 0.1.3 → 0.2.0

package/dist/tools/run-test.js

@@ -7,6 +7,8 @@ import { PlaywrightMcpError } from '../types/index.js';
 import { detectProject, missingPlaywrightMessage } from '../utils/project-detector.js';
 import { runTests } from '../utils/playwright-runner.js';
 import { normalizePath, relativeToRoot } from '../utils/path-utils.js';
+import { recordRun } from '../utils/run-history.js';
+import { startBackgroundRun } from '../utils/run-registry.js';
 import { codeFence, clipLines, formatDuration, guard, renderFailure, resolveConfigSelection, resolveProjectRoot, sanitizeTestPathArgument, testPathExists, toolError, toolText, } from './shared.js';
 const runTestInput = z.object({
     projectRoot: z
@@ -55,9 +57,13 @@ const runTestInput = z.object({
         .array(z.string())
         .optional()
         .describe('Extra Playwright flags from an allowlist, as --flag or --flag=value (e.g. --repeat-each=3, --shard=1/2, --trace=on)'),
+    background: z
+        .boolean()
+        .optional()
+        .describe('Return a run id at once; poll get-run-status'),
 });
 export const runTestSchema = runTestInput;
-function renderRunResult(result, root) {
+export function renderRunResult(result, root) {
     const flakyCount = result.stats?.flaky ?? 0;
     const status = result.ok
         ? flakyCount > 0
@@ -116,7 +122,7 @@ function renderRunResult(result, root) {
 }
 export const runTestTool = {
     name: 'run-test',
-    description: 'Run Playwright end-to-end tests in the user\'s project and return structured results: pass/fail stats, per-failure messages with file:line, and diagnostics. Detects missing Playwright installs, multiple configs, dead dev servers, syntax errors, browser crashes, timeouts (kills the process tree and returns partial results) and full disks.',
+    description: 'Run the project\'s Playwright tests: stats plus each failure\'s file:line, kind and message. Diagnoses missing installs, dead dev servers, syntax errors, crashes and timeouts (kills the tree, keeps partial results). Reports progress; background: true returns a run id for long suites. Runs are recorded for analyze-history.',
     inputSchema: runTestSchema,
     handler: async (args, ctx) => guard('run-test', async () => {
         const root = await resolveProjectRoot(args.projectRoot, ctx);
@@ -155,8 +161,29 @@ export const runTestTool = {
             extraArgs: args.args,
             signal: ctx.signal,
         };
-        const result = await runTests(options);
+        if (args.background) {
+            const { signal: _signal, ...rest } = options;
+            const label = sanitized.length > 0 ? sanitized.map((f) => relativeToRoot(root, f)).join(', ') : 'whole suite';
+            const run = startBackgroundRun(rest, label, async (result) => {
+                ctx.store.setLastRun({ projectRoot: root, result, at: Date.now() });
+                await recordRun(root, result, 'run-test');
+            });
+            return toolText([
+                `## ▶️ Run started in the background — \`${run.id}\``,
+                '',
+                `**Tests:** ${label}`,
+                '',
+                `> Next: call **get-run-status** with \`runId: "${run.id}"\` (add \`waitSeconds\` to wait for it). The result also becomes the last run for **get-failure** and **suggest-fix** when it finishes.`,
+            ].join('\n'));
+        }
+        const result = await runTests({
+            ...options,
+            onProgress: ctx.progress
+                ? (p) => ctx.progress?.(p.done, p.total, `${p.done}${p.total ? `/${p.total}` : ''} tests done${p.failed ? `, ${p.failed} failed` : ''}${p.last ? ` · ${p.last}` : ''}`)
+                : undefined,
+        });
         ctx.store.setLastRun({ projectRoot: root, result, at: Date.now() });
+        await recordRun(root, result, 'run-test').catch((err) => ctx.logger.warn('could not record run history', { error: err }));
         ctx.logger.info('run-test finished', {
             ok: result.ok,
             exitCode: result.exitCode,

package/dist/tools/run-test.js.map

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

package/dist/tools/shared.d.ts

@@ -6,7 +6,9 @@
  * (This file is an implementation detail; the five tool modules remain
  * the public surface documented in the README.)
  */
+import { z } from 'zod';
 import type { ErrorKind, FailureKind, ProjectDetection, TestFailure, ToolContext, ToolResponse, ToolStore } from '../types/index.js';
+import type { LocatorCall } from '../utils/locator-expr.js';
 export declare function createToolStore(): ToolStore;
 export declare function toolText(markdown: string): ToolResponse;
 export declare function toolError(kind: ErrorKind | 'ERROR', message: string, hint?: string, details?: string): ToolResponse;
@@ -37,19 +39,125 @@ export declare function testPathExists(argument: string, root: string): Promise<
 export declare function formatDuration(ms: number): string;
 export declare function codeFence(text: string, lang?: string): string;
 export declare function clipLines(text: string, maxLines: number, maxChars?: number): string;
+/**
+ * Escape a value so it cannot break out of a Markdown table cell.
+ *
+ * Backslashes are escaped before pipes: escaping only `|` lets an input that
+ * ends in `\` consume the inserted backslash, leaving a live `|` that splits
+ * the row (CodeQL js/incomplete-sanitization).
+ */
+export declare function markdownCell(text: string): string;
 export declare function renderFailure(failure: TestFailure, index: number, total: number): string;
 export declare function failureHint(kind: FailureKind): string;
-export interface BrowserScriptConfig {
-    mode: 'inspect' | 'validate' | 'screenshot';
+export declare const pageActionSchema: 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>;
+/** Signed-in session inputs. */
+export declare const sessionShape: {
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+};
+/** Inputs shared by every tool that opens a page. */
+export declare const pageStateShape: {
+    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>>;
+};
+export interface PageStateInput {
+    storageState?: string;
+    headers?: Record<string, string>;
+    actions?: Array<z.infer<typeof pageActionSchema>>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export interface ResolvedPageState {
+    storageState?: string;
+    headers?: Record<string, string>;
+    actions?: Array<{
+        type: string;
+        label: string;
+        locator?: LocatorCall[];
+        value?: string;
+        url?: string;
+        ms?: number;
+    }>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Validate page-state inputs: the storageState file must sit inside the
+ * project root (symlinks resolved) and parse as JSON, every goto URL passes
+ * the same URL policy as the entry URL, and locators are parsed into
+ * whitelisted call chains (never evaluated as code).
+ */
+export declare function resolvePageState(input: PageStateInput, root: string, entryUrl: string, ctx: ToolContext): Promise<ResolvedPageState>;
+/** One line describing the page state, for tool output headers. */
+export declare function describePageState(state: ResolvedPageState, root: string): string | undefined;
+/** A hint when an unauthenticated page landed on a login screen. */
+export declare function loginHint(finalUrl: string | undefined, state: ResolvedPageState): string | undefined;
+export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
+    mode: 'inspect' | 'validate' | 'screenshot' | 'heal';
     projectRoot: string;
-    url: string;
+    /** Page to open; omitted when rendering a snapshot. */
+    url?: string;
+    /** Render this DOM snapshot file instead of navigating (all requests blocked). */
+    snapshotHtmlPath?: string;
+    /** CSS selector for inspect mode. */
     selector?: string;
+    /** Parsed locator chain for validate / screenshot modes. */
+    selectorChain?: LocatorCall[];
+    /** inspect: 'elements' (DOM inventory) or 'locators' (compact locator map). */
+    view?: 'elements' | 'locators';
+    /** heal: words from the broken locator, and its role when it had one. */
+    healTokens?: string[];
+    healRole?: string;
     waitFor?: string;
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
     includeHtml?: boolean;
     maxHtmlChars?: number;
     gotoTimeout?: number;
     waitTimeout?: number;
+    actionTimeout?: number;
     /** Screenshot target path (mode: 'screenshot'). */
     screenshotPath?: string;
     /** Capture the full scrollable page (mode: 'screenshot'). */
@@ -71,10 +179,16 @@ export interface BrowserScriptData {
     };
     parseError?: string;
     consoleMessages?: import('../types/index.js').ConsoleMessageInfo[];
+    /** Page actions that completed before inspection. */
+    actionsDone?: string[];
     durationMs?: number;
 }
+/** Best verified locator for an element, as source text. */
+export declare function bestLocator(element: import('../types/index.js').ElementInfo): string | undefined;
 export interface BrowserScriptOutcome {
     ok: boolean;
+    /** Page actions that completed before a failure. */
+    actionsDone?: string[];
     data?: BrowserScriptData;
     kind?: ErrorKind;
     error?: string;