playwright-e2e-mcp

Generate an E2E test

generate-e2e-test

Destructive

Scaffold a runnable Playwright or pytest spec from a description using real project selectors, optionally walking steps on the live page and verifying the spec passes.

Instructions

Scaffold a Playwright test (a .spec.ts, or a test_*.py module in a pytest-playwright project) from a description using the project's REAL selectors. Scans the agent's recent file changes (git working tree / last commit, mtime fallback), extracts data-testid / role / label / placeholder / id locators with their source locations, optionally cross-checks them against the live page, writes a ready-to-run spec, and returns next steps. With steps it walks the flow on the live page instead: each step must work there, the spec replays them, asserts the URL and aria snapshot where the flow landed, and is run once to prove it passes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "description": "<description>"
    },
    "name": "generate-e2e-test"
  }
}

Input Schema

Name	Required	Description
`file`	No	Exact spec path (.spec.ts / .test.ts, or test_*.py in a pytest project) inside the project instead of the default location
`steps`	No	Walk the flow: run these steps on the live page first, then write a spec that replays them and asserts the end state
`write`	No	Write the file to disk (default true)
`config`	No	playwright.config path or 1-based index
`verify`	No	steps: run the written spec once to prove it passes (default true)
`pageUrl`	No	Page the test starts on (default: baseURL from playwright.config)
`project`	No	steps: Playwright project for the verification run
`testDir`	No	Directory for the generated spec (default: detected testDir or tests/)
`overwrite`	No	Replace an existing spec at the target path (only specs this tool generated)
`timeoutMs`	No
`assertScope`	No	steps: CSS scope of the end-state aria snapshot (default 'body')
`description`	Yes	What the test should cover, e.g. "login with valid credentials"
`liveInspect`	No	Verify discovered selectors against the live page (default true when a URL is known)
`projectRoot`	No	Project directory; defaults to the server working directory
`storageState`	No	steps: signed-in session file, also used by the spec

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.15.0Nov 5, 2026

changedInput schema / properties / file / description

Previous value: -"Exact spec path (*.spec.ts / *.test.ts) inside the project instead of the default location"New value: +"Exact spec path (*.spec.ts / *.test.ts, or test_*.py in a pytest project) inside the project instead of the default location"

Changed7 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 / assertScope / maxLength
```
Removed value: -200
```
removedInput schema / properties / description / minLength
```
Removed value: -3
```

changedInput schema / properties / steps / items / properties / type / enum

Previous value: -[
-  "goto",
-  "click",
-  "dblclick",
-  "hover",
-  "fill",
-  "press",
-  "check",
-  "uncheck",
-  "select",
-  "wait"
-]New value: +[
+  "goto",
+  "click",
+  "dblclick",
+  "hover",
+  "fill",
+  "press",
+  "check",
+  "uncheck",
+  "select",
+  "wait",
+  "switchTab"
+]

changedInput schema / properties / steps / items / properties / value / description

Previous value: -"fill text, press key, select option"New value: +"fill text, press key, select option; switchTab: 'last' (default), 'first', a 1-based number, or text in the tab's URL or title"

removedInput schema / properties / steps / maxItems
```
Removed value: -30
```

Changed7 schema fields changedv0.6.1Oct 27, 2026

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

addedInput schema / properties / assertScope

Added value: +{
+  "description": "steps: CSS scope of the end-state aria snapshot (default 'body')",
+  "maxLength": 200,
+  "type": "string"
+}

addedInput schema / properties / project

Added value: +{
+  "description": "steps: Playwright project for the verification run",
+  "type": "string"
+}

addedInput schema / properties / steps

Added value: +{
+  "description": "Walk the flow: run these steps on the live page first, then write a spec that replays them and asserts the end state",
+  "items": {
+    "properties": {
+      "locator": {
+        "description": "Locator or selector, e.g. getByRole('button', { name: 'Next' })",
+        "type": "string"
+      },
+      "ms": {
+        "description": "wait without locator",
+        "maximum": 10000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "type": {
+        "enum": [
+          "goto",
+          "click",
+          "dblclick",
+          "hover",
+          "fill",
+          "press",
+          "check",
+          "uncheck",
+          "select",
+          "wait"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "description": "goto target (may be relative)",
+        "type": "string"
+      },
+      "value": {
+        "description": "fill text, press key, select option",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type"
+    ],
+    "type": "object"
+  },
+  "maxItems": 30,
+  "type": "array"
+}

addedInput schema / properties / storageState

Added value: +{
+  "description": "steps: signed-in session file, also used by the spec",
+  "type": "string"
+}

addedInput schema / properties / timeoutMs

Added value: +{
+  "maximum": 600000,
+  "minimum": 5000,
+  "type": "integer"
+}

addedInput schema / properties / verify

Added value: +{
+  "description": "steps: run the written spec once to prove it passes (default true)",
+  "type": "boolean"
+}

First observedv0.3.2Oct 20, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare write/destructive/openWorld behavior, but the description adds real substance: it explains the git working-tree/last-commit scan with mtime fallback, optional live cross-checking, file writing, and that step-mode specs are executed once to prove they pass. It does not cover timeouts, failure handling, or prerequisites (installed Playwright, config presence), which the destructiveHint warrants.

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?

Two dense sentences that are front-loaded with the core action and the mode distinction; the parenthetical about spec naming is useful rather than filler. The first sentence is long enough that scanning takes effort, but nothing is wasted.

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?

For a 15-parameter tool with no output schema and mutation semantics, the description covers the two modes, the discovery sources, the side effect (writing a spec), and the verification run, which is what an agent needs to select it safely. Gaps remain around failure paths and required environment setup.

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 93%, so the baseline is 3, but the description adds meaning the schema does not: step-mode steps are validated on the live page first and the spec asserts URL and aria snapshot at the landing state, which clarifies `steps`, `assertScope`, `storageState`, and `verify`. The `file`/`projectRoot` interaction with discovery remains implicit.

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

Purpose5/5

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

States a specific verb and artifact ('Scaffold a Playwright test ... .spec.ts or test_*.py') plus the distinctive mechanism (real selectors scraped from the project). The two operating modes, description-driven and `steps`-driven, are spelled out, making it easy to separate from siblings like validate-selector or run-test.

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?

Clearly establishes when each mode applies: a plain description scaffolds a spec from discovered locators, while 'With `steps` it walks the flow on the live page instead'. It does not name alternatives it should be chosen over (e.g. inspect-page for exploration only), so it falls short of full when/when-not routing.

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