From 79c80ad0032fd89fbe81171ef99e620e6c07bb8b Mon Sep 17 00:00:00 2001 From: Simon Knott Date: Tue, 26 Aug 2025 14:15:23 +0200 Subject: [PATCH 1/5] Add AI section --- ai/intro.mdx | 3 +++ dotnet/docusaurus.config.ts | 16 ++++++++++++++++ java/docusaurus.config.ts | 16 ++++++++++++++++ nodejs/docusaurus.config.ts | 16 ++++++++++++++++ python/docusaurus.config.ts | 16 ++++++++++++++++ sidebarAI.js | 5 +++++ 6 files changed, 72 insertions(+) create mode 100644 ai/intro.mdx create mode 100644 sidebarAI.js diff --git a/ai/intro.mdx b/ai/intro.mdx new file mode 100644 index 00000000000..ef354934229 --- /dev/null +++ b/ai/intro.mdx @@ -0,0 +1,3 @@ +# Intro + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. diff --git a/dotnet/docusaurus.config.ts b/dotnet/docusaurus.config.ts index 87e573cfc5e..27a02391fa3 100644 --- a/dotnet/docusaurus.config.ts +++ b/dotnet/docusaurus.config.ts @@ -33,6 +33,16 @@ let plugins = [ sidebarPath: require.resolve('./sidebarCommunity.js'), }), ], + [ + 'content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'ai', + path: 'ai', + routeBasePath: 'ai', + sidebarPath: require.resolve('./sidebarAI.js'), + }), + ], require.resolve("@docusaurus/plugin-content-pages"), [ require.resolve('@docusaurus/plugin-ideal-image'), @@ -128,6 +138,12 @@ export default { }, ], }, + { + to: '/ai/intro', + label: 'AI', + position: 'left', + activeBaseRegex: `/ai/`, + }, { to: '/community/welcome', label: 'Community', diff --git a/java/docusaurus.config.ts b/java/docusaurus.config.ts index 13350977154..9f6bbf16e61 100644 --- a/java/docusaurus.config.ts +++ b/java/docusaurus.config.ts @@ -33,6 +33,16 @@ let plugins = [ sidebarPath: require.resolve('./sidebarCommunity.js'), }), ], + [ + 'content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'ai', + path: 'ai', + routeBasePath: 'ai', + sidebarPath: require.resolve('./sidebarAI.js'), + }), + ], require.resolve("@docusaurus/plugin-content-pages"), [ require.resolve('@docusaurus/plugin-ideal-image'), @@ -128,6 +138,12 @@ module.exports = { }, ], }, + { + to: '/ai/intro', + label: 'AI', + position: 'left', + activeBaseRegex: `/ai/`, + }, { to: '/community/welcome', label: 'Community', diff --git a/nodejs/docusaurus.config.ts b/nodejs/docusaurus.config.ts index dda2ba3fe0d..ad123210680 100644 --- a/nodejs/docusaurus.config.ts +++ b/nodejs/docusaurus.config.ts @@ -33,6 +33,16 @@ let plugins = [ sidebarPath: require.resolve('./sidebarCommunity.js'), }), ], + [ + 'content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'ai', + path: 'ai', + routeBasePath: 'ai', + sidebarPath: require.resolve('./sidebarAI.js'), + }), + ], require.resolve("@docusaurus/plugin-content-pages"), [ require.resolve('@docusaurus/plugin-ideal-image'), @@ -128,6 +138,12 @@ export default { }, ], }, + { + to: '/ai/intro', + label: 'AI', + position: 'left', + activeBaseRegex: `/ai/`, + }, { to: '/community/welcome', label: 'Community', diff --git a/python/docusaurus.config.ts b/python/docusaurus.config.ts index a6ca1ca4b36..d6e6bea2615 100644 --- a/python/docusaurus.config.ts +++ b/python/docusaurus.config.ts @@ -33,6 +33,16 @@ let plugins = [ sidebarPath: require.resolve('./sidebarCommunity.js'), }), ], + [ + 'content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'ai', + path: 'ai', + routeBasePath: 'ai', + sidebarPath: require.resolve('./sidebarAI.js'), + }), + ], require.resolve("@docusaurus/plugin-content-pages"), [ require.resolve('@docusaurus/plugin-ideal-image'), @@ -128,6 +138,12 @@ export default { }, ], }, + { + to: '/ai/intro', + label: 'AI', + position: 'left', + activeBaseRegex: `/ai/`, + }, { to: '/community/welcome', label: 'Community', diff --git a/sidebarAI.js b/sidebarAI.js new file mode 100644 index 00000000000..ca967c5e948 --- /dev/null +++ b/sidebarAI.js @@ -0,0 +1,5 @@ +module.exports = { + ai: [ + 'intro', + ] +}; From b796fbd81aedc5f1a57682ad19a765a4a1e280cb Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Tue, 2 Sep 2025 22:49:28 +0200 Subject: [PATCH 2/5] docs: mcp first draft for review --- ai/browser-and-emulation.mdx | 150 +++++++++++++++ ai/custom-hosts-and-ports.mdx | 58 ++++++ ai/debugging-and-output.mdx | 58 ++++++ ai/debugging-with-ai.mdx | 85 +++++++++ ai/faq.mdx | 45 +++++ ai/getting-started.mdx | 28 +++ ai/index.mdx | 73 ++++++++ ai/intro.mdx | 3 - ai/mcp-on-ci.mdx | 27 +++ ai/network-and-security.mdx | 112 ++++++++++++ ai/playwright-mcp-browser-automation.mdx | 53 ++++++ ai/playwright-mcp-explore-and-test.mdx | 222 +++++++++++++++++++++++ ai/playwright-mcp-generating-tests.mdx | 191 +++++++++++++++++++ ai/screenshots-pdf-generation.mdx | 83 +++++++++ ai/session-and-state.mdx | 135 ++++++++++++++ ai/troubleshooting-and-tips.mdx | 46 +++++ ai/using-configuration-file.mdx | 44 +++++ ai/verification-tools.mdx | 33 ++++ ai/vision.mdx | 30 +++ sidebarAI.js | 26 ++- 20 files changed, 1498 insertions(+), 4 deletions(-) create mode 100644 ai/browser-and-emulation.mdx create mode 100644 ai/custom-hosts-and-ports.mdx create mode 100644 ai/debugging-and-output.mdx create mode 100644 ai/debugging-with-ai.mdx create mode 100644 ai/faq.mdx create mode 100644 ai/getting-started.mdx create mode 100644 ai/index.mdx delete mode 100644 ai/intro.mdx create mode 100644 ai/mcp-on-ci.mdx create mode 100644 ai/network-and-security.mdx create mode 100644 ai/playwright-mcp-browser-automation.mdx create mode 100644 ai/playwright-mcp-explore-and-test.mdx create mode 100644 ai/playwright-mcp-generating-tests.mdx create mode 100644 ai/screenshots-pdf-generation.mdx create mode 100644 ai/session-and-state.mdx create mode 100644 ai/troubleshooting-and-tips.mdx create mode 100644 ai/using-configuration-file.mdx create mode 100644 ai/verification-tools.mdx create mode 100644 ai/vision.mdx diff --git a/ai/browser-and-emulation.mdx b/ai/browser-and-emulation.mdx new file mode 100644 index 00000000000..992c1e6f637 --- /dev/null +++ b/ai/browser-and-emulation.mdx @@ -0,0 +1,150 @@ +--- +id: browser-and-emulation +title: Browser and Emulation +description: Options for selecting browsers, device emulation, viewport sizes and user agents. +--- + + +These settings let you control which browser Playwright uses and how it simulates devices and environments. Below you'll find concise JSON `mcpServers` examples you can paste into your configuration, along with guidance on when to use each option and a few troubleshooting tips. + +## Choose the right option + +- Browser selection (`--browser`): use when reproducing browser-specific behavior (Chromium, Firefox, WebKit, Edge). +- Device emulation (`--device`): use for responsive layout tests, touch interactions, and mobile-specific features. +- Viewport and user agent (`--viewport-size`, `--user-agent`): useful for targeted layout checks and simulating specific clients. +- Executable path (`--executable-path`): use a system or custom browser build instead of Playwright's bundled browsers. +- Ignore HTTPS errors (`--ignore-https-errors`): only for local development where self-signed certs are unavoidable. + +## Browser Selection + +Using a specific browser (example: msedge): + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--browser", + "msedge" + ] + } + } +} +``` + +### Example Prompt browser selection + +```bash +navigate to playwright.dev and tell me what browser you are using +``` + +If prompted to "Install the browser specified in the config", choose Allow. Playwright will download the required browser if missing, and the run will launch Microsoft Edge (msedge) instead of the default bundled Chromium. + +## Device Emulation + +Emulating a mobile device (example: iPhone 13): + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--device", + "iPhone 13" + ] + } + } +} +``` + +### Example Prompt device emulation + +```bash +navigate to playwright.dev and wait for the page to load, then take a screenshot and save it as iphone13.png +``` + +You should now have a full page screenshot emulating an iPhone 13 device. + +## Custom Viewport + +Setting a custom viewport size (example: 1600x720): + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--viewport-size", + "1600,720" + ] + } + } +} +``` + +### Example Prompt viewport size + +```bash +navigate to playwright.dev and tell me what viewport size is being used +``` + +## Custom User Agent + +Using a custom user agent: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--user-agent", + "MyCustomUserAgent/1.0" + ] + } + } +} +``` + +## Custom Executable Path + +Specifying a browser executable path: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--executable-path", + "/path/to/your/browser" + ] + } + } +} +``` +## Ignore HTTPS Errors + +Ignore HTTPS errors (development only): + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--ignore-https-errors" + ] + } + } +} +``` diff --git a/ai/custom-hosts-and-ports.mdx b/ai/custom-hosts-and-ports.mdx new file mode 100644 index 00000000000..9bc4d99f5c2 --- /dev/null +++ b/ai/custom-hosts-and-ports.mdx @@ -0,0 +1,58 @@ +--- +id: custom-hosts-and-ports +title: Custom Hosts and Ports +description: Running the MCP server on custom hosts/ports, binding behavior and examples for standalone servers. +--- + +## Custom Port & Standalone MCP server + +Use a custom port to avoid conflicts or to run the MCP server as a long lived process (keeping a headed browser open) and let the client connect over HTTP (SSE). + +Steps: +1. In the MCP client config, use a "url" pointing to the running server. +2. In a terminal, start the server: `npx @playwright/mcp@latest --port ` [other flags]` +3. The client reconnects as needed; the browser session persists. + +Headed browser on a machine without display access: +- Start the server where a display exists (desktop, VM with X11/Wayland/xvfb, macOS GUI). +- Remote / IDE processes without DISPLAY just use the url. + +Example: +1. Config: + +```json +{ + "mcpServers": { + "playwright": { + "url": "http://localhost:3001/mcp" + } + } +} +``` + +Run the MCP server in your terminal specifying the port for SSE transport: + +```bash +npx @playwright/mcp@latest --port 3001 +``` +Then in your chat you can ask to navigate to localhost:3001 and use the Playwright MCP server on that port + + +## Binding to a Specific Host + +By default, the MCP server binds to `localhost`. You can change this with the `--host` flag. Use `0.0.0.0` to bind to all available network interfaces. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--host", + "0.0.0.0" + ] + } + } +} +``` diff --git a/ai/debugging-and-output.mdx b/ai/debugging-and-output.mdx new file mode 100644 index 00000000000..81d06c72221 --- /dev/null +++ b/ai/debugging-and-output.mdx @@ -0,0 +1,58 @@ +--- +id: debugging-and-output +title: Debugging and Output +description: Guidance on saving traces, specifying output directories, and other debugging tips for Playwright MCP. +--- + +These settings are useful for development, troubleshooting, and saving artifacts from your sessions. + +### Saving a Trace of the Session + +The Playwright MCP can record a detailed trace of the session, which is invaluable for debugging. Use the `--save-trace` flag to enable this feature. The trace file will be saved in the `.playwright-mcp` directory. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--save-trace" + ] + } + } +} +``` + +Open the saved trace (must be zipped before viewing or sharing): + +1. Locate the trace folder under `.playwright-mcp/` (e.g. `.playwright-mcp/trace-`). +2. Zip it and rename it to `trace.zip`, and then launch the Trace Viewer: + ```bash + npx playwright show-trace trace.zip + ``` + +### Specifying an Output Directory + +You can set a directory for output files, such as traces, screenshots and saved sessions, using the `--output-dir` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--output-dir", + "full/path/to/output/folder" + ] + } + } +} +``` + +Additional tips: +- Use `--output-dir` to collect sessions, saved traces and artifacts for debugging. +- Many tools (PDF export, saved sessions) write to `--output-dir` if set, otherwise `.playwright-mcp/`. + +```` diff --git a/ai/debugging-with-ai.mdx b/ai/debugging-with-ai.mdx new file mode 100644 index 00000000000..d3e4d0f8dcd --- /dev/null +++ b/ai/debugging-with-ai.mdx @@ -0,0 +1,85 @@ +--- +id: debugging-with-ai +title: Debugging with AI +description: Debugging with AI using the copy prompt button and fix with AI feature in VS Code. +--- +import ProgressiveImage from '@theme/ProgressiveImage'; +import LiteYouTube from '@site/src/components/LiteYouTube'; + +# Debugging with AI + +## Overview + +Debugging is a crucial part of the test development lifecycle, but it can often be time-consuming. With the power of AI, you can now accelerate the process of identifying and fixing test failures. This guide will show you how to leverage AI tools like GitHub Copilot directly within your Playwright workflow. You'll learn how to use features like "Copy Prompt" and "Fix with AI" to instantly get suggestions and fix failing tests from the Test Explorer, UI Mode, the HTML report, and the Trace Viewer, turning hours of debugging into minutes. + + + +## 1. Copy Prompt (Faster Test Debugging) +> (Image coming soon: Copy Prompt button in HTML report / trace viewer) + +When a test fails (in the HTML report, trace viewer, or UI mode) a **Copy prompt** button appears beside the error. It copies a pre-filled, context-rich prompt including: +- Error message & stack +- Snippet of the failing test body +- Relevant stdout / stderr (when available) + +Paste it directly into your AI chat and ask: “Suggest the minimal fix and explain why.” This eliminates manual summarizing, reducing time-to-fix. + +### UI Mode Debugging + +For interactive debugging sessions: + +```bash +npx playwright test --ui +``` + +**Workflow:** +1. **Launch UI Mode** using the command above +2. **Run the failing test** within the UI interface +3. **Click "Copy Prompt"** button when a test fails +4. **Paste into Copilot** or your preferred AI tool + +**What the AI Prompt Contains:** +- **Full page snapshot** for visual context +- **Complete error message** with technical details +- **Relevant test code** showing the failing assertion +- **Additional debugging context** for comprehensive analysis + +### HTML Report Analysis + +After running your test suite with a failed test: + +1. **Open the HTML report** (automatically generated on a failed test run) +2. **Navigate to failed tests** +3. **Click "Copy Prompt"** for any failure +4. **Paste into any AI provider** (Copilot, ChatGPT, Claude, etc.) + +This method is excellent for post-execution analysis and sharing debugging context with team members. + +### Trace Viewer Debugging + +For CI/CD and production failure analysis: + +1. **Access the Trace Viewer** for failed tests +2. **Locate the AI prompt button** within the trace interface +3. **Copy the debugging prompt** with full execution context +4. **Analyze with AI tools** even when debugging remotely + +**Advantages:** +- Works with CI failures where you can't run tests locally +- Provides complete execution trace context +- Enables remote debugging capabilities + +## 2. Fix with AI In VS Code + + +When a test fails while in VS Code (with the Playwright VS Code extension), instead of manually analyzing stack traces, Copilot reads the complete context (snapshot diff, test code, error messages) and provides contextual, accurate fix suggestions. This enables one-click problem resolution. + +**Workflow:** +1. **Locate the AI fix button** in the test failure output +2. **Click the button** to trigger AI analysis +3. **Review the suggested fix** from Copilot +4. **Accept the changes** and rerun the test + diff --git a/ai/faq.mdx b/ai/faq.mdx new file mode 100644 index 00000000000..98b851f9be8 --- /dev/null +++ b/ai/faq.mdx @@ -0,0 +1,45 @@ +--- +id: faq +title: "Frequently Asked Questions" +--- + +## FAQ + +### What's the difference between MCP automation and Playwright tests? +MCP sessions are interactive and ephemeral (good for exploration and drafting). Playwright tests are versioned, repeatable code run in CI for regression prevention. + +### When do I use Copy Prompt vs Fix with AI? +Use Copy Prompt to shuttle rich failure context into chat for deeper reasoning. Use Fix with AI for a fast inline suggestion when the change is likely mechanical. + +### Is it safe to paste credentials into chat? +No. Use placeholders (e.g. `{{USER}}`) or storage state. Never paste secrets; rotate dedicated test accounts instead. + +### How do I reuse a logged-in session with AI? +Launch via the MCP browser extension attached to an existing profile or export/import Playwright storage state (`--save-storage` / load in config) before asking the agent to act. + +### Headless or headed for AI-driven workflows? +Start headed while iterating (visual trust), then switch to headless for speed once stable. AI does not "see" pixels—only accessibility data—so headed adds no vision beyond human verification. + +### The agent picked a brittle locator—what now? +Ask MCP to list accessible roles/names for that region and regenerate a semantic locator (`getByRole`, `getByLabel`). Replace rather than layering multiple fallbacks. + +### Can the AI run my whole test suite in CI? +Today it's best used to generate and maintain tests. The suite itself should run via standard `npx playwright test` in CI—AI is optional for interactive repair, not required for execution. + +### When should I promote an automation script into a test? +If you'll reuse it ≥3 times, it guards a critical path, or a failure should block deploys—promote it to a Playwright test or helper library. + +### How do I handle sensitive production data? +Prefer staging. If production is required: least privilege accounts, explicit confirmation prompts, logging of changes, and no credential exposure in chat. + +### Why did Fix with AI suggest an over-simplified change? +Inline fix heuristics optimize for speed. If the suggestion removes meaningful assertions, reject it and ask in chat for a more robust alternative referencing the actual DOM via MCP. + +### Can the agent see dynamically rendered elements? +Yes, once they are in the accessibility tree. If something is missing, ensure the UI has completed rendering (wait for network/animation) before requesting the tree. + +### Does MCP enable image or visual diffing? +No—MCP exposes structured accessibility data, not pixels. Use Playwright's built-in screenshot or snapshot tooling for visual comparisons. + +--- +Have questions not covered here? Open a PR or start a discussion referencing `faq`. diff --git a/ai/getting-started.mdx b/ai/getting-started.mdx new file mode 100644 index 00000000000..ad15c360c9e --- /dev/null +++ b/ai/getting-started.mdx @@ -0,0 +1,28 @@ +--- +id: getting-started +title: Getting Started +description: Quickstart install the Playwright MCP server and configure an MCP client. +--- + +## Getting Started + +The quickest way to get started is to install the Playwright MCP server for your favorite MCP client. For many clients, like VS Code, this is a simple, one-click process. + +Install in VS Code + +This will create a new MCP server configuration in a JSON file in your VS Code settings. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest" + ] + } + } +} +``` + +Once installed, you can start giving the agent commands to control your browser right away. diff --git a/ai/index.mdx b/ai/index.mdx new file mode 100644 index 00000000000..a5339c145dd --- /dev/null +++ b/ai/index.mdx @@ -0,0 +1,73 @@ +--- +id: playwright-mcp +title: "Introduction Playwright MCP" +--- + +## Overview + +We've all been there: repeating the same multi-step process in a browser over and over. Maybe you're filling out similar forms, checking multiple dashboards, or gathering data from different websites. These tasks are perfect for automation, but writing traditional automation scripts can be time-consuming and brittle. + +What if you could describe these tasks in plain English instead? "Fill out this contact form with our company details," or "Navigate to the GitHub issues page and check for any bugs labeled 'critical'." AI agents can now understand these instructions and translate them into browser actions. + +An **AI Agent** is powered by a large language model (LLM) that can parse your natural language instructions and figure out the steps needed to complete a task. But to actually interact with websites, the agent needs tools to control the browser. + +## Model Context Protocol (MCP) + +For an agent to interact with software, it needs a way to communicate. The **Model Context Protocol (MCP)** is that communication standard, think of it as a universal remote control for AI. It defines a common language that allows agents to understand and control different tools. + +- An **MCP Client** is the application where you interact with the agent. This could be your code editor (like VS Code with GitHub Copilot), a dedicated chat application, or a command-line interface. +- An **MCP Server** exposes a set of tools that the agent can use. It's the "hands" that carry out the agent's instructions. + +## Playwright MCP? + +The Playwright MCP is a powerful MCP server that gives an AI agent control over a web browser. It's built on top of [Playwright](https://playwright.dev), the same technology that powers our reliable testing and automation framework. + +Its key advantage is how it "sees" a web page. Instead of looking at pixels on a screen, it uses the browser's **accessibility tree**. This is a structured representation of the page content, similar to what a screen reader uses. This makes it: + +- **Fast and Lightweight:** It doesn't need slow, expensive vision models to understand the page. +- **Reliable and Deterministic:** It interacts with elements based on their role and name, not their position, which is far less brittle than screenshot-based approaches. +- **LLM-Friendly:** It provides clean, structured data that language models can easily understand and act upon. + +## What Can I Use It For? + +The Playwright MCP is a versatile tool that's useful for both developers and anyone looking to automate their web-based workflows. + +- **For Development:** + - **Generate Tests:** Ask an agent to write Playwright tests for you. "Generate a test that adds an item to the shopping cart and checks out." + - **Explore Your Website:** Use the agent to navigate your website and understand its structure and propose possible test cases. + +- **For Automation:** + - **Automate Repetitive Tasks:** Fill out forms, download reports, or perform any other multi-step process on a website. + - **Data Extraction:** Scrape information from web pages and summarize it. + +## Getting Started + +The quickest way to get started is to install the Playwright MCP server for your favorite MCP client. For many clients, like VS Code, this is a simple, one-click process. + +Install in VS Code + +This will create a new MCP server configuration in a JSON file in your VS Code settings. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest" + ] + } + } +} +``` + +Once installed, you can start giving the agent commands to control your browser right away. + +For more installation options and configuration details, see the [Playwright MCP GitHub README](https://github.com/microsoft/playwright-mcp). +For quick installation instructions see the dedicated guide: [Getting Started](getting-started.mdx) +## What's Next? + +Now that you understand the basics, dive into our other guides to see what you can build: + +- [**Guide: Generating Tests with Playwright MCP**](playwright-mcp-generating-tests) +- [**Guide: Using Playwright MCP for Automation**](playwright-mcp-automation) diff --git a/ai/intro.mdx b/ai/intro.mdx deleted file mode 100644 index ef354934229..00000000000 --- a/ai/intro.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Intro - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. diff --git a/ai/mcp-on-ci.mdx b/ai/mcp-on-ci.mdx new file mode 100644 index 00000000000..bcbe567a2e5 --- /dev/null +++ b/ai/mcp-on-ci.mdx @@ -0,0 +1,27 @@ +--- +id: mcp-on-ci +title: MCP on CI +description: Running Playwright MCP headless on CI and tips for stable CI execution. +--- + +By default, Playwright MCP launches a headed browser so you can see the automation happen. For CI/CD environments or when a visible UI is not needed, you can run in headless mode using the `--headless` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--headless" + ] + } + } +} +``` + +## CI tips + +- Prefer `--isolated` for CI to avoid shared profiles. +- Use `--output-dir` to collect traces and artifacts for failing runs. +- Pin browser versions or run `npx playwright install` in CI to ensure browsers are available. diff --git a/ai/network-and-security.mdx b/ai/network-and-security.mdx new file mode 100644 index 00000000000..a76ce521b88 --- /dev/null +++ b/ai/network-and-security.mdx @@ -0,0 +1,112 @@ +--- +id: network-and-security +title: Networking and Security +description: Network, proxy and security-related configuration options for Playwright MCP. +--- + +## Networking and Security + +These options are for configuring proxies, origins, and security policies. + +### Using a Proxy Server + +If you need to route traffic through a proxy, you can use the `--proxy-server` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--proxy-server", + "http://myproxy:3128" + ] + } + } +} +``` + +### Bypassing a Proxy for Specific Domains + +To bypass the proxy for certain domains, use the `--proxy-bypass` flag with a comma-separated list of domains. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--proxy-server", + "http://myproxy:3128", + "--proxy-bypass", + ".com,chromium.org" + ] + } + } +} +``` + +### Allowing and Blocking Origins + +You can control which domains the browser is allowed to access. Use `--allowed-origins` to whitelist specific domains and `--blocked-origins` to blacklist them. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--allowed-origins", + "https://www.microsoft.com", + "--blocked-origins", + "https://www.google.com" + ] + } + } +} +``` + +### Disabling the Sandbox + +In certain restricted environments (like some Docker containers), you may need to disable the browser's sandbox for it to run. Use the `--no-sandbox` flag with caution. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--no-sandbox" + ] + } + } +} +``` + +### Blocking Service Workers + +In some testing scenarios, service workers can interfere with network requests. You can block them entirely with the `--block-service-workers` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--block-service-workers" + ] + } + } +} +``` + +## Security recommendations + +- Restrict `--allowed-origins` when exposing the server on networks. By default the server allows all origins — when running on non-localhost, set an allowlist. +- Use `--host=127.0.0.1` or default `localhost` for local-only usage. Use firewall rules when binding to `0.0.0.0`. +- Avoid running untrusted web content with persistent profiles; prefer `--isolated` for untrusted sessions. diff --git a/ai/playwright-mcp-browser-automation.mdx b/ai/playwright-mcp-browser-automation.mdx new file mode 100644 index 00000000000..624e2ee9303 --- /dev/null +++ b/ai/playwright-mcp-browser-automation.mdx @@ -0,0 +1,53 @@ +--- +id: playwright-mcp-browser-automation +title: 'Browser Automation' +--- + +import LiteYouTube from '@site/src/components/LiteYouTube'; + +# Playwright MCP: AI Browser Control + +## Overview + +Playwright MCP (Model Context Protocol) is a powerful tool that allows AI agents to automate and interact with web browsers. It acts as a server, providing browser automation capabilities through the Playwright framework. This enables Large Language Models (LLMs) like OpenAI or Claude to understand and interact with web pages using structured data from accessibility snapshots, rather than relying on visual information. + +With Playwright MCP, you can instruct an AI to perform tasks like browsing websites, clicking buttons, filling forms, uploading files, and much more. + + + +## Let's Get Started + +In this guide, we'll walk through a simple workflow to demonstrate how you can use Playwright MCP to automate a task on GitHub: navigating to a repository and starring it. + +### Step 1: Navigate to the Repository + +First, instruct the AI to navigate to the Playwright MCP GitHub repository. You can do this with a simple prompt. + +```bash +Go to the Playwright MCP repo +``` + +The AI will use the `browser_navigate` tool from the Playwright MCP server to open the page in a new browser window. + +### Step 2: Sign in to GitHub + +Once on the repository page, the AI will use the `browser_snapshot` tool from the Playwright MCP server to take a page snapshot which is a representation of the current state of the page through the accessibility tree. From this snapshot, it will recognize that to star the repository, you need to be signed in. It will use the `browser_click` tool to automatically click the "Sign in" button. + +For security reasons, it's not recommended to share your credentials with the AI. You can manually enter your username and password in the browser window that Playwright opened and then let the agent continue once you're signed in. + +### Step 3: Star the Repository + +After you've signed in, you can instruct the AI to star the repository. + +```bash +star the repo +``` + +The AI will then perform the action, and you'll see the repository get a new star. + +## Conclusion + +That's a quick look at the power of Playwright MCP. This technology opens up a new world of possibilities for how AI agents can interact with the web. diff --git a/ai/playwright-mcp-explore-and-test.mdx b/ai/playwright-mcp-explore-and-test.mdx new file mode 100644 index 00000000000..025fccfa2a4 --- /dev/null +++ b/ai/playwright-mcp-explore-and-test.mdx @@ -0,0 +1,222 @@ +--- +id: playwright-mcp-explore-and-test +title: Explore and Generate Tests +--- + +import LiteYouTube from '@site/src/components/LiteYouTube'; + +# Playwright MCP: Explore and Generate Tests + +## Overview + +Unleash the power of AI to supercharge your testing workflow. This guide demonstrates how Playwright's Model Context Protocol (MCP) can autonomously explore your web application, discover key user flows, and automatically generate robust end-to-end tests. + + + +## Overview + +What if your tests could write themselves by actually using your app like a real user? The Playwright MCP (Model Context Protocol) in Agent Mode enables AI to explore websites autonomously, detect features, and generate meaningful end-to-end tests automatically. + +This powerful approach allows AI to: +- Navigate through your application like a real user +- Discover functionalities you might have missed +- Identify edge cases and potential bugs +- Generate comprehensive test suites without manual coding +- Provide detailed test execution steps for review + +## Key Features Demonstrated + +### Autonomous Website Exploration +- AI navigates through your application independently +- Discovers key functionalities by interacting with the UI +- Maps out different user workflows and paths +- Identifies interactive elements and features + +### Intelligent Test Generation +- Creates tests based on actual user interactions +- Generates realistic test scenarios +- Writes complete Playwright test files +- Includes proper assertions and test structure + +### Edge Case Detection +As demonstrated in the video, the AI discovered an unexpected edge case: +- Searched for "Star Wars" but received results showing "Kill" +- This revealed a data inconsistency that might have been missed +- Shows how AI exploration can uncover hidden bugs + +### Comprehensive Test Coverage +The AI identified five key functionalities: +1. **Homepage Navigation** - Basic site navigation and layout +2. **Search Functionality** - Movie search with results validation +3. **Movie Details Page** - Individual movie information display +4. **Theme Toggle** - Dark/light mode switching +5. **Navigation Flow** - Overall user journey mapping + +## Implementation Workflow + +### 1. Playwright MCP Server Setup + +Install and start the Playwright MCP server. Here is an example configuration in `mcp.json`: + +```json +{ + "servers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest" + ] + } + } +} +``` + +### 2. Create Exploration Prompt + +The AI uses a specialized prompt for autonomous exploration: +- Instructs the agent to explore the website systematically +- Defines the scope and depth of exploration +- Specifies the number of tests to generate +- Sets parameters for test complexity + +Create a reusable prompt file (e.g., `generate-test.md`) in a prompts folder inside the `.github` directory and add the following content: + +```md +--- +tools: ['playwright'] +mode: 'agent' +--- + +- You are a playwright test generator. +- You are given a scenario and you need to generate a playwright test for it. +- DO NOT generate test code based on the scenario alone. +- DO run steps one by one using the tools provided by the Playwright MCP. +- When asked to explore a website: + 1. Navigate to the specified URL + 2. Explore 1 key functionality of the site and when finished close the browser. + 3. Implement a Playwright TypeScript test that uses @playwright/test based on message history using Playwright's best practices including role based locators, auto retrying assertions and with no added timeouts unless necessary as Playwright has built in retries and autowaiting if the correct locators and assertions are used. +- Save generated test file in the tests directory +- Execute the test file and iterate until the test passes +- Include appropriate assertions to verify the expected behavior +- Structure tests properly with descriptive test titles and comments +``` +### 3. Agent Mode Exploration Process + +To activate agent mode with the exploration prompt: + +1. **Open your AI assistant chat interface** +2. **Enable Agent Mode** in the settings or mode selector +3. **Add the prompt file** (`generate-test.md`) to the conversation context +4. **Execute the exploration command**: + + +```bash +Explore https://debs-obrien.github.io/playwright-movies-app +``` + +The AI will: +1. **Initial Navigation** - AI visits the target website +2. **Feature Discovery** - Systematically explores available functionalities +3. **User Interaction Simulation** - Performs actions like searching, clicking, navigation +4. **Data Collection** - Gathers information about application behavior +5. **Edge Case Investigation** - Tests various input scenarios + +### 4. Test Generation + +After exploration, the agent analyzes its findings and creates a comprehensive summary of discovered functionalities. From this analysis, it intelligently selects the most suitable functionality as the focus for test generation. + +The agent then generates a complete Playwright test file that includes: +- Proper test structure with descriptive names and comments +- Role-based locators following Playwright best practices +- Auto-retrying assertions for robust test execution +- Comprehensive validation of expected behaviors +- Error handling for edge cases discovered during exploration + +```javascript +import { test, expect } from '@playwright/test'; + +test.describe('Movie search', () => { + test('Search for a movie by title', async ({ page }) => { + // Navigate to the movies app + await page.goto('https://debs-obrien.github.io/playwright-movies-app'); + + // Click on the search button to activate the search input + await page.getByRole('search').click(); + + // Type 'Star Wars' into the search input and press Enter + const searchTerm = 'Star Wars'; + await page.getByRole('textbox', { name: 'Search Input' }).fill(searchTerm); + await page.getByRole('textbox', { name: 'Search Input' }).press('Enter'); + + // Verify we're on the search results page with correct title + await expect(page).toHaveTitle(`${searchTerm} - Search Results`); + + // Verify the search results heading contains the search term + await expect(page.getByRole('heading', { level: 1 })).toHaveText(searchTerm); + await expect(page.getByRole('heading', { name: 'search results', level: 2 })).toBeVisible(); + + // Verify that search results are displayed + await expect(page.getByRole('list', { name: 'movies' })).toBeVisible(); + + // Click on a movie from search results + const firstMovie = page.getByRole('list', { name: 'movies' }).getByRole('link').first(); + const movieTitleElement = firstMovie.getByRole('heading', { level: 2 }); + const movieTitle = await movieTitleElement.textContent() || ''; + await firstMovie.click(); + + // Verify that the movie details page is loaded with the correct title + await expect(page.getByRole('heading', { level: 1 })).toHaveText(movieTitle); + + // Verify movie details sections are present + await expect(page.getByText('The Synopsis')).toBeVisible(); + await expect(page.getByText('The Cast')).toBeVisible(); + + // Verify recommended movies section is present + await expect(page.getByRole('heading', { name: 'Recommended Movies' })).toBeVisible(); + + // Go back to search results + await page.getByRole('button', { name: 'Back' }).click(); + + // Verify we're back on the search results page + await expect(page.getByRole('heading', { level: 1 })).toHaveText(searchTerm); + }); +}); +``` + + +## Running the Test +### Test Execution and Validation + +After test generation, the AI automatically executes the test to verify it works correctly. For this example, the generated test passed on the first run. + +You can iterate, refine the prompt, increase test count, or tell the agent to explore different areas. + +## Best Practices + +### Effective Prompting +- **Be Specific**: Define clear exploration boundaries and objectives +- **Set Scope**: Specify how many tests to generate (start with 1-3) +- **Define Focus**: Target specific functionalities or user journeys +- **Include Context**: Provide relevant application information + +### Exploration Strategy +- **Start Simple**: Begin with core functionalities +- **Iterate Gradually**: Expand to more complex scenarios +- **Review Results**: Always examine generated tests and traces +- **Refine Approach**: Adjust prompts based on initial results + +### Test Quality Assurance +- **Validate Logic**: Ensure generated tests make logical sense +- **Check Assertions**: Verify that test assertions are meaningful +- **Review Edge Cases**: Examine discovered edge cases carefully + + +## Additional Resources + +- **Blog Post**: [Detailed setup and implementation guide](https://dev.to/debs_obrien/letting-playwright-mcp-explore-your-site-and-write-your-tests-mf1) +- **MCP Documentation**: Learn more about Model Context Protocol +- **Playwright Test Generation**: Explore other AI-powered testing approaches +- **Agent Mode**: Advanced AI automation techniques diff --git a/ai/playwright-mcp-generating-tests.mdx b/ai/playwright-mcp-generating-tests.mdx new file mode 100644 index 00000000000..481bd5c4553 --- /dev/null +++ b/ai/playwright-mcp-generating-tests.mdx @@ -0,0 +1,191 @@ +--- +id: playwright-mcp-generating-tests +title: "Generating Tests" +--- +# Playwright MCP: Generating Tests + +import LiteYouTube from '@site/src/components/LiteYouTube'; + +## Overview + +Learn how to generate end-to-end Playwright tests using the Playwright MCP (Model Context Protocol) server with GitHub Copilot, even when you don't have access to the source code. This powerful approach enables black-box testing, AI-driven automation, and rapid test generation using natural language descriptions. + + + +## What Makes MCP Different + +Traditional AI code generation with Copilot works great when you have access to source code, but what happens when you only have a URL and a browser? That's where Playwright MCP shines: + +- **No Source Code Required**: Generate tests for any website without needing the underlying codebase +- **Real Browser Interaction**: MCP gives Copilot actual browser access to interact with pages like a real user +- **Page Snapshots**: Uses the accessibility tree to understand UI elements and their accessible names + +## How It Works + +The Playwright MCP server acts as a bridge between GitHub Copilot and a real browser, enabling this workflow: + +1. **Copilot opens a browser** using the MCP server +2. **Navigates to the target website** as specified in a prompt +3. **Takes page snapshots** to understand the page structure and available elements +4. **Interacts with the page** based on the test scenario +5. **Generates a Playwright test file** based on the actions taken +6. **Executes and validates** the generated test + +## Setting Up Your Environment + +### Tools Used + +- **Playwright MCP**: [`https://github.com/microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp) +- **GitHub Copilot**: Agent mode with custom prompts +- **AI Model**: Claude 3.5 Sonnet (or similar LLM that supports MCP) + +## Creating Effective Prompts + +### Reusable Prompt Template + +Create a reusable prompt file (e.g., `generate-test.md`) in a prompts folder inside the `.github` directory: + +```markdown +# Playwright Test Generator Prompt + +- You are a Playwright test generator +- You are given a scenario and you need to generate a Playwright test for it +- DO NOT generate test code based on the scenario alone +- DO run steps one by one using the tools provided by the Playwright MCP +- Only after all steps are completed, emit a Playwright TypeScript test that uses @playwright/test +- Save generated test file in the tests directory +- Execute the test file and iterate until the test passes +``` + +### Example Test Scenarios + +#### Basic Navigation and Search +``` +Generate a Playwright test for the following scenario: +- Navigate to [URL] +- Search for "Garfield" +- Verify the movie is in the search results list +``` + +#### Form Interaction +``` +Generate a Playwright test for the following scenario: +- Navigate to [URL] +- Fill out the contact form with sample data +- Submit the form +- Verify success message appears +``` + +#### Multi-step Workflow +``` +Generate a Playwright test for the following scenario: +- Navigate to [URL] +- Add multiple items to shopping cart +- Proceed to checkout +- Verify cart contents and total +``` + +## Step-by-Step Walkthrough + +### 1. Start with Your Prompt + +1. Drag and drop your reusable prompt file into Copilot chat +2. Add your specific test scenario + +### 2. Watch the Playwright MCP Server in Action + +Playwright MCP will: +- **Open a browser window** automatically +- **Navigate to your target URL** +- **Analyze the page structure** using accessibility snapshots +- **Adapt to UI challenges** (e.g., finding hidden search fields) +- **Perform the required actions** step by step + +### 3. Intelligent Problem Solving + +When the AI encounters issues (like a hidden search input), it will: +- Take a page snapshot to understand the current state +- Identify the correct element to interact with +- Adjust its approach (e.g., click search icon before typing) +- Continue with the test scenario + +### 4. Test Generation and Validation + +Once all actions are completed: +- A complete Playwright test file is generated +- The test is saved to your tests directory +- The test is executed to ensure it passes +- Any issues are debugged and fixed automatically + +## Example Generated Test + +Here's what a typical generated test might look like: + +```typescript +import { test, expect } from '@playwright/test'; + +test('search for Garfield movie', async ({ page }) => { + // Navigate to the website + await page.goto('https://example-movie-site.com'); + + // Click search icon to reveal search input + await page.getByRole('button', { name: 'Search' }).click(); + + // Type search term + await page.getByPlaceholder('Search movies...').fill('Garfield'); + + // Submit search + await page.getByRole('button', { name: 'Search' }).click(); + + // Verify Garfield appears in results + await expect(page.getByText('Garfield')).toBeVisible(); +}); +``` + +## Best Practices + +### Prompt Engineering Tips + +- **Be specific** about the exact steps you want to test +- **Use clear, natural language** descriptions +- **Break complex scenarios** into smaller, manageable steps +- **Specify verification points** clearly + +### Handling Dynamic Content + +- The MCP can adapt to dynamic UIs and changing page structures +- Page snapshots help identify the current state of elements +- Tests are generated based on actual page interaction, not assumptions + +### Iteration and Refinement + +- Generated tests are automatically executed and debugged +- Failed tests trigger automatic iteration until they pass +- You can refine prompts based on generated test quality + +## Limitations and Considerations + +### Context Window Management +- For longer test flows, break them into smaller scenarios +- The LLM may lose context with very complex multi-step workflows +- Consider generating multiple focused tests instead of one large test + +## Next Steps + +After successfully generating tests with Playwright MCP: + +1. **Review and refactor** generated code to match your project standards +2. **Integrate with your CI/CD pipeline** for automated execution +3. **Create reusable prompt templates** for common testing scenarios + +This approach revolutionizes how we think about test automation, making it accessible even when source code isn't available and dramatically speeding up the test creation process. + +## Related Resources + +- [Playwright MCP GitHub Repository](https://github.com/microsoft/playwright-mcp) +- [Example Prompts Repository](https://github.com/debs-obrien/generate-test-with-copilot) +- [Debugging with AI](debugging-with-ai.mdx) +- [Maintaining Tests](playwright-mcp-maintaining-tests) diff --git a/ai/screenshots-pdf-generation.mdx b/ai/screenshots-pdf-generation.mdx new file mode 100644 index 00000000000..faa9cf7c163 --- /dev/null +++ b/ai/screenshots-pdf-generation.mdx @@ -0,0 +1,83 @@ +--- +id: screenshots-pdf-generation +title: Screenshots and PDF Generation +description: enable PDF generation via Playwright MCP, `browser_pdf_save` usage, examples and best practices. +--- + +# Screenshots and PDF Generation + +The Playwright MCP can capture what your users see by taking screenshots or generating print-friendly PDF documents. Use screenshots for visual regression testing, debugging UI failures, or documenting application states. Use PDF generation to create shareable, high-fidelity artifacts of your web content for reports or offline viewing. + +## Screenshots + +Playwright can capture screenshots of the current page via the MCP server. Ask the agent to navigate to a page and save a screenshot with an optional filename. If omitted, a timestamped name like `page-.png` is used. + +Typical flow: +1. Navigate to the page and wait for the UI to load (network idle, images and fonts loaded). +2. Optionally set viewport and expand sections you want visible. +3. Save a screenshot. + +### Example Prompt full page screenshot + +```bash +Navigate to playwright.dev and take a screenshot and save it as playwright.png +``` + +### Example Prompt partial screenshot + +```bash +navigate to playwright.dev and find the footer and take a screenshot of it +``` + +## PDF Generation + +PDF generation is an opt-in capability that lets the agent render the current page to a PDF file which is useful for creating print-friendly versions of web content. + +### Enable the capability + +Add the `--caps=pdf` argument to your Playwright MCP server configuration, for example in your `mcp.json` file: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--caps=pdf" + ] + } + } +} +``` + +### Example Prompt pdf generation + +```bash +navigate to playwright.dev, wait for images to load and save the page as a PDF named "mcp-test.pdf". +``` + +## Setting the Output Directory + +By default the generated PDF is written to the MCP server's artifacts location. If you set `--output-dir` the file will be written there; otherwise the server may use a default like `.playwright-mcp/`. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--caps=pdf", + "--output-dir", + "full/path/to/output/folder" + ] + } + } +} +``` + + + + + diff --git a/ai/session-and-state.mdx b/ai/session-and-state.mdx new file mode 100644 index 00000000000..6ad53213bdd --- /dev/null +++ b/ai/session-and-state.mdx @@ -0,0 +1,135 @@ +--- +id: session-and-state +title: Session and State +description: How to manage sessions, storage state, and user data directories with Playwright MCP. +--- + +These settings are for managing user data, login states, and browser profiles. + +### Starting a Clean Session + +Isolated mode `--isolated` starts each session with a fresh, temporary browser profile. When the browser is closed (or the MCP server restarts), all cookies, localStorage, and other storage for that session are discarded. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--isolated" + ] + } + } +} +``` + +If you need state to persist across runs, avoid `--isolated` and instead use `--save-session` or a user data directory. + +Learn more: https://playwright.dev/docs/auth + +### Persisting Login State + +To avoid logging in every time, you can save your authentication state to a file and reuse it across sessions. Use the `--storage-state` flag and provide a path to your state file. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--isolated", + "--storage-state", + "auth.json" + ] + } + } +} +``` + +### Saving the Session + +To persist the session's state, including cookies and local storage, use the `--save-session` flag. This is useful for tasks that require maintaining a logged-in state across multiple runs. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--isolated", + "--save-session" + ] + } + } +} +``` + +### Using a Custom User Data Directory + +To control where the browser stores its profile data, you can specify a path with the `--user-data-dir` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--user-data-dir", + "path/to/user/data" + ] + } + } +} +``` + +### Connecting to an Existing Browser Session + +You can connect to a running instance of Chrome or Edge using the `--extension` flag. This allows the AI assistant to interact with websites where you're already logged in, using your existing cookies, sessions, and browser state. This requires the "Playwright MCP Bridge" browser extension to be installed. + +#### Extension Installation + +1. **Download the Extension**: Download the latest `chrome-extension.zip` from the [Playwright MCP GitHub releases page](https://github.com/microsoft/playwright-mcp/releases). +2. **Unzip the file**. +3. **Load the Extension**: + * Open your Chrome/Edge browser and navigate to `chrome://extensions/`. + * Enable "Developer mode" using the toggle in the top-right corner. + * Click "Load unpacked" and select the unzipped extension directory. + +Once the extension is installed, you can use the `--extension` flag in your configuration. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--extension" + ] + } + } +} +``` + +### Connecting to a CDP Endpoint + +For advanced use cases, you can connect to a running browser's Chrome DevTools Protocol (CDP) endpoint using the `--cdp-endpoint` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--cdp-endpoint", + "ws://127.0.0.1:9222/devtools/browser/..." + ] + } + } +} +``` diff --git a/ai/troubleshooting-and-tips.mdx b/ai/troubleshooting-and-tips.mdx new file mode 100644 index 00000000000..9afd2a94c4c --- /dev/null +++ b/ai/troubleshooting-and-tips.mdx @@ -0,0 +1,46 @@ +--- +id: troubleshooting-and-tips +title: Troubleshooting & Tips +description: Common troubleshooting steps and tips for working with the Playwright MCP server. +--- + +Quick troubleshooting steps and tips for common problems. + +## Missing browsers + +- Run Playwright's install step in your project or use `browser_install` tooling to fetch browser binaries. + +## Client can't connect + +- Verify `--port` and that no firewall blocks SSE/HTTP. +- Confirm the MCP server `--host` and the client's `url` match (including `/mcp` path). + +## Collecting artifacts + +- Use `--output-dir` to store traces, screenshots and saved sessions. +- Use `--save-trace` and `--save-screenshots` flags where appropriate. + +## Helpful tips + +- Prefer `--isolated` for untrusted pages and CI environments. +- Use `--viewport-size` with consistent dimensions for deterministic visual tests. + + +### Controlling Image Responses + +To save bandwidth, you can prevent the server from sending image data to the client using the `--image-responses` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--image-responses", + "omit" + ] + } + } +} +``` diff --git a/ai/using-configuration-file.mdx b/ai/using-configuration-file.mdx new file mode 100644 index 00000000000..9a92cfc6c0a --- /dev/null +++ b/ai/using-configuration-file.mdx @@ -0,0 +1,44 @@ +--- +id: using-configuration-file +title: Using a Configuration File +description: How to supply a JSON/YAML configuration file to the Playwright MCP server and examples of common settings. +--- + +# Using a Configuration File + +You can specify a path to a configuration file using the `--config` flag. This allows you to manage your settings in a separate file. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--config", + "path/to/your/config.json" + ] + } + } +} +``` + +config.json example: + +```json +{ + "browser": { + "browserName": "edge", + "isolated": true, + "launchOptions": { "headless": true }, + "contextOptions": { "viewport": { "width": 1280, "height": 720 } } + }, + "server": { "host": "0.0.0.0", "port": 8931 }, + "capabilities": ["verify", "pdf"], + "network": { "allowedOrigins": ["https://example.com"], "blockedOrigins": ["https://tracker.example"] }, + "imageResponses": "omit", + "outputDir": "./mcp-output" +} +``` + +Check the [Playwright MCP README](https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#configuration-file) for details on the configuration file format and options. diff --git a/ai/verification-tools.mdx b/ai/verification-tools.mdx new file mode 100644 index 00000000000..af92e637a64 --- /dev/null +++ b/ai/verification-tools.mdx @@ -0,0 +1,33 @@ +--- +id: verification-tools +title: Verification tools +description: How to use the verification tools provided by Playwright MCP (`--caps=verify`). +--- + +## Verify / Verification tools + +Verification tools are opt-in via `--caps=verify` and provide read-only assertions against the page snapshot. + +Tools: +- `browser_verify_element_visible`: Assert an element is visible by accessibility role + accessibleName (preferred; stable). +- `browser_verify_text_visible`: Assert raw text is present (fallback when no suitable role/name; prefer the element variant when possible). +- `browser_verify_list_visible`: Assert a list (e.g. nav, menu, listbox) contains the exact expected items. Provide both a brief human description and the exact snapshot ref plus the expected item strings. +- `browser_verify_value`: Assert an element's current value/state (inputs, selects, checkboxes, radios). For checkboxes/radios use "true"/"false". + +These actions only inspect the page state and return pass/fail results (no mutations), so prefer exact snapshot refs or accessible-role/name matches for reliable verification. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--caps=vision" + ] + } + } +} +``` + +```` diff --git a/ai/vision.mdx b/ai/vision.mdx new file mode 100644 index 00000000000..ac70b1d7970 --- /dev/null +++ b/ai/vision.mdx @@ -0,0 +1,30 @@ +--- +id: vision +title: Vision +description: Enable and configure vision capabilities for Playwright MCP (`--caps=vision`). +--- + +Enable vision with `--caps=vision` to let the agent visually inspect the page. + +Adds coordinate mouse tools: +- `browser_mouse_click_xy` (click) +- `browser_mouse_drag_xy` (press + drag) +- `browser_mouse_move_xy` (hover only) + +All use viewport CSS pixel coords (0,0 top‑left) and require a brief element description for permission. Click/drag mutate page state; move is read-only (hover events only). Use a headed (or virtual) display for reliability. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--caps=vision", + ] + } + } +} +``` + +```` diff --git a/sidebarAI.js b/sidebarAI.js index ca967c5e948..d251b8696ab 100644 --- a/sidebarAI.js +++ b/sidebarAI.js @@ -1,5 +1,29 @@ module.exports = { ai: [ - 'intro', + { type: 'doc', id: 'playwright-mcp' }, + { type: 'doc', id: 'getting-started' }, + { + type: 'category', + label: 'MCP Guides', + collapsed: false, + items: [ + { type: 'doc', id: 'playwright-mcp-browser-automation' }, + { type: 'doc', id: 'playwright-mcp-explore-and-test' }, + { type: 'doc', id: 'playwright-mcp-generating-tests' }, + { type: 'doc', id: 'browser-and-emulation' }, + { type: 'doc', id: 'debugging-and-output' }, + { type: 'doc', id: 'session-and-state' }, + { type: 'doc', id: 'screenshots-pdf-generation' }, + { type: 'doc', id: 'network-and-security' }, + { type: 'doc', id: 'mcp-on-ci' }, + { type: 'doc', id: 'custom-hosts-and-ports' }, + { type: 'doc', id: 'using-configuration-file' }, + { type: 'doc', id: 'vision' }, + { type: 'doc', id: 'verification-tools' }, + ], + }, + { type: 'doc', id: 'troubleshooting-and-tips' }, + { type: 'doc', id: 'faq' }, + { type: 'doc', id: 'debugging-with-ai' }, ] }; From cd6007cec78f74000e62c735a7fc82c18db8bef9 Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Tue, 2 Sep 2025 22:56:33 +0200 Subject: [PATCH 3/5] docs for mcp first draft --- nodejs/docusaurus.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nodejs/docusaurus.config.ts b/nodejs/docusaurus.config.ts index ad123210680..746cd5246c8 100644 --- a/nodejs/docusaurus.config.ts +++ b/nodejs/docusaurus.config.ts @@ -139,7 +139,7 @@ export default { ], }, { - to: '/ai/intro', + to: '/ai', label: 'AI', position: 'left', activeBaseRegex: `/ai/`, From fc7a4bf82ff43605a6940eae79b6296a9efc43ce Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Thu, 4 Sep 2025 11:08:03 +0200 Subject: [PATCH 4/5] fixes from pair programming --- ai/browser-and-emulation.mdx | 156 ++++++++++++++++--- ai/custom-hosts-and-ports.mdx | 58 -------- ai/debugging-and-output.mdx | 58 -------- ai/faq.mdx | 45 ------ ai/getting-started.mdx | 28 ---- ai/index.mdx | 3 +- ai/mcp-on-ci.mdx | 27 ---- ai/network-and-security.mdx | 66 +++----- ai/playwright-mcp-browser-automation.mdx | 5 +- ai/playwright-mcp-explore-and-test.mdx | 17 +-- ai/playwright-mcp-generating-tests.mdx | 3 +- ai/screenshots-pdf-generation.mdx | 83 ----------- ai/session-and-state.mdx | 3 + ai/traces-and-screenshots.mdx | 182 +++++++++++++++++++++++ ai/troubleshooting-and-tips.mdx | 46 ------ ai/using-configuration-file.mdx | 44 ------ ai/verification-tools.mdx | 33 ---- ai/vision.mdx | 30 ---- sidebarAI.js | 29 +--- 19 files changed, 360 insertions(+), 556 deletions(-) delete mode 100644 ai/custom-hosts-and-ports.mdx delete mode 100644 ai/debugging-and-output.mdx delete mode 100644 ai/faq.mdx delete mode 100644 ai/getting-started.mdx delete mode 100644 ai/mcp-on-ci.mdx delete mode 100644 ai/screenshots-pdf-generation.mdx create mode 100644 ai/traces-and-screenshots.mdx delete mode 100644 ai/troubleshooting-and-tips.mdx delete mode 100644 ai/using-configuration-file.mdx delete mode 100644 ai/verification-tools.mdx delete mode 100644 ai/vision.mdx diff --git a/ai/browser-and-emulation.mdx b/ai/browser-and-emulation.mdx index 992c1e6f637..9f46ca69e5b 100644 --- a/ai/browser-and-emulation.mdx +++ b/ai/browser-and-emulation.mdx @@ -1,20 +1,14 @@ --- id: browser-and-emulation -title: Browser and Emulation -description: Options for selecting browsers, device emulation, viewport sizes and user agents. +title: Browser Profiles and Emulation +description: Options for selecting browsers, device emulation, viewport sizes and user agents as well as session and state. --- +# Browser Profiles and Emulation +## Overview These settings let you control which browser Playwright uses and how it simulates devices and environments. Below you'll find concise JSON `mcpServers` examples you can paste into your configuration, along with guidance on when to use each option and a few troubleshooting tips. -## Choose the right option - -- Browser selection (`--browser`): use when reproducing browser-specific behavior (Chromium, Firefox, WebKit, Edge). -- Device emulation (`--device`): use for responsive layout tests, touch interactions, and mobile-specific features. -- Viewport and user agent (`--viewport-size`, `--user-agent`): useful for targeted layout checks and simulating specific clients. -- Executable path (`--executable-path`): use a system or custom browser build instead of Playwright's bundled browsers. -- Ignore HTTPS errors (`--ignore-https-errors`): only for local development where self-signed certs are unavoidable. - ## Browser Selection Using a specific browser (example: msedge): @@ -34,7 +28,7 @@ Using a specific browser (example: msedge): } ``` -### Example Prompt browser selection +#### Example Prompt browser selection ```bash navigate to playwright.dev and tell me what browser you are using @@ -44,7 +38,7 @@ If prompted to "Install the browser specified in the config", choose Allow. Play ## Device Emulation -Emulating a mobile device (example: iPhone 13): +Playwright comes with a [registry of device parameters](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) for selected desktop, tablet and mobile devices. It can be used to simulate browser behavior for a specific device such as user agent, screen size, viewport and if it has touch enabled.Emulating a mobile device (example: iPhone 13): ```json { @@ -61,17 +55,17 @@ Emulating a mobile device (example: iPhone 13): } ``` -### Example Prompt device emulation +#### Example Prompt device emulation ```bash -navigate to playwright.dev and wait for the page to load, then take a screenshot and save it as iphone13.png +navigate to playwright.dev and take a screenshot and save it as iphone13.png ``` You should now have a full page screenshot emulating an iPhone 13 device. ## Custom Viewport -Setting a custom viewport size (example: 1600x720): +Playwright's default viewport is 1280x720. You can set a custom viewport size should you need to (for example: 1600x720). Note that once you set the viewport due to persistent profiles the viewport will remain saved and you will need to reset it if you want to return to the default viewport: ```json { @@ -88,7 +82,7 @@ Setting a custom viewport size (example: 1600x720): } ``` -### Example Prompt viewport size +#### Example Prompt viewport size ```bash navigate to playwright.dev and tell me what viewport size is being used @@ -113,9 +107,9 @@ Using a custom user agent: } ``` -## Custom Executable Path +## Ignore HTTPS Errors -Specifying a browser executable path: +Ignore HTTPS errors (development only): ```json { @@ -124,16 +118,20 @@ Specifying a browser executable path: "command": "npx", "args": [ "@playwright/mcp@latest", - "--executable-path", - "/path/to/your/browser" + "--ignore-https-errors" ] } } } ``` -## Ignore HTTPS Errors -Ignore HTTPS errors (development only): +## Session and State + +Playwright MCP uses persistent profiles by default. This means that user data, login states and cookies are preserved across sessions. + +### Starting a Clean Session + +Isolated mode `--isolated` starts each session with a fresh, temporary browser profile. When the browser is closed (or the MCP server restarts), all cookies, localStorage, and other storage for that session are discarded. ```json { @@ -142,7 +140,119 @@ Ignore HTTPS errors (development only): "command": "npx", "args": [ "@playwright/mcp@latest", - "--ignore-https-errors" + "--isolated" + ] + } + } +} +``` +//TODO Simon check this +If you need state to persist across runs, avoid `--isolated` and instead use `--save-session` or a user data directory. + +Learn more: https://playwright.dev/docs/auth + +### Saving the Session + +To persist the session's state, including cookies and local storage, use the `--save-session` flag. This is useful for tasks that require maintaining a logged-in state across multiple runs. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--isolated", + "--save-session" + ] + } + } +} +``` + +### Loading the Session + +To avoid logging in every time, you can save your authentication state to a file and reuse it across sessions. Use the `--storage-state` flag and provide a path to your state file. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--isolated", + "--storage-state", + "auth.json" + ] + } + } +} +``` + + + +### Using a Custom User Data Directory + +To control where the browser stores its profile data, you can specify a path with the `--user-data-dir` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--user-data-dir", + "path/to/user/data" + ] + } + } +} +``` + +### Connecting to an Existing Browser Session + +You can connect to a running instance of Chrome or Edge using the `--extension` flag. This allows the AI assistant to interact with websites where you're already logged in, using your existing cookies, sessions, and browser state. This requires the "Playwright MCP Bridge" browser extension to be installed. + +#### Extension Installation + +1. **Download the Extension**: Download the latest `chrome-extension.zip` from the [Playwright MCP GitHub releases page](https://github.com/microsoft/playwright-mcp/releases). +2. **Unzip the file**. +3. **Load the Extension**: + * Open your Chrome/Edge browser and navigate to `chrome://extensions/`. + * Enable "Developer mode" using the toggle in the top-right corner. + * Click "Load unpacked" and select the unzipped extension directory. + +Once the extension is installed, you can use the `--extension` flag in your configuration. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--extension" + ] + } + } +} +``` + +### Connecting to a CDP Endpoint + +For advanced use cases, you can connect to a running browser's Chrome DevTools Protocol (CDP) endpoint using the `--cdp-endpoint` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--cdp-endpoint", + "ws://127.0.0.1:9222/devtools/browser/..." ] } } diff --git a/ai/custom-hosts-and-ports.mdx b/ai/custom-hosts-and-ports.mdx deleted file mode 100644 index 9bc4d99f5c2..00000000000 --- a/ai/custom-hosts-and-ports.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -id: custom-hosts-and-ports -title: Custom Hosts and Ports -description: Running the MCP server on custom hosts/ports, binding behavior and examples for standalone servers. ---- - -## Custom Port & Standalone MCP server - -Use a custom port to avoid conflicts or to run the MCP server as a long lived process (keeping a headed browser open) and let the client connect over HTTP (SSE). - -Steps: -1. In the MCP client config, use a "url" pointing to the running server. -2. In a terminal, start the server: `npx @playwright/mcp@latest --port ` [other flags]` -3. The client reconnects as needed; the browser session persists. - -Headed browser on a machine without display access: -- Start the server where a display exists (desktop, VM with X11/Wayland/xvfb, macOS GUI). -- Remote / IDE processes without DISPLAY just use the url. - -Example: -1. Config: - -```json -{ - "mcpServers": { - "playwright": { - "url": "http://localhost:3001/mcp" - } - } -} -``` - -Run the MCP server in your terminal specifying the port for SSE transport: - -```bash -npx @playwright/mcp@latest --port 3001 -``` -Then in your chat you can ask to navigate to localhost:3001 and use the Playwright MCP server on that port - - -## Binding to a Specific Host - -By default, the MCP server binds to `localhost`. You can change this with the `--host` flag. Use `0.0.0.0` to bind to all available network interfaces. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--host", - "0.0.0.0" - ] - } - } -} -``` diff --git a/ai/debugging-and-output.mdx b/ai/debugging-and-output.mdx deleted file mode 100644 index 81d06c72221..00000000000 --- a/ai/debugging-and-output.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -id: debugging-and-output -title: Debugging and Output -description: Guidance on saving traces, specifying output directories, and other debugging tips for Playwright MCP. ---- - -These settings are useful for development, troubleshooting, and saving artifacts from your sessions. - -### Saving a Trace of the Session - -The Playwright MCP can record a detailed trace of the session, which is invaluable for debugging. Use the `--save-trace` flag to enable this feature. The trace file will be saved in the `.playwright-mcp` directory. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--save-trace" - ] - } - } -} -``` - -Open the saved trace (must be zipped before viewing or sharing): - -1. Locate the trace folder under `.playwright-mcp/` (e.g. `.playwright-mcp/trace-`). -2. Zip it and rename it to `trace.zip`, and then launch the Trace Viewer: - ```bash - npx playwright show-trace trace.zip - ``` - -### Specifying an Output Directory - -You can set a directory for output files, such as traces, screenshots and saved sessions, using the `--output-dir` flag. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--output-dir", - "full/path/to/output/folder" - ] - } - } -} -``` - -Additional tips: -- Use `--output-dir` to collect sessions, saved traces and artifacts for debugging. -- Many tools (PDF export, saved sessions) write to `--output-dir` if set, otherwise `.playwright-mcp/`. - -```` diff --git a/ai/faq.mdx b/ai/faq.mdx deleted file mode 100644 index 98b851f9be8..00000000000 --- a/ai/faq.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -id: faq -title: "Frequently Asked Questions" ---- - -## FAQ - -### What's the difference between MCP automation and Playwright tests? -MCP sessions are interactive and ephemeral (good for exploration and drafting). Playwright tests are versioned, repeatable code run in CI for regression prevention. - -### When do I use Copy Prompt vs Fix with AI? -Use Copy Prompt to shuttle rich failure context into chat for deeper reasoning. Use Fix with AI for a fast inline suggestion when the change is likely mechanical. - -### Is it safe to paste credentials into chat? -No. Use placeholders (e.g. `{{USER}}`) or storage state. Never paste secrets; rotate dedicated test accounts instead. - -### How do I reuse a logged-in session with AI? -Launch via the MCP browser extension attached to an existing profile or export/import Playwright storage state (`--save-storage` / load in config) before asking the agent to act. - -### Headless or headed for AI-driven workflows? -Start headed while iterating (visual trust), then switch to headless for speed once stable. AI does not "see" pixels—only accessibility data—so headed adds no vision beyond human verification. - -### The agent picked a brittle locator—what now? -Ask MCP to list accessible roles/names for that region and regenerate a semantic locator (`getByRole`, `getByLabel`). Replace rather than layering multiple fallbacks. - -### Can the AI run my whole test suite in CI? -Today it's best used to generate and maintain tests. The suite itself should run via standard `npx playwright test` in CI—AI is optional for interactive repair, not required for execution. - -### When should I promote an automation script into a test? -If you'll reuse it ≥3 times, it guards a critical path, or a failure should block deploys—promote it to a Playwright test or helper library. - -### How do I handle sensitive production data? -Prefer staging. If production is required: least privilege accounts, explicit confirmation prompts, logging of changes, and no credential exposure in chat. - -### Why did Fix with AI suggest an over-simplified change? -Inline fix heuristics optimize for speed. If the suggestion removes meaningful assertions, reject it and ask in chat for a more robust alternative referencing the actual DOM via MCP. - -### Can the agent see dynamically rendered elements? -Yes, once they are in the accessibility tree. If something is missing, ensure the UI has completed rendering (wait for network/animation) before requesting the tree. - -### Does MCP enable image or visual diffing? -No—MCP exposes structured accessibility data, not pixels. Use Playwright's built-in screenshot or snapshot tooling for visual comparisons. - ---- -Have questions not covered here? Open a PR or start a discussion referencing `faq`. diff --git a/ai/getting-started.mdx b/ai/getting-started.mdx deleted file mode 100644 index ad15c360c9e..00000000000 --- a/ai/getting-started.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: getting-started -title: Getting Started -description: Quickstart install the Playwright MCP server and configure an MCP client. ---- - -## Getting Started - -The quickest way to get started is to install the Playwright MCP server for your favorite MCP client. For many clients, like VS Code, this is a simple, one-click process. - -Install in VS Code - -This will create a new MCP server configuration in a JSON file in your VS Code settings. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest" - ] - } - } -} -``` - -Once installed, you can start giving the agent commands to control your browser right away. diff --git a/ai/index.mdx b/ai/index.mdx index a5339c145dd..78ad800f79a 100644 --- a/ai/index.mdx +++ b/ai/index.mdx @@ -1,6 +1,7 @@ --- id: playwright-mcp title: "Introduction Playwright MCP" +description: Introduction to Playwright MCP, an MCP server that gives AI agents control over a web browser using Playwright. --- ## Overview @@ -64,7 +65,7 @@ This will create a new MCP server configuration in a JSON file in your VS Code s Once installed, you can start giving the agent commands to control your browser right away. For more installation options and configuration details, see the [Playwright MCP GitHub README](https://github.com/microsoft/playwright-mcp). -For quick installation instructions see the dedicated guide: [Getting Started](getting-started.mdx) + ## What's Next? Now that you understand the basics, dive into our other guides to see what you can build: diff --git a/ai/mcp-on-ci.mdx b/ai/mcp-on-ci.mdx deleted file mode 100644 index bcbe567a2e5..00000000000 --- a/ai/mcp-on-ci.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: mcp-on-ci -title: MCP on CI -description: Running Playwright MCP headless on CI and tips for stable CI execution. ---- - -By default, Playwright MCP launches a headed browser so you can see the automation happen. For CI/CD environments or when a visible UI is not needed, you can run in headless mode using the `--headless` flag. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--headless" - ] - } - } -} -``` - -## CI tips - -- Prefer `--isolated` for CI to avoid shared profiles. -- Use `--output-dir` to collect traces and artifacts for failing runs. -- Pin browser versions or run `npx playwright install` in CI to ensure browsers are available. diff --git a/ai/network-and-security.mdx b/ai/network-and-security.mdx index a76ce521b88..8168b73dadd 100644 --- a/ai/network-and-security.mdx +++ b/ai/network-and-security.mdx @@ -3,33 +3,17 @@ id: network-and-security title: Networking and Security description: Network, proxy and security-related configuration options for Playwright MCP. --- +# Networking and Security -## Networking and Security +## Overview -These options are for configuring proxies, origins, and security policies. +Never use Playwright or Playwright MCP to browse untrusted web content. -### Using a Proxy Server +These options are for configuring proxies, origins, and security policies. To learn more about session and state see our guide: [Session and State](session-and-state.mdx). -If you need to route traffic through a proxy, you can use the `--proxy-server` flag. +## Allowing and Blocking Origins -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--proxy-server", - "http://myproxy:3128" - ] - } - } -} -``` - -### Bypassing a Proxy for Specific Domains - -To bypass the proxy for certain domains, use the `--proxy-bypass` flag with a comma-separated list of domains. +You can control which domains the browser is allowed to access. Use `--allowed-origins` to whitelist specific domains and `--blocked-origins` to blacklist them. ```json { @@ -38,19 +22,19 @@ To bypass the proxy for certain domains, use the `--proxy-bypass` flag with a co "command": "npx", "args": [ "@playwright/mcp@latest", - "--proxy-server", - "http://myproxy:3128", - "--proxy-bypass", - ".com,chromium.org" + "--allowed-origins", + "https://www.microsoft.com", + "--blocked-origins", + "https://www.google.com" ] } } } ``` -### Allowing and Blocking Origins +## Blocking Service Workers -You can control which domains the browser is allowed to access. Use `--allowed-origins` to whitelist specific domains and `--blocked-origins` to blacklist them. +In some testing scenarios, service workers can interfere with network requests. You can block them entirely with the `--block-service-workers` flag. ```json { @@ -59,19 +43,16 @@ You can control which domains the browser is allowed to access. Use `--allowed-o "command": "npx", "args": [ "@playwright/mcp@latest", - "--allowed-origins", - "https://www.microsoft.com", - "--blocked-origins", - "https://www.google.com" + "--block-service-workers" ] } } } ``` -### Disabling the Sandbox +## Using a Proxy Server -In certain restricted environments (like some Docker containers), you may need to disable the browser's sandbox for it to run. Use the `--no-sandbox` flag with caution. +If you need to route traffic through a proxy, you can use the `--proxy-server` flag. ```json { @@ -80,16 +61,15 @@ In certain restricted environments (like some Docker containers), you may need t "command": "npx", "args": [ "@playwright/mcp@latest", - "--no-sandbox" + "--proxy-server", + "http://myproxy:3128" ] } } } ``` -### Blocking Service Workers - -In some testing scenarios, service workers can interfere with network requests. You can block them entirely with the `--block-service-workers` flag. +To bypass the proxy for certain domains, use the `--proxy-bypass` flag with a comma-separated list of domains. ```json { @@ -98,15 +78,13 @@ In some testing scenarios, service workers can interfere with network requests. "command": "npx", "args": [ "@playwright/mcp@latest", - "--block-service-workers" + "--proxy-server", + "http://myproxy:3128", + "--proxy-bypass", + ".com,chromium.org" ] } } } ``` -## Security recommendations - -- Restrict `--allowed-origins` when exposing the server on networks. By default the server allows all origins — when running on non-localhost, set an allowlist. -- Use `--host=127.0.0.1` or default `localhost` for local-only usage. Use firewall rules when binding to `0.0.0.0`. -- Avoid running untrusted web content with persistent profiles; prefer `--isolated` for untrusted sessions. diff --git a/ai/playwright-mcp-browser-automation.mdx b/ai/playwright-mcp-browser-automation.mdx index 624e2ee9303..1dba5ef8419 100644 --- a/ai/playwright-mcp-browser-automation.mdx +++ b/ai/playwright-mcp-browser-automation.mdx @@ -1,11 +1,12 @@ --- id: playwright-mcp-browser-automation -title: 'Browser Automation' +title: Browser Automation +description: Playwright MCP enables AI agents to control a web browser using Playwright for tasks like navigation, clicking, and form filling. --- import LiteYouTube from '@site/src/components/LiteYouTube'; -# Playwright MCP: AI Browser Control +# Browser Automation with Playwright MCP ## Overview diff --git a/ai/playwright-mcp-explore-and-test.mdx b/ai/playwright-mcp-explore-and-test.mdx index 025fccfa2a4..480ec295706 100644 --- a/ai/playwright-mcp-explore-and-test.mdx +++ b/ai/playwright-mcp-explore-and-test.mdx @@ -1,6 +1,7 @@ --- id: playwright-mcp-explore-and-test -title: Explore and Generate Tests +title: Explore and Generate Test +description: Playwright MCP can autonomously explore your web application and generate end-to-end tests automatically. --- import LiteYouTube from '@site/src/components/LiteYouTube'; @@ -9,15 +10,6 @@ import LiteYouTube from '@site/src/components/LiteYouTube'; ## Overview -Unleash the power of AI to supercharge your testing workflow. This guide demonstrates how Playwright's Model Context Protocol (MCP) can autonomously explore your web application, discover key user flows, and automatically generate robust end-to-end tests. - - - -## Overview - What if your tests could write themselves by actually using your app like a real user? The Playwright MCP (Model Context Protocol) in Agent Mode enables AI to explore websites autonomously, detect features, and generate meaningful end-to-end tests automatically. This powerful approach allows AI to: @@ -27,6 +19,11 @@ This powerful approach allows AI to: - Generate comprehensive test suites without manual coding - Provide detailed test execution steps for review + + ## Key Features Demonstrated ### Autonomous Website Exploration diff --git a/ai/playwright-mcp-generating-tests.mdx b/ai/playwright-mcp-generating-tests.mdx index 481bd5c4553..04fedf0d6ee 100644 --- a/ai/playwright-mcp-generating-tests.mdx +++ b/ai/playwright-mcp-generating-tests.mdx @@ -1,6 +1,7 @@ --- id: playwright-mcp-generating-tests -title: "Generating Tests" +title: Generating Tests +description: Learn how to generate end-to-end Playwright tests using Playwright MCP with GitHub Copilot, even without access to source code. --- # Playwright MCP: Generating Tests diff --git a/ai/screenshots-pdf-generation.mdx b/ai/screenshots-pdf-generation.mdx deleted file mode 100644 index faa9cf7c163..00000000000 --- a/ai/screenshots-pdf-generation.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: screenshots-pdf-generation -title: Screenshots and PDF Generation -description: enable PDF generation via Playwright MCP, `browser_pdf_save` usage, examples and best practices. ---- - -# Screenshots and PDF Generation - -The Playwright MCP can capture what your users see by taking screenshots or generating print-friendly PDF documents. Use screenshots for visual regression testing, debugging UI failures, or documenting application states. Use PDF generation to create shareable, high-fidelity artifacts of your web content for reports or offline viewing. - -## Screenshots - -Playwright can capture screenshots of the current page via the MCP server. Ask the agent to navigate to a page and save a screenshot with an optional filename. If omitted, a timestamped name like `page-.png` is used. - -Typical flow: -1. Navigate to the page and wait for the UI to load (network idle, images and fonts loaded). -2. Optionally set viewport and expand sections you want visible. -3. Save a screenshot. - -### Example Prompt full page screenshot - -```bash -Navigate to playwright.dev and take a screenshot and save it as playwright.png -``` - -### Example Prompt partial screenshot - -```bash -navigate to playwright.dev and find the footer and take a screenshot of it -``` - -## PDF Generation - -PDF generation is an opt-in capability that lets the agent render the current page to a PDF file which is useful for creating print-friendly versions of web content. - -### Enable the capability - -Add the `--caps=pdf` argument to your Playwright MCP server configuration, for example in your `mcp.json` file: - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--caps=pdf" - ] - } - } -} -``` - -### Example Prompt pdf generation - -```bash -navigate to playwright.dev, wait for images to load and save the page as a PDF named "mcp-test.pdf". -``` - -## Setting the Output Directory - -By default the generated PDF is written to the MCP server's artifacts location. If you set `--output-dir` the file will be written there; otherwise the server may use a default like `.playwright-mcp/`. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--caps=pdf", - "--output-dir", - "full/path/to/output/folder" - ] - } - } -} -``` - - - - - diff --git a/ai/session-and-state.mdx b/ai/session-and-state.mdx index 6ad53213bdd..a4f5f109140 100644 --- a/ai/session-and-state.mdx +++ b/ai/session-and-state.mdx @@ -3,6 +3,9 @@ id: session-and-state title: Session and State description: How to manage sessions, storage state, and user data directories with Playwright MCP. --- +# Session and State + +## Overview These settings are for managing user data, login states, and browser profiles. diff --git a/ai/traces-and-screenshots.mdx b/ai/traces-and-screenshots.mdx new file mode 100644 index 00000000000..afd45495fae --- /dev/null +++ b/ai/traces-and-screenshots.mdx @@ -0,0 +1,182 @@ +--- +id: traces-and-screenshots +title: Traces and Screenshots +description: Guidance on saving traces, specifying output directories, and other debugging tips for Playwright MCP. +--- +# Traces and Screenshots + +## Overview + +When working with Playwright MCP, it's often helpful to save traces and other output artifacts for debugging and analysis such as screenshots and PDFs. + +These settings are useful for development, troubleshooting, and saving artifacts from your sessions. + +### Saving a Trace of the Session + +The Playwright MCP can record a detailed trace of the session, which is invaluable for debugging. Use the `--save-trace` flag to enable this feature. The trace file will be saved in the `.playwright-mcp` directory. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--save-trace" + ] + } + } +} +``` + +Open the saved trace (must be zipped before viewing or sharing): + +1. Locate the trace folder under `.playwright-mcp/` (e.g. `.playwright-mcp/trace-`). +2. Zip it and rename it to `trace.zip`, and then launch the Trace Viewer: + ```bash + npx playwright show-trace trace.zip + ``` + + +## Screenshots + +Playwright can capture screenshots of the current page via the MCP server. Ask the agent to navigate to a page and save a screenshot with an optional filename. If omitted, a timestamped name like `page-.png` is used. + +Typical flow: +1. Navigate to the page and wait for the UI to load (network idle, images and fonts loaded). +2. Optionally set viewport and expand sections you want visible. +3. Save a screenshot. + +### Example Prompt full page screenshot + +```bash +Navigate to playwright.dev and take a screenshot and save it as playwright.png +``` + +### Example Prompt partial screenshot + +```bash +navigate to playwright.dev and find the footer and take a screenshot of it +``` + +## PDF Generation + +PDF generation is an opt-in capability that lets the agent render the current page to a PDF file which is useful for creating print-friendly versions of web content. + +### Enable the capability + +Add the `--caps=pdf` argument to your Playwright MCP server configuration, for example in your `mcp.json` file: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--caps=pdf" + ] + } + } +} +``` + +### Example Prompt pdf generation + +```bash +navigate to playwright.dev, wait for images to load and save the page as a PDF named "mcp-test.pdf". +``` + +## Setting the Output Directory + +By default the generated PDF is written to the MCP server's artifacts location. If you set `--output-dir` the file will be written there; otherwise the server may use a default like `.playwright-mcp/`. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--output-dir", + "full/path/to/output/folder" + ] + } + } +} +``` + +## Agents on CI + +Agents on CI are great because they can run unattended, on a schedule, and at scale. This is perfect for tasks like: +- Automated testing +- Data extraction +- Monitoring web pages for changes +- Filling out forms or submitting data +- Generating reports +However, running agents on CI comes with its own set of challenges. Here are some tips to help you get started. + +## Headless Mode + +By default, Playwright MCP launches a headed browser so you can see the automation happen. For CI/CD environments or when a visible UI is not needed, you can run in headless mode using the `--headless` flag. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--headless" + ] + } + } +} +``` +## CI tips + +- Use `--output-dir` to collect traces and artifacts for failing runs. +- use `--save-traces` to capture traces for all runs. +- Pin browser versions or run `npx playwright install` in CI to ensure browsers are available. + + +## Using a Configuration File + +You can specify a path to a configuration file using the `--config` flag. This allows you to manage your settings in a separate file. + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "@playwright/mcp@latest", + "--config", + "path/to/your/config.json" + ] + } + } +} +``` + +config.json example: + +```json +{ + "browser": { + "browserName": "edge", + "isolated": true, + "launchOptions": { "headless": true }, + "contextOptions": { "viewport": { "width": 1280, "height": 720 } } + }, + "server": { "host": "0.0.0.0", "port": 8931 }, + "capabilities": ["verify", "pdf"], + "network": { "allowedOrigins": ["https://example.com"], "blockedOrigins": ["https://tracker.example"] }, + "imageResponses": "omit", + "outputDir": "./mcp-output" +} +``` + +Check the [Playwright MCP README](https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#configuration-file) for details on the configuration file format and options. + + diff --git a/ai/troubleshooting-and-tips.mdx b/ai/troubleshooting-and-tips.mdx deleted file mode 100644 index 9afd2a94c4c..00000000000 --- a/ai/troubleshooting-and-tips.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: troubleshooting-and-tips -title: Troubleshooting & Tips -description: Common troubleshooting steps and tips for working with the Playwright MCP server. ---- - -Quick troubleshooting steps and tips for common problems. - -## Missing browsers - -- Run Playwright's install step in your project or use `browser_install` tooling to fetch browser binaries. - -## Client can't connect - -- Verify `--port` and that no firewall blocks SSE/HTTP. -- Confirm the MCP server `--host` and the client's `url` match (including `/mcp` path). - -## Collecting artifacts - -- Use `--output-dir` to store traces, screenshots and saved sessions. -- Use `--save-trace` and `--save-screenshots` flags where appropriate. - -## Helpful tips - -- Prefer `--isolated` for untrusted pages and CI environments. -- Use `--viewport-size` with consistent dimensions for deterministic visual tests. - - -### Controlling Image Responses - -To save bandwidth, you can prevent the server from sending image data to the client using the `--image-responses` flag. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--image-responses", - "omit" - ] - } - } -} -``` diff --git a/ai/using-configuration-file.mdx b/ai/using-configuration-file.mdx deleted file mode 100644 index 9a92cfc6c0a..00000000000 --- a/ai/using-configuration-file.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: using-configuration-file -title: Using a Configuration File -description: How to supply a JSON/YAML configuration file to the Playwright MCP server and examples of common settings. ---- - -# Using a Configuration File - -You can specify a path to a configuration file using the `--config` flag. This allows you to manage your settings in a separate file. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--config", - "path/to/your/config.json" - ] - } - } -} -``` - -config.json example: - -```json -{ - "browser": { - "browserName": "edge", - "isolated": true, - "launchOptions": { "headless": true }, - "contextOptions": { "viewport": { "width": 1280, "height": 720 } } - }, - "server": { "host": "0.0.0.0", "port": 8931 }, - "capabilities": ["verify", "pdf"], - "network": { "allowedOrigins": ["https://example.com"], "blockedOrigins": ["https://tracker.example"] }, - "imageResponses": "omit", - "outputDir": "./mcp-output" -} -``` - -Check the [Playwright MCP README](https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#configuration-file) for details on the configuration file format and options. diff --git a/ai/verification-tools.mdx b/ai/verification-tools.mdx deleted file mode 100644 index af92e637a64..00000000000 --- a/ai/verification-tools.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -id: verification-tools -title: Verification tools -description: How to use the verification tools provided by Playwright MCP (`--caps=verify`). ---- - -## Verify / Verification tools - -Verification tools are opt-in via `--caps=verify` and provide read-only assertions against the page snapshot. - -Tools: -- `browser_verify_element_visible`: Assert an element is visible by accessibility role + accessibleName (preferred; stable). -- `browser_verify_text_visible`: Assert raw text is present (fallback when no suitable role/name; prefer the element variant when possible). -- `browser_verify_list_visible`: Assert a list (e.g. nav, menu, listbox) contains the exact expected items. Provide both a brief human description and the exact snapshot ref plus the expected item strings. -- `browser_verify_value`: Assert an element's current value/state (inputs, selects, checkboxes, radios). For checkboxes/radios use "true"/"false". - -These actions only inspect the page state and return pass/fail results (no mutations), so prefer exact snapshot refs or accessible-role/name matches for reliable verification. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--caps=vision" - ] - } - } -} -``` - -```` diff --git a/ai/vision.mdx b/ai/vision.mdx deleted file mode 100644 index ac70b1d7970..00000000000 --- a/ai/vision.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -id: vision -title: Vision -description: Enable and configure vision capabilities for Playwright MCP (`--caps=vision`). ---- - -Enable vision with `--caps=vision` to let the agent visually inspect the page. - -Adds coordinate mouse tools: -- `browser_mouse_click_xy` (click) -- `browser_mouse_drag_xy` (press + drag) -- `browser_mouse_move_xy` (hover only) - -All use viewport CSS pixel coords (0,0 top‑left) and require a brief element description for permission. Click/drag mutate page state; move is read-only (hover events only). Use a headed (or virtual) display for reliability. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest", - "--caps=vision", - ] - } - } -} -``` - -```` diff --git a/sidebarAI.js b/sidebarAI.js index d251b8696ab..c9bf3f56df2 100644 --- a/sidebarAI.js +++ b/sidebarAI.js @@ -1,29 +1,12 @@ module.exports = { ai: [ { type: 'doc', id: 'playwright-mcp' }, - { type: 'doc', id: 'getting-started' }, - { - type: 'category', - label: 'MCP Guides', - collapsed: false, - items: [ - { type: 'doc', id: 'playwright-mcp-browser-automation' }, - { type: 'doc', id: 'playwright-mcp-explore-and-test' }, - { type: 'doc', id: 'playwright-mcp-generating-tests' }, - { type: 'doc', id: 'browser-and-emulation' }, - { type: 'doc', id: 'debugging-and-output' }, - { type: 'doc', id: 'session-and-state' }, - { type: 'doc', id: 'screenshots-pdf-generation' }, - { type: 'doc', id: 'network-and-security' }, - { type: 'doc', id: 'mcp-on-ci' }, - { type: 'doc', id: 'custom-hosts-and-ports' }, - { type: 'doc', id: 'using-configuration-file' }, - { type: 'doc', id: 'vision' }, - { type: 'doc', id: 'verification-tools' }, - ], - }, - { type: 'doc', id: 'troubleshooting-and-tips' }, - { type: 'doc', id: 'faq' }, + { type: 'doc', id: 'playwright-mcp-browser-automation' }, + { type: 'doc', id: 'playwright-mcp-explore-and-test' }, + { type: 'doc', id: 'playwright-mcp-generating-tests' }, + { type: 'doc', id: 'browser-and-emulation' }, + { type: 'doc', id: 'traces-and-screenshots' }, + { type: 'doc', id: 'network-and-security' }, { type: 'doc', id: 'debugging-with-ai' }, ] }; From a75bb1480517b8aa2c7e2b1eb190964528d8e141 Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Thu, 4 Sep 2025 22:11:20 +0200 Subject: [PATCH 5/5] refactor(docs): update Playwright MCP documentation for clarity and structure --- ai/playwright-mcp-explore-and-test.mdx | 181 ++++++------------------ ai/playwright-mcp-generating-tests.mdx | 182 +++++-------------------- 2 files changed, 76 insertions(+), 287 deletions(-) diff --git a/ai/playwright-mcp-explore-and-test.mdx b/ai/playwright-mcp-explore-and-test.mdx index 480ec295706..fd3e022b1ec 100644 --- a/ai/playwright-mcp-explore-and-test.mdx +++ b/ai/playwright-mcp-explore-and-test.mdx @@ -6,11 +6,11 @@ description: Playwright MCP can autonomously explore your web application and ge import LiteYouTube from '@site/src/components/LiteYouTube'; -# Playwright MCP: Explore and Generate Tests +# Let AI Explore Your Site & Write Tests with Playwright MCP ## Overview -What if your tests could write themselves by actually using your app like a real user? The Playwright MCP (Model Context Protocol) in Agent Mode enables AI to explore websites autonomously, detect features, and generate meaningful end-to-end tests automatically. +The Playwright MCP (Model Context Protocol) in Agent Mode enables AI to explore websites autonomously, detect bugs, and generate meaningful end-to-end tests automatically. This powerful approach allows AI to: - Navigate through your application like a real user @@ -19,201 +19,108 @@ This powerful approach allows AI to: - Generate comprehensive test suites without manual coding - Provide detailed test execution steps for review +While human oversight remains important, the combination of AI exploration and automated test generation provides a powerful foundation for modern web application testing. + -## Key Features Demonstrated - -### Autonomous Website Exploration -- AI navigates through your application independently -- Discovers key functionalities by interacting with the UI -- Maps out different user workflows and paths -- Identifies interactive elements and features - -### Intelligent Test Generation -- Creates tests based on actual user interactions -- Generates realistic test scenarios -- Writes complete Playwright test files -- Includes proper assertions and test structure - -### Edge Case Detection -As demonstrated in the video, the AI discovered an unexpected edge case: -- Searched for "Star Wars" but received results showing "Kill" -- This revealed a data inconsistency that might have been missed -- Shows how AI exploration can uncover hidden bugs - -### Comprehensive Test Coverage -The AI identified five key functionalities: -1. **Homepage Navigation** - Basic site navigation and layout -2. **Search Functionality** - Movie search with results validation -3. **Movie Details Page** - Individual movie information display -4. **Theme Toggle** - Dark/light mode switching -5. **Navigation Flow** - Overall user journey mapping - -## Implementation Workflow - -### 1. Playwright MCP Server Setup - -Install and start the Playwright MCP server. Here is an example configuration in `mcp.json`: - -```json -{ - "servers": { - "playwright": { - "command": "npx", - "args": [ - "@playwright/mcp@latest" - ] - } - } -} -``` - -### 2. Create Exploration Prompt - -The AI uses a specialized prompt for autonomous exploration: -- Instructs the agent to explore the website systematically -- Defines the scope and depth of exploration -- Specifies the number of tests to generate -- Sets parameters for test complexity +## Create a Test Generation Prompt -Create a reusable prompt file (e.g., `generate-test.md`) in a prompts folder inside the `.github` directory and add the following content: +Start with creating a reusable prompt file in your `.github` folder named `generate_tests.prompt.md`. By doing this you can then reuse the same prompt for different websites and scenarios. -```md +```markdown --- tools: ['playwright'] mode: 'agent' --- -- You are a playwright test generator. -- You are given a scenario and you need to generate a playwright test for it. -- DO NOT generate test code based on the scenario alone. -- DO run steps one by one using the tools provided by the Playwright MCP. -- When asked to explore a website: - 1. Navigate to the specified URL - 2. Explore 1 key functionality of the site and when finished close the browser. - 3. Implement a Playwright TypeScript test that uses @playwright/test based on message history using Playwright's best practices including role based locators, auto retrying assertions and with no added timeouts unless necessary as Playwright has built in retries and autowaiting if the correct locators and assertions are used. -- Save generated test file in the tests directory -- Execute the test file and iterate until the test passes -- Include appropriate assertions to verify the expected behavior -- Structure tests properly with descriptive test titles and comments -``` -### 3. Agent Mode Exploration Process +You are a playwright test generator. You are given a scenario and you need to generate a playwright test for it. DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided by the Playwright MCP. + +When asked to explore a website, navigate to the specified URL and explore one key functionality of the site. When finished, close the browser and implement a Playwright TypeScript test that uses @playwright/test based on message history using Playwright's best practices including role based locators, auto retrying assertions and with no added timeouts unless necessary as Playwright has built in retries and autowaiting if the correct locators and assertions are used. -To activate agent mode with the exploration prompt: +Save the generated test file in the tests directory and execute the test file, iterating until the test passes. Include appropriate assertions to verify the expected behavior and structure tests properly with descriptive test titles and comments. +``` -1. **Open your AI assistant chat interface** -2. **Enable Agent Mode** in the settings or mode selector -3. **Add the prompt file** (`generate-test.md`) to the conversation context -4. **Execute the exploration command**: +## Exploring a Website with AI +Once you have the [Playwright MCP installed](./index.mdx#getting-started), you can start exploring websites and generating tests. In VS Code Agent Mode, choose a model that supports MCPs and with your prompt added to context, simply type: -```bash +``` Explore https://debs-obrien.github.io/playwright-movies-app ``` -The AI will: -1. **Initial Navigation** - AI visits the target website -2. **Feature Discovery** - Systematically explores available functionalities -3. **User Interaction Simulation** - Performs actions like searching, clicking, navigation -4. **Data Collection** - Gathers information about application behavior -5. **Edge Case Investigation** - Tests various input scenarios +The agent will then begin its autonomous exploration of your application. -### 4. Test Generation +## What Happens During Exploration? -After exploration, the agent analyzes its findings and creates a comprehensive summary of discovered functionalities. From this analysis, it intelligently selects the most suitable functionality as the focus for test generation. +### Initial Navigation +The agent starts by navigating to your specified URL and taking a page snapshot to understand what's available on the page. It can see all interactive elements and begin exploring them systematically. -The agent then generates a complete Playwright test file that includes: -- Proper test structure with descriptive names and comments -- Role-based locators following Playwright best practices -- Auto-retrying assertions for robust test execution -- Comprehensive validation of expected behaviors -- Error handling for edge cases discovered during exploration +### Feature Discovery +The agent explores your application like a real user would, typically following the natural tab order of elements such as search functionality, navigation elements, theme toggles, login forms, and other interactive components. -```javascript +### Bug Detection +One of the most interesting aspects of using AI for exploration is its ability to discover edge cases you might have missed. + +The agent doesn't just test one feature but explores multiple aspects of your application including homepage functionality, search features, movie details pages, theme toggling, and navigation patterns. + +## Test Generation Process + +After exploration, the agent summarizes its findings and selects key functionality to focus on for test generation. Here's what the generated test might look like: + +```typescript import { test, expect } from '@playwright/test'; test.describe('Movie search', () => { test('Search for a movie by title', async ({ page }) => { // Navigate to the movies app await page.goto('https://debs-obrien.github.io/playwright-movies-app'); - + // Click on the search button to activate the search input await page.getByRole('search').click(); - + // Type 'Star Wars' into the search input and press Enter const searchTerm = 'Star Wars'; await page.getByRole('textbox', { name: 'Search Input' }).fill(searchTerm); await page.getByRole('textbox', { name: 'Search Input' }).press('Enter'); - + // Verify we're on the search results page with correct title await expect(page).toHaveTitle(`${searchTerm} - Search Results`); - + // Verify the search results heading contains the search term await expect(page.getByRole('heading', { level: 1 })).toHaveText(searchTerm); await expect(page.getByRole('heading', { name: 'search results', level: 2 })).toBeVisible(); - + // Verify that search results are displayed await expect(page.getByRole('list', { name: 'movies' })).toBeVisible(); - + // Click on a movie from search results const firstMovie = page.getByRole('list', { name: 'movies' }).getByRole('link').first(); const movieTitleElement = firstMovie.getByRole('heading', { level: 2 }); const movieTitle = await movieTitleElement.textContent() || ''; await firstMovie.click(); - + // Verify that the movie details page is loaded with the correct title await expect(page.getByRole('heading', { level: 1 })).toHaveText(movieTitle); - + // Verify movie details sections are present await expect(page.getByText('The Synopsis')).toBeVisible(); await expect(page.getByText('The Cast')).toBeVisible(); - + // Verify recommended movies section is present await expect(page.getByRole('heading', { name: 'Recommended Movies' })).toBeVisible(); - + // Go back to search results await page.getByRole('button', { name: 'Back' }).click(); - + // Verify we're back on the search results page await expect(page.getByRole('heading', { level: 1 })).toHaveText(searchTerm); }); }); ``` +The generated tests use Playwright's role-based locators (`getByRole`, `getByText`, `getByLabel`), which are more resilient and accessible than traditional CSS selectors. The tests use web-first assertions with built-in retries, making them more reliable without needing custom timeouts. The tests include multiple assertion points to verify navigation behavior, page titles and content, element visibility, and complete user interaction flows. -## Running the Test -### Test Execution and Validation - -After test generation, the AI automatically executes the test to verify it works correctly. For this example, the generated test passed on the first run. - -You can iterate, refine the prompt, increase test count, or tell the agent to explore different areas. - -## Best Practices - -### Effective Prompting -- **Be Specific**: Define clear exploration boundaries and objectives -- **Set Scope**: Specify how many tests to generate (start with 1-3) -- **Define Focus**: Target specific functionalities or user journeys -- **Include Context**: Provide relevant application information - -### Exploration Strategy -- **Start Simple**: Begin with core functionalities -- **Iterate Gradually**: Expand to more complex scenarios -- **Review Results**: Always examine generated tests and traces -- **Refine Approach**: Adjust prompts based on initial results - -### Test Quality Assurance -- **Validate Logic**: Ensure generated tests make logical sense -- **Check Assertions**: Verify that test assertions are meaningful -- **Review Edge Cases**: Examine discovered edge cases carefully - - -## Additional Resources - -- **Blog Post**: [Detailed setup and implementation guide](https://dev.to/debs_obrien/letting-playwright-mcp-explore-your-site-and-write-your-tests-mf1) -- **MCP Documentation**: Learn more about Model Context Protocol -- **Playwright Test Generation**: Explore other AI-powered testing approaches -- **Agent Mode**: Advanced AI automation techniques +After generating the test, the AI automatically fixes any linting errors and runs the test to ensure it passes. The process is highly iterative. You can refine your prompts for better results, increase the number of tests generated, direct the agent to explore specific areas of your application, and build upon generated tests with additional test cases. diff --git a/ai/playwright-mcp-generating-tests.mdx b/ai/playwright-mcp-generating-tests.mdx index 04fedf0d6ee..28d719411f0 100644 --- a/ai/playwright-mcp-generating-tests.mdx +++ b/ai/playwright-mcp-generating-tests.mdx @@ -7,186 +7,68 @@ description: Learn how to generate end-to-end Playwright tests using Playwright import LiteYouTube from '@site/src/components/LiteYouTube'; -## Overview - -Learn how to generate end-to-end Playwright tests using the Playwright MCP (Model Context Protocol) server with GitHub Copilot, even when you don't have access to the source code. This powerful approach enables black-box testing, AI-driven automation, and rapid test generation using natural language descriptions. +Imagine a scenario where you need to test a website but don't have access to the source code. Traditional testing approaches fall short when you only have a browser and a URL. This is where the powerful combination of Playwright Model Context Protocol (MCP) and GitHub Copilot transforms the testing landscape. -## What Makes MCP Different - -Traditional AI code generation with Copilot works great when you have access to source code, but what happens when you only have a URL and a browser? That's where Playwright MCP shines: - -- **No Source Code Required**: Generate tests for any website without needing the underlying codebase -- **Real Browser Interaction**: MCP gives Copilot actual browser access to interact with pages like a real user -- **Page Snapshots**: Uses the accessibility tree to understand UI elements and their accessible names +## Understanding the Problem -## How It Works +The difference between using Copilot alone and using the Playwright MCP is significant. While Copilot can generate test code based on source code, it cannot interact with live websites to understand their actual behavior. When you only have access to a browser and no source code, traditional AI-assisted testing approaches hit a wall. -The Playwright MCP server acts as a bridge between GitHub Copilot and a real browser, enabling this workflow: +This gap becomes a major barrier for black-box testing scenarios, where testers need to validate functionality without internal knowledge of the application structure. -1. **Copilot opens a browser** using the MCP server -2. **Navigates to the target website** as specified in a prompt -3. **Takes page snapshots** to understand the page structure and available elements -4. **Interacts with the page** based on the test scenario -5. **Generates a Playwright test file** based on the actions taken -6. **Executes and validates** the generated test +## How Playwright MCP Changes the Game -## Setting Up Your Environment +The Playwright MCP serves as a bridge between AI and browser automation. It gives Copilot the ability to access and control a browser, enabling it to interact with web applications just like a real user would. The agent can then capture these interactions and transform them into reusable, automated test scripts. -### Tools Used +This creates a powerful workflow where the agent can navigate websites, interact with UI elements via page snapshots, generate comprehensive test files, and validate functionality without requiring access to the application's source code. -- **Playwright MCP**: [`https://github.com/microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp) -- **GitHub Copilot**: Agent mode with custom prompts -- **AI Model**: Claude 3.5 Sonnet (or similar LLM that supports MCP) +## Setting Up Your Testing Environment -## Creating Effective Prompts +### Creating the Prompt File -### Reusable Prompt Template - -Create a reusable prompt file (e.g., `generate-test.md`) in a prompts folder inside the `.github` directory: +The foundation of effective MCP testing lies in crafting a clear, directive prompt. Create a reusable prompt file in your `.github/prompts` folder called `generate-test.prompt.md`: ```markdown -# Playwright Test Generator Prompt - -- You are a Playwright test generator -- You are given a scenario and you need to generate a Playwright test for it -- DO NOT generate test code based on the scenario alone -- DO run steps one by one using the tools provided by the Playwright MCP -- Only after all steps are completed, emit a Playwright TypeScript test that uses @playwright/test -- Save generated test file in the tests directory -- Execute the test file and iterate until the test passes -``` - -### Example Test Scenarios - -#### Basic Navigation and Search -``` -Generate a Playwright test for the following scenario: -- Navigate to [URL] -- Search for "Garfield" -- Verify the movie is in the search results list -``` - -#### Form Interaction -``` -Generate a Playwright test for the following scenario: -- Navigate to [URL] -- Fill out the contact form with sample data -- Submit the form -- Verify success message appears -``` - -#### Multi-step Workflow -``` -Generate a Playwright test for the following scenario: -- Navigate to [URL] -- Add multiple items to shopping cart -- Proceed to checkout -- Verify cart contents and total -``` +--- +tools: ['playwright'] +mode: 'agent' +--- -## Step-by-Step Walkthrough - -### 1. Start with Your Prompt - -1. Drag and drop your reusable prompt file into Copilot chat -2. Add your specific test scenario - -### 2. Watch the Playwright MCP Server in Action - -Playwright MCP will: -- **Open a browser window** automatically -- **Navigate to your target URL** -- **Analyze the page structure** using accessibility snapshots -- **Adapt to UI challenges** (e.g., finding hidden search fields) -- **Perform the required actions** step by step - -### 3. Intelligent Problem Solving - -When the AI encounters issues (like a hidden search input), it will: -- Take a page snapshot to understand the current state -- Identify the correct element to interact with -- Adjust its approach (e.g., click search icon before typing) -- Continue with the test scenario - -### 4. Test Generation and Validation - -Once all actions are completed: -- A complete Playwright test file is generated -- The test is saved to your tests directory -- The test is executed to ensure it passes -- Any issues are debugged and fixed automatically - -## Example Generated Test - -Here's what a typical generated test might look like: - -```typescript -import { test, expect } from '@playwright/test'; - -test('search for Garfield movie', async ({ page }) => { - // Navigate to the website - await page.goto('https://example-movie-site.com'); - - // Click search icon to reveal search input - await page.getByRole('button', { name: 'Search' }).click(); - - // Type search term - await page.getByPlaceholder('Search movies...').fill('Garfield'); - - // Submit search - await page.getByRole('button', { name: 'Search' }).click(); - - // Verify Garfield appears in results - await expect(page.getByText('Garfield')).toBeVisible(); -}); +You are a playwright test generator. You are given a scenario and you need to generate a playwright test for it. DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided by the Playwright MCP. Only after all steps are completed, emit a Playwright TypeScript test that uses @playwright/test. Save generated test file in the tests directory. Execute the test file and iterate until the test passes. ``` -## Best Practices +### Configuring the MCP Server -### Prompt Engineering Tips +Ensure you have the [Playwright MCP server installed](./index.mdx#getting-started) and running locally. The server acts as the intermediary that allows Copilot to control browser instances and capture interaction data. -- **Be specific** about the exact steps you want to test -- **Use clear, natural language** descriptions -- **Break complex scenarios** into smaller, manageable steps -- **Specify verification points** clearly +### Initiating the Process -### Handling Dynamic Content +With your prompt file ready and the MCP server running, drag and drop the prompt file into GitHub Copilot to provide context. Then specify your testing scenario in natural language. For example: -- The MCP can adapt to dynamic UIs and changing page structures -- Page snapshots help identify the current state of elements -- Tests are generated based on actual page interaction, not assumptions +``` +Generate a Playwright test for the following scenario: Navigate to [URL], search for Garfield, and verify the movie is in the list. +``` -### Iteration and Refinement +### AI-Driven Browser Automation -- Generated tests are automatically executed and debugged -- Failed tests trigger automatic iteration until they pass -- You can refine prompts based on generated test quality +When you initiate the process using agent mode with Claude 3.5 Sonnet, the agent begins by opening a browser window through the Playwright MCP server. This marks the beginning of autonomous test generation. -## Limitations and Considerations +The agent navigates to your specified URL and begins exploring the interface. When it encounters challenges, such as needing to activate a search field before typing, it automatically takes page snapshots to understand the current state of the application. -### Context Window Management -- For longer test flows, break them into smaller scenarios -- The LLM may lose context with very complex multi-step workflows -- Consider generating multiple focused tests instead of one large test +### Intelligent Problem Solving -## Next Steps +The page snapshots provide the agent with all accessible elements and their names, enabling it to make informed decisions about required interactions. When the agent discovers it needs to click a search icon before entering text, it adapts its approach automatically. -After successfully generating tests with Playwright MCP: +This intelligent problem-solving capability means the agent can handle dynamic interfaces and discover the correct interaction patterns needed to complete the specified scenario. -1. **Review and refactor** generated code to match your project standards -2. **Integrate with your CI/CD pipeline** for automated execution -3. **Create reusable prompt templates** for common testing scenarios +### Test Generation and Validation -This approach revolutionizes how we think about test automation, making it accessible even when source code isn't available and dramatically speeding up the test creation process. +Once the agent has completed the scenario, it automatically generates a comprehensive Playwright test file. This file captures all the necessary steps, navigation, element interactions, search actions, and verification, reflecting the manual process the agent performed. -## Related Resources +Next, the agent executes the generated test to confirm it passes, providing immediate feedback and validation. This seamless workflow from scenario exploration to automated test creation and execution ensures your tests are both accurate and reliable. -- [Playwright MCP GitHub Repository](https://github.com/microsoft/playwright-mcp) -- [Example Prompts Repository](https://github.com/debs-obrien/generate-test-with-copilot) -- [Debugging with AI](debugging-with-ai.mdx) -- [Maintaining Tests](playwright-mcp-maintaining-tests) +To maximize the effectiveness of MCP generated tests, focus on crafting clear and detailed prompts. Specify each step of the user journey you want to automate. The more precise your instructions, the more closely the generated tests will match your requirements. Use these tests as a foundation for building out more robust test suites, and experiment with different AI models, to determine which produces the best results for your needs.