playwright-mcp-server

Converts recorded or described browser interactions (clicks, form fills, navigation, assertions) into executable Playwright test code by parsing interaction sequences and mapping them to Playwright API calls. Uses an MCP server architecture to expose test generation as a tool callable from LLM clients (Claude, Cursor), enabling real-time test scaffolding without leaving the editor. Generates syntactically valid TypeScript/JavaScript test files with proper page object patterns and selectors.

Registers test generation capabilities as MCP tools (function definitions with JSON schemas) that LLM clients can discover and invoke. Implements the MCP protocol to expose structured endpoints for test generation, selector extraction, and assertion building, allowing Claude or Cursor to call these tools with typed arguments and receive test code as structured responses. Handles schema validation, error propagation, and response formatting according to MCP specification.

Analyzes DOM elements and generates robust CSS selectors, XPath expressions, or Playwright locators (using getByRole, getByLabel, etc.) for test interactions. Uses heuristics to prefer semantic selectors (role-based, label-based) over fragile ID/class selectors, and generates fallback selectors for resilience. Integrates with Playwright's locator API to produce idiomatic selector code that survives minor DOM changes.

Generates Playwright assertion code (expect() chains) based on described or inferred test conditions, such as element visibility, text content, URL changes, or network requests. Maps natural language assertions ('the button should be disabled', 'the page should show a success message') to idiomatic Playwright expect() syntax with proper matchers (toBeVisible, toContainText, toHaveURL). Supports both synchronous assertions and async wait conditions with configurable timeouts.

Generates page object model (POM) class structures for organizing test code, mapping page elements to reusable methods, and encapsulating selectors and interactions. Creates TypeScript/JavaScript classes with typed methods for common page interactions (click, fill, submit), reducing duplication across tests and improving maintainability. Supports inheritance hierarchies for shared page components and generates factory methods for page instantiation.

Generates complete test suite files with proper setup/teardown hooks (beforeEach, afterEach, beforeAll, afterAll), test structure, and browser context management. Creates test files with Playwright's test runner integration, including fixture definitions, page object imports, and assertion chains. Handles test organization (describe blocks, test naming) and generates configuration for parallel execution, retries, and reporting.

Translates natural language test descriptions (e.g., 'user logs in with valid credentials and sees dashboard') into executable Playwright test code by parsing intent, identifying page interactions, and mapping them to Playwright API calls. Uses LLM context from the MCP client to understand application-specific terminology and generates contextually appropriate test code. Supports multi-step scenarios with branching logic and error handling.

Integrates with Cursor IDE as an MCP server, enabling inline test generation through Cursor's command palette and context menu. Allows developers to highlight code, describe a test scenario, and generate Playwright tests directly in the editor without context switching. Supports Cursor's inline editing and code insertion features, enabling tests to be generated and inserted into the current file or new test files.