Agents section

agents/browser-and-emulation.mdx

@@ -0,0 +1,286 @@
+---
+id: browser-and-emulation
+title: Browser Profiles and Emulation
+description: Options for selecting browsers, device emulation, viewport sizes and user agents as well as session and state.
+---
+
+## Emulation
+
+You can control which browser Playwright uses and how it simulates devices and environments.
+Below you'll find concise config examples you can paste into your configuration, along with guidance on when to use each option and a few troubleshooting tips.
+
+### 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
+
+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
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--device",
+        "iPhone 13"
+      ]
+    }
+  }
+}
+```
+
+#### Example Prompt device emulation
+
+```bash
+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
+
+Playwright's default viewport is 1280x720.
+You can set a custom viewport size should you need to:
+
+```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
+```
+
+Note that if you're using a persistent profile (the default), the viewport size will be saved and reused across sessions.
+If you want to return to the default viewport, you need to reset it explicitly.
+
+### Custom User Agent
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--user-agent",
+        "MyCustomUserAgent/1.0"
+      ]
+    }
+  }
+}
+```
+
+### Ignore HTTPS Errors
+
+Only use this in development.
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--ignore-https-errors"
+      ]
+    }
+  }
+}
+```
+
+## Browser Profiles and State
+
+By default, Playwright MCP uses persistent profiles.
+This means that user data, login states and cookies are preserved across sessions.
+For some usecases, this is the desired behavior as it allows the agent to stay logged in to websites and maintain session data.
+
+In other usecases, this is not ideal because you want a clean slate every time the agent starts.
+There's a few ways to control this behavior.
+
+### 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"
+      ]
+    }
+  }
+}
+```
+
+### Providing Storage State
+
+To pre-populate a clean session with local storage and Cookies, you can use the `--storage-state` flag to load the state from a file. See docs on [`BrowserContext.storageState()`](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state) for details on the file format.
+
+```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/..."
+      ]
+    }
+  }
+}
+```
+
+## Using a Configuration File
+
+Big configurations can be hard to manage inline, so we allow you to manage them in a separate file using the `--config` flag.
+
+```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 [README](https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#configuration-file) for details on the configuration file format and options.
+
+

agents/debugging-with-ai.mdx

@@ -0,0 +1,43 @@
+---
+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.
+Agents can help you identify and fix test failures.
+This guide will show you how to leverage 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.
+
+<LiteYouTube
+  id="Ec_3h5Q8RHY"
+  title="Debug Playwright Tests with AI – Fix Failures Instantly"
+/>
+
+## 1. Copy Prompt (Faster Test Debugging)
+
+<ProgressiveImage image={require('../images/getting-started/html-report-open.png')} alt="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.
+
+## 2. Fix with AI In VS Code
+<ProgressiveImage image={require('../images/getting-started/fix-with-ai.png')} alt="Fix with AI in VS Code" />
+
+When a test fails while in VS Code (with the Playwright VS Code extension), a sparkly button appears in the Test Explorer and the editor gutter.
+Click it to engage Copilot's "Fix with AI" feature.
+
+Copilot has access to wealth of context on the error (page snapshot, git diff, source code, error messages) and tries to provide contextual, accurate fix suggestions.
+This enables one-click problem resolution.
+