playwright-e2e-mcp

Run E2E tests

run-test

DestructiveIdempotent

Runs Playwright tests and reports stats plus each failure's file:line, kind, and message. Diagnoses missing installs, dead servers, syntax errors, crashes, and timeouts while keeping partial results.

Instructions

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.

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": "run-test"
  }
}

Input Schema

Name	Required	Description
`args`	No	Extra Playwright flags from an allowlist, as --flag or --flag=value (e.g. --repeat-each=3, --shard=1/2, --trace=on)
`grep`	No	Only run tests whose title matches this regex
`config`	No	playwright.config path or 1-based index when the project has several configs
`headed`	No	Run with a visible browser window
`browser`	No	Playwright project name to run (matched against playwright.config projects)
`changed`	No	Only test files affected by changes (Playwright --only-changed, follows imports): true = uncommitted changes, or a git ref such as 'origin/main'
`retries`	No
`workers`	No
`testFiles`	No	Test files/directories relative to the project root; "file:line" is supported. Omit to run the whole suite.
`timeoutMs`	No	Hard wall-clock limit for the whole run; the process tree is killed past it (default 120000)
`background`	No	Return a run id at once; poll get-run-status
`lastFailed`	No	Only re-run tests that failed in the previous run (Playwright --last-failed) — the fast fix → re-run loop
`projectRoot`	No	Project directory; defaults to the server working directory
`testTimeoutMs`	No	Per-test timeout passed to Playwright
`retryOnFailure`	No	Auto retry failing tests once before reporting failure (default true; ignored when retries is set)

Output Schema

Name	Required	Description
`ok`	Yes	false when the call failed (see error) or the tests it ran failed
`run`	No
`error`	No
`runId`	No
`status`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.14.0Nov 2, 2026

addedInput schema / properties / changed

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "string"
+    }
+  ],
+  "description": "Only test files affected by changes (Playwright --only-changed, follows imports): true = uncommitted changes, or a git ref such as 'origin/main'"
+}

Changed2 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: -{}
```

Changed1 schema field changedv0.7.0Oct 29, 2026

addedOutput schema / properties / run / properties / quarantined

Added value: +{
+  "description": "failures covered by an active quarantine entry (they do not fail the run)",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed2 schema fields changedv0.6.1Oct 27, 2026

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

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "hint": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "message"
+      ],
+      "type": "object"
+    },
+    "ok": {
+      "description": "false when the call failed (see error) or the tests it ran failed",
+      "type": "boolean"
+    },
+    "run": {
+      "additionalProperties": false,
+      "properties": {
+        "durationMs": {
+          "type": "number"
+        },
+        "exitCode": {
+          "anyOf": [
+            {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "failed": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "failures": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string"
+              },
+              "line": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "message": {
+                "type": "string"
+              },
+              "project": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "tracePath": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "file",
+              "title",
+              "kind",
+              "message"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "failuresTruncated": {
+          "type": "boolean"
+        },
+        "flaky": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "partial": {
+          "type": "boolean"
+        },
+        "passed": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "skipped": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "passed",
+        "failed",
+        "flaky",
+        "skipped",
+        "durationMs",
+        "exitCode",
+        "partial",
+        "failures"
+      ],
+      "type": "object"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedv0.3.2Oct 20, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already flag this as a non-read-only, destructive, open-world operation, so the description's job is to flesh that out — and it does: it diagnoses missing installs, dead dev servers, syntax errors, crashes and timeouts, kills the process tree, retains partial results, reports progress, and records runs for analyze-history. That is meaningful context on failure modes and side effects. What's still unstated is what the destructive scope actually touches (dev servers spawned? ports? files in the tree?) and whether it mutates project state.

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 output, then behavior, then the background mode — a sensible order with no filler sentences. It is dense to the point of compression ("stats plus each failure's file:line, kind and message"), which works here but borders on terse for a 15-parameter tool.

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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile; the remaining description covers failure diagnosis, partial results, progress, and history linkage. Nearly complete for a complex tool, with the main gap being explicit routing to sibling tools (background polling via get-run-status is only referenced in the schema, not the description).

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

Parameters3/5

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

Schema description coverage is 87%, so the schema already carries the parameter burden and baseline 3 applies. The description adds only one param-adjacent detail (background returns a run id, useful for long suites); the 15 parameters, including retries/workers/projectRoot, get no additional semantics from the description.

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?

States a specific verb and resource ("Run the project's Playwright tests") and specifies the return shape (stats plus each failure's file:line, kind, message). That distinguishes it clearly from query-side siblings like get-run-status and get-failure, though those siblings are never named as alternatives.

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

Usage Guidelines3/5

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

There is one genuine conditional: "background: true returns a run id for long suites," which tells the agent when to prefer async execution. Beyond that, usage is only implied — nothing says when to reach for this versus list-tests, diagnose-flaky, or bisect-failure, and no prerequisites (e.g. installs/config presence) are stated.

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