playwright-e2e-mcp 0.5.1 → 0.6.0

package/dist/utils/flake-rules.js

@@ -0,0 +1,327 @@
+/**
+ * Flake-risk rules for Playwright test code: patterns that make tests
+ * pass or fail by timing rather than by what the app does (hard waits,
+ * assertions that read once instead of retrying, promises nobody awaits,
+ * selectors tied to layout). Each finding says why it is risky, and the
+ * mechanical ones carry the replacement line.
+ *
+ * The scan is line based, not a TypeScript parse: it skips comments and
+ * aims for few false alarms over catching every case.
+ */
+export const SEVERITY_WEIGHT = { high: 5, medium: 2, low: 1 };
+export const RULES = {
+    'hard-wait': {
+        severity: 'high',
+        message: 'Fixed wait: too short on a slow run, wasted time on a fast one. Wait for the state instead (a web-first assertion, waitForURL or waitForResponse).',
+    },
+    sleep: {
+        severity: 'high',
+        message: 'setTimeout sleep: the same problem as waitForTimeout, hidden from Playwright. Wait for the state instead.',
+    },
+    'non-retrying-assertion': {
+        severity: 'high',
+        message: 'Reads the page once and asserts on the value, so it fails if the page is a moment late. A web-first assertion retries until it holds.',
+    },
+    'missing-await': {
+        severity: 'high',
+        message: 'Not awaited: the test moves on (or ends) before this finishes, so a failure is lost or lands in another step.',
+    },
+    'focused-test': {
+        severity: 'high',
+        message: '.only left in: every other test in the run is skipped (and forbidOnly fails CI).',
+    },
+    'force-action': {
+        severity: 'medium',
+        message: 'force: true skips the actionability checks, so the action can hit a covered, moving or disabled element that a user could not.',
+    },
+    networkidle: {
+        severity: 'medium',
+        message: "networkidle waits for 500 ms without traffic, which polling, analytics or websockets can stop from ever happening. Playwright discourages it; wait for what the test needs.",
+    },
+    'element-handle': {
+        severity: 'medium',
+        message: 'ElementHandle API: the handle goes stale when the page re-renders. Locators re-resolve on every use.',
+    },
+    'fragile-selector': {
+        severity: 'medium',
+        message: 'Selector tied to layout or generated class names: it breaks when markup moves. Prefer getByRole, getByLabel, getByText or getByTestId.',
+    },
+    'no-timeout': {
+        severity: 'medium',
+        message: 'timeout: 0 means wait forever: a missed state hangs the run until the global timeout instead of failing at this step.',
+    },
+    'hardcoded-url': {
+        severity: 'low',
+        message: 'Hard-coded local URL: set baseURL in the config and goto a path, so the test runs against any environment.',
+    },
+    'serial-mode': {
+        severity: 'low',
+        message: 'Serial mode: tests depend on each other, so one failure skips the rest and retries re-run the whole group.',
+    },
+};
+/* ------------------------------------------------------------------ */
+/* Small parsing helpers                                               */
+/* ------------------------------------------------------------------ */
+/** Index of the bracket closing the one at `open`, skipping quoted strings; -1 if unbalanced. */
+export function matchBracket(text, open) {
+    const pairs = { '(': ')', '[': ']', '{': '}' };
+    const stack = [];
+    let quote = '';
+    for (let i = open; i < text.length; i += 1) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === '\\')
+                i += 1;
+            else if (ch === quote)
+                quote = '';
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`')
+            quote = ch;
+        else if (pairs[ch])
+            stack.push(pairs[ch]);
+        else if (ch === ')' || ch === ']' || ch === '}') {
+            if (stack.pop() !== ch)
+                return -1;
+            if (stack.length === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Splits `target.method(args)` into its parts when `expr` ends in a call. */
+function trailingCall(expr) {
+    const trimmed = expr.trim();
+    if (!trimmed.endsWith(')'))
+        return undefined;
+    // Walk back to the call's opening parenthesis.
+    for (let open = trimmed.lastIndexOf('('); open >= 0; open = trimmed.lastIndexOf('(', open - 1)) {
+        if (matchBracket(trimmed, open) !== trimmed.length - 1)
+            continue;
+        const head = /\.(\w+)\s*$/.exec(trimmed.slice(0, open));
+        if (!head)
+            return undefined;
+        return { target: trimmed.slice(0, head.index), method: head[1], args: trimmed.slice(open + 1, -1).trim() };
+    }
+    return undefined;
+}
+const STATE_MATCHERS = {
+    isVisible: 'toBeVisible',
+    isHidden: 'toBeHidden',
+    isEnabled: 'toBeEnabled',
+    isDisabled: 'toBeDisabled',
+    isChecked: 'toBeChecked',
+    isEditable: 'toBeEditable',
+};
+/**
+ * The web-first form of a one-shot assertion, e.g.
+ * `expect(await x.isVisible()).toBe(true)` → `await expect(x).toBeVisible()`.
+ * Returns the whole rewritten line, or undefined when the line is not one
+ * this knows how to rewrite.
+ */
+export function webFirstRewrite(line) {
+    const start = /\bexpect\(/.exec(line);
+    if (!start)
+        return undefined;
+    const open = start.index + 'expect'.length;
+    const close = matchBracket(line, open);
+    if (close < 0)
+        return undefined;
+    const inner = line.slice(open + 1, close).trim();
+    const after = line.slice(close + 1);
+    const assertion = /^\s*\.(not\.)?(toBe|toEqual|toStrictEqual|toBeTruthy|toBeFalsy|toContain)\(/.exec(after);
+    if (!assertion)
+        return undefined;
+    const argsOpen = assertion[0].length - 1;
+    const argsClose = matchBracket(after, argsOpen);
+    if (argsClose < 0)
+        return undefined;
+    const expected = after.slice(argsOpen + 1, argsClose).trim();
+    const tail = after.slice(argsClose + 1);
+    let negated = Boolean(assertion[1]);
+    const matcher = assertion[2];
+    const equality = matcher === 'toBe' || matcher === 'toEqual' || matcher === 'toStrictEqual';
+    let target;
+    let web;
+    let webArgs = '';
+    if (/^page\.url\(\)$/.test(inner)) {
+        if (!equality)
+            return undefined;
+        target = 'page';
+        web = 'toHaveURL';
+        webArgs = expected;
+    }
+    else {
+        if (!inner.startsWith('await '))
+            return undefined;
+        const call = trailingCall(inner.slice('await '.length));
+        if (!call || call.target.trim() === '')
+            return undefined;
+        target = call.target.trim();
+        if (STATE_MATCHERS[call.method] && call.args === '') {
+            if (matcher === 'toBeTruthy' || (equality && expected === 'true'))
+                web = STATE_MATCHERS[call.method];
+            else if (matcher === 'toBeFalsy' || (equality && expected === 'false')) {
+                web = STATE_MATCHERS[call.method];
+                negated = !negated;
+            }
+            else
+                return undefined;
+        }
+        else if ((call.method === 'textContent' || call.method === 'innerText') && call.args === '') {
+            if (equality)
+                web = 'toHaveText';
+            else if (matcher === 'toContain')
+                web = 'toContainText';
+            else
+                return undefined;
+            webArgs = expected;
+        }
+        else if (call.method === 'inputValue' && call.args === '' && equality) {
+            web = 'toHaveValue';
+            webArgs = expected;
+        }
+        else if (call.method === 'count' && call.args === '' && equality) {
+            web = 'toHaveCount';
+            webArgs = expected;
+        }
+        else if (call.method === 'getAttribute' && call.args !== '' && equality) {
+            web = 'toHaveAttribute';
+            webArgs = `${call.args}, ${expected}`;
+        }
+        else if (call.method === 'title' && call.args === '' && target === 'page' && equality) {
+            web = 'toHaveTitle';
+            webArgs = expected;
+        }
+        else
+            return undefined;
+    }
+    const prefix = line.slice(0, start.index);
+    const awaited = /\bawait\s*$/.test(prefix) ? prefix : `${prefix}await `;
+    return `${awaited}expect(${target})${negated ? '.not' : ''}.${web}(${webArgs})${tail}`;
+}
+const ASYNC_MATCHERS = /\.(?:not\.)?(toBeVisible|toBeHidden|toBeEnabled|toBeDisabled|toBeChecked|toBeEditable|toBeFocused|toBeAttached|toBeInViewport|toBeEmpty|toHaveText|toContainText|toHaveValue|toHaveValues|toHaveCount|toHaveAttribute|toHaveClass|toContainClass|toHaveCSS|toHaveId|toHaveJSProperty|toHaveURL|toHaveTitle|toHaveScreenshot|toMatchAriaSnapshot|toHaveAccessibleName|toHaveAccessibleDescription|toHaveRole|toPass)\(/;
+const PAGE_ACTIONS = /\.(goto|click|dblclick|fill|press|pressSequentially|type|check|uncheck|setChecked|selectOption|setInputFiles|hover|tap|focus|blur|clear|reload|goBack|goForward|waitForURL|waitForLoadState|dragTo|dragAndDrop|setViewportSize|screenshot)\(/;
+const TEST_TITLE = /\btest(?:\.(?:only|fixme|skip|slow|fail))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/;
+function selectorRisk(selector) {
+    const s = selector.trim();
+    if (/^(xpath=|\/\/|\(\/\/|\.\.\/)/.test(s))
+        return true;
+    if (/:nth-(child|of-type)\(/.test(s))
+        return true;
+    // Hashed class names from CSS-in-JS and CSS modules.
+    if (/\.(css|sc|jsx|emotion)-[a-z0-9]{5,}/i.test(s) || /\.[A-Za-z]+_[A-Za-z]+__[A-Za-z0-9]{5}/.test(s))
+        return true;
+    // A long chain of descendant or child steps.
+    const steps = s.replace(/\[[^\]]*\]|\([^)]*\)|"[^"]*"|'[^']*'/g, '').split(/\s*>\s*|\s+/).filter(Boolean);
+    return steps.length >= 4;
+}
+/** The statement starting at `index`: that line plus following lines until one ends it (at most six). */
+function statementFrom(lines, index) {
+    const parts = [];
+    for (let i = index; i < lines.length && i < index + 6; i += 1) {
+        parts.push(lines[i].trim());
+        if (/[;{}]\s*$/.test(lines[i]) || (i > index && lines[i].trim() === ''))
+            break;
+    }
+    return parts.join(' ');
+}
+/** Scan one spec file's source. `file` is only copied into the findings. */
+export function scanFlakeRisks(file, source) {
+    const lines = source.split(/\r?\n/);
+    const findings = [];
+    let inBlockComment = false;
+    let currentTest;
+    const add = (index, rule, fix) => {
+        const lineText = lines[index];
+        findings.push({
+            file,
+            line: index + 1,
+            rule,
+            severity: RULES[rule].severity,
+            message: RULES[rule].message,
+            code: lineText.trim(),
+            ...(fix !== undefined && fix !== lineText ? { fix } : {}),
+            ...(currentTest ? { test: currentTest } : {}),
+        });
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (inBlockComment) {
+            if (trimmed.includes('*/'))
+                inBlockComment = false;
+            continue;
+        }
+        if (trimmed.startsWith('/*')) {
+            if (!trimmed.includes('*/'))
+                inBlockComment = true;
+            continue;
+        }
+        if (trimmed === '' || trimmed.startsWith('//') || trimmed.startsWith('*'))
+            continue;
+        // Drop a trailing line comment (not `://` inside a URL).
+        const code = raw.replace(/(^|[^:'"`])\/\/.*$/, '$1');
+        const title = TEST_TITLE.exec(code);
+        if (title && !/\btest\.(describe|step|use|beforeEach|afterEach|beforeAll|afterAll|extend)\b/.test(code))
+            currentTest = title[2];
+        if (/\.waitForTimeout\(/.test(code))
+            add(i, 'hard-wait');
+        if (/new Promise\(\s*\(?\s*\w*\s*\)?\s*=>\s*setTimeout\(/.test(code) || /\bsetTimeout\(\s*\w+\s*,\s*\d+\s*\)\s*\)/.test(code))
+            add(i, 'sleep');
+        if (/\bexpect\(\s*(await\s+[^;]*\.(isVisible|isHidden|isEnabled|isDisabled|isChecked|isEditable|textContent|innerText|inputValue|count|getAttribute)\(|page\.url\(\)\s*\)\s*\.(not\.)?(toBe|toEqual|toStrictEqual)\()/.test(code)) {
+            add(i, 'non-retrying-assertion', webFirstRewrite(raw));
+        }
+        else if (/^(expect(\.soft)?\(|expect\.poll\()/.test(trimmed)) {
+            const statement = statementFrom(lines, i);
+            if (trimmed.startsWith('expect.poll(') || ASYNC_MATCHERS.test(statement)) {
+                add(i, 'missing-await', raw.replace(/^(\s*)/, '$1await '));
+            }
+        }
+        else if (/^page\.\w/.test(trimmed)) {
+            const statement = statementFrom(lines, i);
+            if (PAGE_ACTIONS.test(statement) && !/,\s*$/.test(statement) && !/^page\.(on|once|off|route|unroute)\(/.test(trimmed)) {
+                add(i, 'missing-await', raw.replace(/^(\s*)/, '$1await '));
+            }
+        }
+        if (/\b(test|describe)(\.describe)?\.only\(/.test(code))
+            add(i, 'focused-test', raw.replace(/\.only\(/, '('));
+        if (/\bforce\s*:\s*true\b/.test(code))
+            add(i, 'force-action');
+        if (/['"`]networkidle['"`]/.test(code))
+            add(i, 'networkidle');
+        if (/\bpage\.(\$|\$\$|\$eval|\$\$eval)\(|\.waitForSelector\(|\.elementHandles?\(/.test(code))
+            add(i, 'element-handle');
+        for (const m of code.matchAll(/(?:\.locator|\.\$\$?|waitForSelector)\(\s*(['"`])((?:\\.|(?!\1).)+)\1/g)) {
+            if (selectorRisk(m[2])) {
+                add(i, 'fragile-selector');
+                break;
+            }
+        }
+        if (/\btimeout\s*:\s*0\b/.test(code) || /setTimeout\(\s*0\s*\)|setDefaultTimeout\(\s*0\s*\)/.test(code))
+            add(i, 'no-timeout');
+        if (/\.goto\(\s*['"`]https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)[:/'"`]/.test(code))
+            add(i, 'hardcoded-url');
+        if (/mode\s*:\s*['"`]serial['"`]/.test(code))
+            add(i, 'serial-mode');
+    }
+    return findings;
+}
+/** Apply every finding's fix to the source, line by line. Findings must belong to this source. */
+export function applyFlakeFixes(source, findings) {
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const lines = source.split(/\r?\n/);
+    const applied = [];
+    const done = new Set();
+    for (const finding of findings) {
+        if (finding.fix === undefined || done.has(finding.line))
+            continue;
+        if (lines[finding.line - 1]?.trim() !== finding.code)
+            continue;
+        lines[finding.line - 1] = finding.fix;
+        done.add(finding.line);
+        applied.push(finding);
+    }
+    return { source: lines.join(eol), applied };
+}
+//# sourceMappingURL=flake-rules.js.map

package/dist/utils/flake-rules.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-e2e-mcp",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "MCP server and agent skill that run, diagnose and fix failing Playwright tests: CI report diagnosis, trace analysis, verified locator fixes, flaky verdicts, breaking commits, tests written by walking the flow, accessibility and Web Vitals audits.",
   "author": "xsignon-secure (https://github.com/xsignon-secure)",
   "mcpName": "io.github.xsignon-secure/E2E",
@@ -60,6 +60,7 @@
     "prepare": "npm run build",
     "watch": "tsc -p tsconfig.json --watch",
     "test": "npm run build && node test/run-tests.mjs",
+    "coverage": "npm run build && node test/run-tests.mjs --coverage",
     "e2e": "npm run build && node e2e/run.mjs",
     "mcpb": "npm run build && node scripts/build-mcpb.mjs",
     "mcpb:smoke": "npm run mcpb && node scripts/mcpb-launch-sim.mjs && node scripts/mcpb-client-check.mjs",
@@ -73,16 +74,16 @@
     "prepublishOnly": "npm test"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.3.1",
+    "@modelcontextprotocol/server": "^2.4.0",
     "axe-core": "^4.14.0",
     "zod": "^4.2.0"
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.2",
-    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/client": "^2.4.0",
     "@playwright/test": "1.64.1",
     "@sparticuz/chromium": "153.0.0",
     "@types/node": "^26.6.5",

package/skill/playwright-e2e-mcp/SKILL.md

@@ -13,7 +13,7 @@ and concrete next steps. It can also propose and apply a verified fix for a brok
 locator, inspect pages behind a login, run long suites in the background and keep
 a local history of every run.
 
-This skill is written for playwright-e2e-mcp 0.5.1 and works with 0.2.0 or
+This skill is written for playwright-e2e-mcp 0.6.0 and works with 0.2.0 or
 newer. If `suggest-fix`, `get-run-status` or `analyze-history` is missing, the
 server is older than 0.2.0: use the steps that do not need those tools and tell
 the user to update it. `diagnose-flaky`'s per-test table and `isolate` option
@@ -148,6 +148,16 @@ re-runs the fix locally. If it says traces were not found, pass `traceDirs` with
 the folder where `test-results` was unpacked. The run is added to the history
 with its commit.
 
+## A test that used to pass
+
+When a test fails at HEAD but passed at some earlier commit, call
+`bisect-failure` (0.6.0+) `{ "test": "tests/cart.spec.ts", "grep": "adds an item" }`.
+It runs the test across git history in a temporary worktree (the checkout is not
+touched) and names the first bad commit with its diff summary. Pass `good` (a
+tag or `HEAD~30`) when the run history has no passing run of it; pass `repeat: 3`
+when the failure is intermittent. Read that commit's change before editing the
+test: the fix usually belongs in the app.
+
 ## Flaky or intermittent failures
 
 Start with `analyze-history` (default view `flaky`) to see which tests flip
@@ -164,6 +174,8 @@ one verdict **per test** (passes, failures, duration spread, first error):
   missing awaits, assertions without auto-waiting, shared state between tests and
   fixed `waitForTimeout` sleeps. Never "fix" flakiness by only adding retries or
   sleeps.
+  `audit-tests` (0.6.0+) finds these in the test code and names the ones in
+  tests that flaked; `fix: true` applies the mechanical rewrites and re-runs them.
 - **NOT REPRODUCING**: passed every run. Report that the failure was one-off.
 
 When a test is FLAKY and the suite runs in parallel, call `diagnose-flaky` again
@@ -227,7 +239,7 @@ with the commit it tested. `analyze-history` views:
   `selector` for one region) returns the accessibility snapshot and a
   `toMatchAriaSnapshot` assertion to paste into a spec.
 - **Set up CI:** when the user wants the same diagnosis on every pull request,
-  point them to the GitHub Action (`uses: xsignon-secure/E2E@v0.5.1`) or the
+  point them to the GitHub Action (`uses: xsignon-secure/E2E@v0.6.0`) or the
   `npx -y playwright-e2e-mcp ci` command in `references/setup.md`. It writes the
   run, flaky verdicts and fix diffs to the job summary and one PR comment.
 - **Accessibility:** `audit-accessibility` with `url` runs axe-core against

package/skill/playwright-e2e-mcp/references/setup.md

@@ -12,7 +12,7 @@ This skill only gives the agent instructions. The tools come from the
   (needs Playwright 1.64+) and root-cause grouping in 0.4.0. Check with
   `npx -y playwright-e2e-mcp --version`.
 
-- Node.js 20 or newer.
+- Node.js 22 or newer.
 - A project with `@playwright/test` installed and a browser available:
   `npx playwright install chromium`.
 
@@ -112,7 +112,7 @@ Exit code 0 means passed, 1 tests failed, 2 the run itself failed. On GitHub
 Actions it also writes to the job summary. As an Action:
 
 ```yaml
-- uses: xsignon-secure/E2E@v0.5.1
+- uses: xsignon-secure/E2E@v0.6.0
   with:
     flaky-runs: 3
     suggest: 2

package/skill/playwright-e2e-mcp/references/tools.md

@@ -245,3 +245,35 @@ Reads `.playwright-e2e-mcp/history.jsonl`, written by every run
 passing runs and flags ones that got slower; `trend` shows failed and flaky
 executions per day; `commits` names, per failing or flaky test, the first bad
 commit after its last passing streak and the last good one.
+
+## audit-tests (0.6.0+)
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `testDir` / `filter` | string | Narrow the files |
+| `minSeverity` | `low` \| `medium` \| `high` | Default `low` |
+| `historyRuns` | number | Default 50 |
+| `limit` | number | Findings listed, default 50 |
+| `fix` | boolean | Rewrite mechanical findings, re-run touched files, revert on failure |
+| `verify` | boolean | Default true |
+
+Rules: `hard-wait`, `sleep`, `non-retrying-assertion`, `missing-await`,
+`focused-test` (high); `force-action`, `networkidle`, `element-handle`,
+`fragile-selector`, `no-timeout` (medium); `hardcoded-url`, `serial-mode` (low).
+Only `non-retrying-assertion`, `missing-await` and `focused-test` are fixed
+mechanically. Files rank by findings weighted by their flaky rate in the history.
+
+## bisect-failure (0.6.0+)
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `test` | string | Spec file (required) |
+| `grep` | string | Test title; better than `:line` across commits |
+| `good` / `bad` | string | Commits or refs; `good` defaults to the newest passing commit in the history, `bad` to HEAD |
+| `repeat` | number | Runs per commit (1–10) for intermittent failures |
+| `maxSteps` | number | Default 12 |
+| `stepTimeoutMs` | number | Default 180000 |
+
+Runs in a temporary git worktree with the current `node_modules` linked in;
+untestable commits are skipped. `status` is `found`, `ambiguous`, `max-steps`,
+`not-failing` (passes at bad) or `good-fails`.