playwright-e2e-mcp 0.3.1 → 0.4.0

package/dist/tools/audit-accessibility.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Tool 12 — audit-accessibility: run axe-core (the engine behind Lighthouse
+ * and @axe-core/playwright) on a live page and return the WCAG violations,
+ * worst first, each with the offending elements as verified Playwright
+ * locators and a ready-made regression test.
+ *
+ * It takes the same page state as inspect-page (storageState, headers,
+ * actions), so pages behind a login, open modals and later steps of a flow
+ * can be audited, which is where most real accessibility bugs sit.
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResponse } from '../types/index.js';
+import { type BrowserScriptData } from './shared.js';
+/** WCAG 2.2 level A and AA, the usual legal and contractual bar. */
+export declare const DEFAULT_AXE_TAGS: readonly ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+declare const IMPACT_ORDER: readonly ['critical', 'serious', 'moderate', 'minor'];
+declare const auditAccessibilityInput: z.ZodObject<{
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            check: "check";
+            click: "click";
+            dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
+            hover: "hover";
+            press: "press";
+            select: "select";
+            uncheck: "uncheck";
+            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>>;
+    url: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    standard: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        "best-practice": "best-practice";
+        wcag21aa: "wcag21aa";
+        wcag22aa: "wcag22aa";
+        wcag2a: "wcag2a";
+        wcag2aa: "wcag2aa";
+    }>>;
+    minImpact: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        minor: "minor";
+        moderate: "moderate";
+        serious: "serious";
+    }>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle: "networkidle";
+    }>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuditAccessibilityInput = z.infer<typeof auditAccessibilityInput>;
+export declare const auditAccessibilitySchema: z.ZodObject<{
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            check: "check";
+            click: "click";
+            dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
+            hover: "hover";
+            press: "press";
+            select: "select";
+            uncheck: "uncheck";
+            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>>;
+    url: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    standard: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        "best-practice": "best-practice";
+        wcag21aa: "wcag21aa";
+        wcag22aa: "wcag22aa";
+        wcag2a: "wcag2a";
+        wcag2aa: "wcag2aa";
+    }>>;
+    minImpact: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        minor: "minor";
+        moderate: "moderate";
+        serious: "serious";
+    }>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle: "networkidle";
+    }>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** axe tags for a standard; undefined runs every rule. */
+export declare function axeTagsFor(standard: AuditAccessibilityInput['standard']): string[] | undefined;
+/** axe tags like `wcag143` → "WCAG 1.4.3". */
+export declare function wcagCriteria(tags: readonly string[]): string[];
+export declare function axeSourcePath(): string;
+export declare function renderAudit(url: string, data: BrowserScriptData, options: {
+    minImpact?: (typeof IMPACT_ORDER)[number];
+    tags?: string[];
+    stateLine?: string;
+    selector?: string;
+}): string;
+export declare const auditAccessibilityTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        storageState: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                check: "check";
+                click: "click";
+                dblclick: "dblclick";
+                fill: "fill";
+                goto: "goto";
+                hover: "hover";
+                press: "press";
+                select: "select";
+                uncheck: "uncheck";
+                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>>;
+        url: z.ZodString;
+        projectRoot: z.ZodOptional<z.ZodString>;
+        selector: z.ZodOptional<z.ZodString>;
+        standard: z.ZodOptional<z.ZodEnum<{
+            all: "all";
+            "best-practice": "best-practice";
+            wcag21aa: "wcag21aa";
+            wcag22aa: "wcag22aa";
+            wcag2a: "wcag2a";
+            wcag2aa: "wcag2aa";
+        }>>;
+        minImpact: z.ZodOptional<z.ZodEnum<{
+            critical: "critical";
+            minor: "minor";
+            moderate: "moderate";
+            serious: "serious";
+        }>>;
+        waitFor: z.ZodOptional<z.ZodString>;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle: "networkidle";
+        }>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    handler: (args: AuditAccessibilityInput, ctx: ToolContext) => Promise<ToolResponse>;
+};
+export {};

package/dist/tools/audit-accessibility.js

@@ -0,0 +1,162 @@
+/**
+ * Tool 12 — audit-accessibility: run axe-core (the engine behind Lighthouse
+ * and @axe-core/playwright) on a live page and return the WCAG violations,
+ * worst first, each with the offending elements as verified Playwright
+ * locators and a ready-made regression test.
+ *
+ * It takes the same page state as inspect-page (storageState, headers,
+ * actions), so pages behind a login, open modals and later steps of a flow
+ * can be audited, which is where most real accessibility bugs sit.
+ */
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+import { assertHttpUrl, bestLocator, clipLines, describePageState, guard, loginHint, pageStateShape, resolvePageState, resolveProjectRoot, runBrowserScript, toolError, toolText, } from './shared.js';
+import { assertUrlAllowed } from '../utils/url-policy.js';
+/** WCAG 2.2 level A and AA, the usual legal and contractual bar. */
+export const DEFAULT_AXE_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+const IMPACT_ORDER = ['critical', 'serious', 'moderate', 'minor'];
+const auditAccessibilityInput = z.object({
+    url: z.string().describe('Full URL of the page to audit (http/https)'),
+    projectRoot: z.string().optional().describe('Project whose Playwright launches the browser (default: server root)'),
+    selector: z.string().optional().describe('CSS selector: audit only this part of the page'),
+    standard: z
+        .enum(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa', 'best-practice', 'all'])
+        .optional()
+        .describe("Rule set: WCAG level (default wcag22aa, i.e. 2.0–2.2 A+AA), 'best-practice' adds axe's extra rules, 'all' runs everything"),
+    minImpact: z
+        .enum(IMPACT_ORDER)
+        .optional()
+        .describe('Hide violations below this impact (default: minor, show all)'),
+    waitFor: z.string().optional().describe('Wait for this selector first'),
+    ...pageStateShape,
+    waitUntil: z
+        .enum(['load', 'domcontentloaded', 'networkidle'])
+        .optional()
+        .describe('Navigation wait condition (default load)'),
+    timeoutMs: z.number().int().min(1_000).max(300_000).optional().describe('Overall audit limit in ms (default 60000)'),
+});
+export const auditAccessibilitySchema = auditAccessibilityInput;
+/** axe tags for a standard; undefined runs every rule. */
+export function axeTagsFor(standard) {
+    switch (standard ?? 'wcag22aa') {
+        case 'wcag2a':
+            return ['wcag2a'];
+        case 'wcag2aa':
+            return ['wcag2a', 'wcag2aa'];
+        case 'wcag21aa':
+            return ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+        case 'wcag22aa':
+            return [...DEFAULT_AXE_TAGS];
+        case 'best-practice':
+            return [...DEFAULT_AXE_TAGS, 'best-practice'];
+        default:
+            return undefined;
+    }
+}
+/** axe tags like `wcag143` → "WCAG 1.4.3". */
+export function wcagCriteria(tags) {
+    const out = [];
+    for (const tag of tags) {
+        const m = /^wcag(\d)(\d)(\d{1,2})$/.exec(tag);
+        if (m)
+            out.push(`${m[1]}.${m[2]}.${m[3]}`);
+    }
+    return out;
+}
+export function axeSourcePath() {
+    return createRequire(import.meta.url).resolve('axe-core/axe.min.js');
+}
+function impactRank(impact) {
+    const i = IMPACT_ORDER.indexOf(impact);
+    return i === -1 ? IMPACT_ORDER.length : i;
+}
+/** First line of axe's failure summary that says what to change. */
+function fixLine(summary) {
+    const lines = summary.split('\n').map((l) => l.trim()).filter(Boolean);
+    const body = lines.filter((l) => !/^Fix (any|all) of the following:?$/i.test(l));
+    return clipLines(body[0] ?? lines[0] ?? '', 1, 200);
+}
+export function renderAudit(url, data, options) {
+    const scan = data.a11y;
+    const floor = impactRank(options.minImpact ?? 'minor');
+    const all = [...scan.violations].sort((a, b) => impactRank(a.impact) - impactRank(b.impact) || b.nodeCount - a.nodeCount);
+    const shown = all.filter((v) => impactRank(v.impact) <= floor);
+    const hidden = all.length - shown.length;
+    const standard = options.tags ? options.tags.join(', ') : 'all axe rules';
+    const lines = [];
+    if (scan.scopeMissing) {
+        return [`## ❓ Nothing to audit`, '', `\`${options.selector}\` matched no element on ${url}. Run **inspect-page** to find the right container.`].join('\n');
+    }
+    const counts = IMPACT_ORDER.map((impact) => [impact, shown.filter((v) => v.impact === impact).length]).filter(([, n]) => n > 0);
+    if (shown.length === 0) {
+        lines.push(`## ✅ No accessibility violations`, '');
+    }
+    else {
+        lines.push(`## ♿ ${shown.length} accessibility violation${shown.length === 1 ? '' : 's'} (${counts.map(([i, n]) => `${n} ${i}`).join(', ')})`, '');
+    }
+    lines.push(`**URL:** ${url}${options.selector ? `  |  **Scope:** \`${options.selector}\`` : ''}  |  **Rules:** ${standard}`);
+    if (options.stateLine)
+        lines.push(`**Page state:** ${options.stateLine}`);
+    lines.push(`**Checked:** ${scan.passes} rules passed · ${scan.incomplete} need manual review${hidden ? ` · ${hidden} below ${options.minImpact} hidden` : ''}`, '');
+    shown.forEach((v, i) => {
+        const criteria = wcagCriteria(v.tags);
+        lines.push(`### ${i + 1}. ${v.impact} · \`${v.id}\`: ${v.help}${criteria.length ? ` (WCAG ${criteria.join(', ')})` : ''}`);
+        lines.push(`${v.nodeCount} element${v.nodeCount === 1 ? '' : 's'} · ${v.helpUrl}`);
+        for (const node of v.nodes) {
+            const element = node.element >= 0 ? data.elements[node.element] : undefined;
+            const locator = element ? bestLocator(element) : undefined;
+            lines.push(`- \`${locator ?? node.target}\`${locator ? '' : ' (CSS)'}: ${fixLine(node.summary)}`);
+        }
+        if (v.nodeCount > v.nodes.length)
+            lines.push(`- …and ${v.nodeCount - v.nodes.length} more`);
+        lines.push('');
+    });
+    if (shown.length > 0) {
+        const tagList = (options.tags ?? [...DEFAULT_AXE_TAGS]).map((t) => `'${t}'`).join(', ');
+        lines.push('**Keep it fixed:** add this check to the spec that reaches this page (`npm i -D @axe-core/playwright`):', '', '```ts', "import AxeBuilder from '@axe-core/playwright';", '', `const { violations } = await new AxeBuilder({ page })${options.selector ? `.include(${JSON.stringify(options.selector)})` : ''}.withTags([${tagList}]).analyze();`, 'expect(violations.map((v) => v.id)).toEqual([]);', '```');
+    }
+    return lines.join('\n').trimEnd();
+}
+export const auditAccessibilityTool = {
+    name: 'audit-accessibility',
+    description: "Run axe-core on a live page (WCAG 2.2 AA by default) and return violations worst first, each with the offending elements as verified Playwright locators, the fix, and a regression check to paste into a spec. Accepts storageState/headers/actions to audit pages behind a login or after a step.",
+    inputSchema: auditAccessibilitySchema,
+    handler: async (args, ctx) => guard('audit-accessibility', async () => {
+        const url = assertHttpUrl(args.url);
+        await assertUrlAllowed(url);
+        const root = await resolveProjectRoot(args.projectRoot, ctx);
+        const state = await resolvePageState(args, root, url, ctx);
+        const timeoutMs = args.timeoutMs ?? 60_000;
+        const tags = axeTagsFor(args.standard);
+        const outcome = await runBrowserScript({
+            ...state,
+            mode: 'a11y',
+            projectRoot: root,
+            url,
+            selector: args.selector,
+            waitFor: args.waitFor,
+            waitUntil: args.waitUntil ?? 'load',
+            axeSourcePath: axeSourcePath(),
+            axeTags: tags,
+            maxNodes: 3,
+            gotoTimeout: Math.max(5_000, timeoutMs - 10_000),
+            waitTimeout: Math.min(10_000, Math.max(3_000, timeoutMs - 10_000)),
+            startedAt: Date.now(),
+        }, { timeoutMs, signal: ctx.signal });
+        if (!outcome.ok || !outcome.data?.a11y) {
+            const done = outcome.actionsDone?.length ? `\n\nSteps completed before the failure: ${outcome.actionsDone.join('; ')}` : '';
+            return toolError(outcome.kind ?? 'UNKNOWN', `Could not audit ${url}: ${outcome.error ?? 'no result from axe-core'}${done}`, outcome.hint, outcome.stderrTail);
+        }
+        let text = renderAudit(url, outcome.data, {
+            minImpact: args.minImpact,
+            tags,
+            stateLine: describePageState(state, root),
+            selector: args.selector,
+        });
+        const login = loginHint(outcome.data.finalUrl, state);
+        if (login)
+            text += `\n\n> 🔒 ${login}`;
+        return toolText(text);
+    }),
+};
+//# sourceMappingURL=audit-accessibility.js.map

package/dist/tools/audit-accessibility.js.map

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

package/dist/tools/compare-visual-state.d.ts

@@ -9,24 +9,19 @@
 import { z } from 'zod';
 import type { ToolContext, ToolResponse } from '../types/index.js';
 declare const compareInput: z.ZodObject<{
-    timeoutMs: z.ZodOptional<z.ZodNumber>;
-    action: z.ZodOptional<z.ZodEnum<{
-        compare: "compare";
-        baseline: "baseline";
-    }>>;
-    tolerance: z.ZodOptional<z.ZodNumber>;
-    pixelThreshold: z.ZodOptional<z.ZodNumber>;
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
-            fill: "fill";
-            goto: "goto";
+            check: "check";
             click: "click";
             dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
             hover: "hover";
             press: "press";
-            check: "check";
-            uncheck: "uncheck";
             select: "select";
+            uncheck: "uncheck";
             wait: "wait";
         }>;
         locator: z.ZodOptional<z.ZodString>;
@@ -38,40 +33,40 @@ declare const compareInput: 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;
     name: z.ZodString;
     projectRoot: z.ZodOptional<z.ZodString>;
     selector: z.ZodOptional<z.ZodString>;
     fullPage: z.ZodOptional<z.ZodBoolean>;
     waitUntil: z.ZodOptional<z.ZodEnum<{
-        load: "load";
         domcontentloaded: "domcontentloaded";
+        load: "load";
         networkidle: "networkidle";
     }>>;
     waitFor: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type CompareVisualStateInput = z.infer<typeof compareInput>;
-export declare const compareVisualStateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     action: z.ZodOptional<z.ZodEnum<{
-        compare: "compare";
         baseline: "baseline";
+        compare: "compare";
     }>>;
     tolerance: z.ZodOptional<z.ZodNumber>;
     pixelThreshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CompareVisualStateInput = z.infer<typeof compareInput>;
+export declare const compareVisualStateSchema: z.ZodObject<{
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
-            fill: "fill";
-            goto: "goto";
+            check: "check";
             click: "click";
             dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
             hover: "hover";
             press: "press";
-            check: "check";
-            uncheck: "uncheck";
             select: "select";
+            uncheck: "uncheck";
             wait: "wait";
         }>;
         locator: z.ZodOptional<z.ZodString>;
@@ -83,42 +78,42 @@ export declare const compareVisualStateSchema: 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;
     name: z.ZodString;
     projectRoot: z.ZodOptional<z.ZodString>;
     selector: z.ZodOptional<z.ZodString>;
     fullPage: z.ZodOptional<z.ZodBoolean>;
     waitUntil: z.ZodOptional<z.ZodEnum<{
-        load: "load";
         domcontentloaded: "domcontentloaded";
+        load: "load";
         networkidle: "networkidle";
     }>>;
     waitFor: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodOptional<z.ZodEnum<{
+        baseline: "baseline";
+        compare: "compare";
+    }>>;
+    tolerance: z.ZodOptional<z.ZodNumber>;
+    pixelThreshold: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const compareVisualStateTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
-        timeoutMs: z.ZodOptional<z.ZodNumber>;
-        action: z.ZodOptional<z.ZodEnum<{
-            compare: "compare";
-            baseline: "baseline";
-        }>>;
-        tolerance: z.ZodOptional<z.ZodNumber>;
-        pixelThreshold: z.ZodOptional<z.ZodNumber>;
+        storageState: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodEnum<{
-                fill: "fill";
-                goto: "goto";
+                check: "check";
                 click: "click";
                 dblclick: "dblclick";
+                fill: "fill";
+                goto: "goto";
                 hover: "hover";
                 press: "press";
-                check: "check";
-                uncheck: "uncheck";
                 select: "select";
+                uncheck: "uncheck";
                 wait: "wait";
             }>;
             locator: z.ZodOptional<z.ZodString>;
@@ -130,19 +125,24 @@ export declare const compareVisualStateTool: {
             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;
         name: z.ZodString;
         projectRoot: z.ZodOptional<z.ZodString>;
         selector: z.ZodOptional<z.ZodString>;
         fullPage: z.ZodOptional<z.ZodBoolean>;
         waitUntil: z.ZodOptional<z.ZodEnum<{
-            load: "load";
             domcontentloaded: "domcontentloaded";
+            load: "load";
             networkidle: "networkidle";
         }>>;
         waitFor: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodOptional<z.ZodEnum<{
+            baseline: "baseline";
+            compare: "compare";
+        }>>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+        pixelThreshold: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
     handler: (args: CompareVisualStateInput, ctx: ToolContext) => Promise<ToolResponse>;
 };

package/dist/tools/diagnose-flaky.d.ts

@@ -9,6 +9,9 @@
  * keeps only one result per test. `isolate` adds a second pass with one
  * worker so failures caused by parallelism (shared state, test-order
  * coupling, contention) are told apart from flakiness inside the test.
+ * `order` (Playwright 1.64+) runs the target files in several random orders
+ * with one worker and replays a failing order, which finds tests that pass
+ * or fail depending on what ran before them, and names the likely culprit.
  *
  * The verdict logic is pure functions (exported for unit tests).
  */
@@ -26,6 +29,7 @@ declare const diagnoseFlakyInput: z.ZodObject<{
     headed: z.ZodOptional<z.ZodBoolean>;
     workers: z.ZodOptional<z.ZodNumber>;
     isolate: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodBoolean>;
     separateProcesses: z.ZodOptional<z.ZodBoolean>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     config: z.ZodOptional<z.ZodString>;
@@ -43,6 +47,7 @@ export declare const diagnoseFlakySchema: z.ZodObject<{
     headed: z.ZodOptional<z.ZodBoolean>;
     workers: z.ZodOptional<z.ZodNumber>;
     isolate: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodBoolean>;
     separateProcesses: z.ZodOptional<z.ZodBoolean>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     config: z.ZodOptional<z.ZodString>;
@@ -95,6 +100,38 @@ export type IsolationReading = 'PARALLEL ONLY' | 'FLAKY ALONE TOO' | 'FAILS EITH
  * was therefore not re-run.
  */
 export declare function isolationReading(parallel: FlakySummary, isolated: FlakySummary | undefined): IsolationReading;
+/** True when this Playwright version has `--shuffle` (1.64+). */
+export declare function supportsShuffle(version: string | null | undefined): boolean;
+/** One shuffled run: its seed and the attempts in execution order (one worker). */
+export interface OrderRun {
+    seed: string;
+    attempts: TestAttempt[];
+}
+export type OrderReading = 'ORDER DEPENDENT' | 'FLAKY IN ANY ORDER' | 'FAILS IN EVERY ORDER' | 'PASSES IN EVERY ORDER';
+export interface OrderFinding {
+    file: string;
+    line?: number;
+    title: string;
+    project?: string;
+    passedSeeds: string[];
+    failedSeeds: string[];
+    /** The failing seed replayed to confirm, and whether it failed again. */
+    replay?: {
+        seed: string;
+        failedAgain: boolean;
+    };
+    reading: OrderReading;
+    /** Tests that ran before this one in every failing order but after it in a passing one (they break it). */
+    suspects: string[];
+    /** Tests that ran before it in every passing order but after it in a failing one (it relies on them). */
+    reliesOn: string[];
+    headline?: string;
+}
+/**
+ * Read shuffled runs (plus replays of failing seeds) per test. Pure, so the
+ * verdicts are unit-tested without Playwright.
+ */
+export declare function analyzeOrder(runs: OrderRun[], replays?: OrderRun[]): OrderFinding[];
 /**
  * Split one --repeat-each run into one run per repetition, so run history
  * (analyze-history) counts every repetition as its own run, exactly as it
@@ -116,6 +153,7 @@ export declare const diagnoseFlakyTool: {
         headed: z.ZodOptional<z.ZodBoolean>;
         workers: z.ZodOptional<z.ZodNumber>;
         isolate: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodBoolean>;
         separateProcesses: z.ZodOptional<z.ZodBoolean>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         config: z.ZodOptional<z.ZodString>;