Docs-improvements

ai/browser-and-emulation.mdx

@@ -0,0 +1,260 @@
+---
+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.
+---
+# 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.
+
+## 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 (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
+{
+  "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"
+      ]
+    }
+  }
+}
+```
+
+## Ignore HTTPS Errors
+
+Ignore HTTPS errors (development only):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--ignore-https-errors"
+      ]
+    }
+  }
+}
+```
+
+## 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
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--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/..."
+      ]
+    }
+  }
+}
+```

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.
+
+<LiteYouTube
+  id="Ec_3h5Q8RHY"
+  title="Debug Playwright Tests with AI – Fix Failures Instantly"
+/>
+
+## 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
+<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), 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
+