playwright-e2e-mcp

Suggest (and apply) a fix

suggest-fix

Destructive

Repair Playwright test failures by replacing drifted or ambiguous locators and updating changed expected text, then return a diff and confidence; optionally apply, re-run, and revert if still failing.

Instructions

Patch a failure from the last run: a drifted locator is matched against the DOM at failure (trace, or live url) and replaced with one proven unique; a locator that matches several elements (strict mode) gets the unique one for the intended match; changed copy gets the new expected text. Returns a diff and confidence; apply: true writes it, re-runs the test and reverts if still red. Refuses when the element is truly missing (app bug).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "suggest-fix"
  }
}

Input Schema

Name	Required	Description
`url`	No	Heal against this live page instead of the trace snapshot
`apply`	No	Write the fix (default: diff only)
`index`	No	1-based failure index (default 1)
`config`	No	playwright.config path or 1-based index
`verify`	No	Re-run after applying; revert if still failing (default true)
`headers`	No	Extra HTTP headers, e.g. Authorization
`candidate`	No	Strict mode violation: which of the listed matches the test meant (1-based)
`timeoutMs`	No	Verification run limit (default 120000)
`projectRoot`	No
`storageState`	No	Logged-in session: storageState JSON inside the project, e.g. playwright/.auth/user.json
`verifyAllProjects`	No	Verify on every project in playwright.config (e.g. chromium, firefox, webkit), not just the one that failed; revert unless all pass
`allowExpectationUpdate`	No	Allow applying changed expected text (can hide regressions)

Output Schema

Name	Required	Description
`ok`	Yes	false when the call failed (see error) or the tests it ran failed
`fix`	No
`error`	No
`applied`	No
`declined`	No	the person declined the change; nothing was written
`verified`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.14.0Nov 2, 2026

addedInput schema / properties / verifyAllProjects

Added value: +{
+  "description": "Verify on every project in playwright.config (e.g. chromium, firefox, webkit), not just the one that failed; revert unless all pass",
+  "type": "boolean"
+}

Changed4 schema fields changedv0.13.0Nov 2, 2026

removedInput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -{}
```
removedInput schema / properties / headers / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / declined

Added value: +{
+  "description": "the person declined the change; nothing was written",
+  "type": "boolean"
+}

Changed3 schema fields changedv0.6.1Oct 27, 2026

addedInput schema / additionalProperties
```
Added value: +{}
```

addedInput schema / properties / candidate

Added value: +{
+  "description": "Strict mode violation: which of the listed matches the test meant (1-based)",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "applied": {
+      "type": "boolean"
+    },
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "hint": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "message"
+      ],
+      "type": "object"
+    },
+    "fix": {
+      "additionalProperties": false,
+      "properties": {
+        "after": {
+          "type": "string"
+        },
+        "alternatives": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "before": {
+          "type": "string"
+        },
+        "confidence": {
+          "type": "string"
+        },
+        "file": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "locator",
+            "expectation"
+          ],
+          "type": "string"
+        },
+        "line": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "why": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "file",
+        "line",
+        "before",
+        "after",
+        "kind",
+        "confidence",
+        "why"
+      ],
+      "type": "object"
+    },
+    "ok": {
+      "description": "false when the call failed (see error) or the tests it ran failed",
+      "type": "boolean"
+    },
+    "verified": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedv0.3.2Oct 20, 2026

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint/openWorldHint, and the description adds the operational safety net that annotations cannot express: default is diff-only, apply:true writes, the test is re-run and reverted if still red. It also discloses the refusal case and the return payload (diff + confidence), giving the agent a clear picture of side effects and rollback.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and built from three semicolon-delimited cases, so it scans well for a 12-parameter tool. It is dense — one long run-on paragraph with no line breaks — but no clause is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 optional params, an output schema, and rich annotations, the description covers the non-obvious surface: write semantics, verification, rollback, and refusal. Remaining gaps (auth via storageState/headers, project-scoped verification) are adequately documented in the schema itself, so nothing an agent needs to call correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 92%, so baseline is 3; the description goes beyond it by explaining cross-parameter behavior — that apply writes and re-runs, that revert happens automatically if still red, and how candidate selects among strict-mode matches. The interaction of apply/verify and the expectation-update path is conveyed semantically rather than just structurally.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource ("Patch a failure from the last run") and enumerates the three fixable cases — drifted locator, strict-mode multi-match, changed copy — so an agent knows exactly what class of problem it solves. It never names a sibling tool to distinguish itself from (e.g. validate-selector or get-failure), which keeps it just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description maps each failure condition to the corresponding fix path and states a clear refusal case ("Refuses when the element is truly missing (app bug)"), which implicitly tells the agent to look elsewhere for app bugs. It gives no explicit prerequisite (e.g. "call get-failure first" or which sibling to use when it refuses), so routing is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.