chore: mark v0.0.26 (#441 )

chore: fix operation over cdp (#440 )
Ref https://github.com/microsoft/playwright-mcp/issues/439
2025-05-17 08:20:37 -07:00 · 2025-05-17 08:20:22 -07:00 · 2025-05-14 20:15:09 -07:00 · 2025-05-14 18:08:44 -07:00 · 2025-05-14 16:01:08 -07:00 · 2025-05-13 16:24:04 -07:00
50 changed files with 1818 additions and 918 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,32 +30,56 @@ jobs:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
-
    steps:
    - uses: actions/checkout@v4
-
    - name: Use Node.js 18
      uses: actions/setup-node@v4
      with:
        # https://github.com/microsoft/playwright-mcp/issues/344
        node-version: '18.19'
        cache: 'npm'
-
    - name: Install dependencies
      run: npm ci
-
    - name: Playwright install
      run: npx playwright install --with-deps
-
    - name: Install MS Edge
-      if: ${{ matrix.os == 'macos-latest' }} # MS Edge is not preinstalled on macOS runners.
+      # MS Edge is not preinstalled on macOS runners.
+      if: ${{ matrix.os == 'macos-latest' }}
      run: npx playwright install msedge
-
    - name: Build
      run: npm run build
-
-    - name: Install Playwright browsers
-      run: npx playwright install --with-deps
-
    - name: Run tests
-      run: npm test -- --forbid-only
+      run: npm test
+
+  test_docker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js 18
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+        cache: 'npm'
+    - name: Install dependencies
+      run: npm ci
+    - name: Playwright install
+      run: npx playwright install --with-deps chromium
+    - name: Build
+      run: npm run build
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    - name: Build and push
+      uses: docker/build-push-action@v6
+      with:
+        tags: playwright-mcp-dev:latest
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+        load: true
+    - name: Run tests
+      shell: bash
+      run: |
+        # Used for the Docker tests to share the test-results folder with the container.
+        umask 0000
+        npm run test -- --project=chromium-docker
+      env:
+        MCP_IN_DOCKER: 1
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -51,5 +51,5 @@ jobs:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
-            playwright.azurecr.io/public/playwright/mcp:${{ github.ref_name }}
+            playwright.azurecr.io/public/playwright/mcp:${{ github.event.release.tag_name }}
            playwright.azurecr.io/public/playwright/mcp:latest
--- a/2
+++ b/2
@@ -66,4 +66,4 @@ COPY --chown=${USERNAME}:${USERNAME} cli.js package.json ./
 COPY --from=builder --chown=${USERNAME}:${USERNAME} /app/lib /app/lib

 # Run in headless and only with chromium (other browsers need more dependencies not included in this image)
-ENTRYPOINT ["node", "cli.js", "--headless", "--browser", "chromium"]
+ENTRYPOINT ["node", "cli.js", "--headless", "--browser", "chromium", "--no-sandbox"]
--- a/README.md
+++ b/README.md
@@ -4,25 +4,22 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit

 ### Key Features

- **Fast and lightweight**: Uses Playwright's accessibility tree, not pixel-based input.
- **LLM-friendly**: No vision models needed, operates purely on structured data.
- **Deterministic tool application**: Avoids ambiguity common with screenshot-based approaches.
+- **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input.
+- **LLM-friendly**. No vision models needed, operates purely on structured data.
+- **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches.

-### Use Cases
-
- Web navigation and form-filling
- Data extraction from structured content
- Automated testing driven by LLMs
- General-purpose browser interaction for agents
+### Requirements
+- Node.js 18 or newer
+- VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client

 <!--
 // Generate using:
 node utils/generate-links.js
 -->

-[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+### Getting started

-### Example config
+First, install the Playwright MCP server with your client. A typical configuration looks like this:

 ```js
 {
@@ -37,20 +34,12 @@ node utils/generate-links.js
 }
 ```

-### Table of Contents
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)

- [Installation in VS Code](#installation-in-vs-code)
- [Command line](#command-line)
- [User profile](#user-profile)
- [Configuration file](#configuration-file)
- [Running on Linux](#running-on-linux)
- [Docker](#docker)
- [Programmatic usage](#programmatic-usage)
- [Tool modes](#tool-modes)

-### Installation in VS Code
+<details><summary><b>Install in VS Code</b></summary>

-You can install the Playwright MCP server using the VS Code CLI:
+You can also install the Playwright MCP server using the VS Code CLI:

 ```bash
 # For VS Code
@@ -58,45 +47,173 @@ code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@la
 ```

 After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
+</details>

-### Command line
+<details>
+<summary><b>Install in Cursor</b></summary>

-The Playwright MCP server supports the following command-line options:
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @playwright/mcp`. You can also verify config or add command like arguments via clicking `Edit`.

- `--browser <browser>`: Browser or chrome channel to use. Possible values:
-  - `chrome`, `firefox`, `webkit`, `msedge`
-  - Chrome channels: `chrome-beta`, `chrome-canary`, `chrome-dev`
-  - Edge channels: `msedge-beta`, `msedge-canary`, `msedge-dev`
-  - Default: `chrome`
- `--caps <caps>`: Comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.
- `--cdp-endpoint <endpoint>`: CDP endpoint to connect to
- `--executable-path <path>`: Path to the browser executable
- `--headless`: Run browser in headless mode (headed by default)
- `--device`: Emulate mobile device
- `--user-data-dir <path>`: Path to the user data directory
- `--port <port>`: Port to listen on for SSE transport
- `--host <host>`: Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
- `--allowed-origins <origins>`: Semicolon-separated list of origins to allow the browser to request. Default is to allow all. Origins matching both `--allowed-origins` and `--blocked-origins` will be blocked.
- `--blocked-origins <origins>`: Semicolon-separated list of origins to block the browser to request. Origins matching both `--allowed-origins` and `--blocked-origins` will be blocked.
- `--vision`: Run server that uses screenshots (Aria snapshots are used by default)
- `--output-dir`: Directory for output files
- `--config <path>`: Path to the configuration file
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Install in Windsurf</b></summary>
+
+Follow Windsuff MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</details>
+
+### Configuration
+
+Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:
+
+<!--- Options generated by update-readme.js -->
+
+```
+> npx @playwright/mcp@latest --help
+  --allowed-origins <origins>  semicolon-separated list of origins to allow the
+                               browser to request. Default is to allow all.
+  --blocked-origins <origins>  semicolon-separated list of origins to block the
+                               browser from requesting. Blocklist is evaluated
+                               before allowlist. If used without the allowlist,
+                               requests not matching the blocklist are still
+                               allowed.
+  --block-service-workers      block service workers
+  --browser <browser>          browser or chrome channel to use, possible
+                               values: chrome, firefox, webkit, msedge.
+  --caps <caps>                comma-separated list of capabilities to enable,
+                               possible values: tabs, pdf, history, wait, files,
+                               install. Default is all.
+  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
+  --config <path>              path to the configuration file.
+  --device <device>            device to emulate, for example: "iPhone 15"
+  --executable-path <path>     path to the browser executable.
+  --headless                   run browser in headless mode, headed by default
+  --host <host>                host to bind server to. Default is localhost. Use
+                               0.0.0.0 to bind to all interfaces.
+  --ignore-https-errors        ignore https errors
+  --isolated                   keep the browser profile in memory, do not save
+                               it to disk.
+  --no-image-responses         do not send image responses to the client.
+  --no-sandbox                 disable the sandbox for all process types that
+                               are normally sandboxed.
+  --output-dir <path>          path to the directory for output files.
+  --port <port>                port to listen on for SSE transport.
+  --proxy-bypass <bypass>      comma-separated domains to bypass proxy, for
+                               example ".com,chromium.org,.domain.com"
+  --proxy-server <proxy>       specify proxy server, for example
+                               "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-trace                 Whether to save the Playwright Trace of the
+                               session into the output directory.
+  --storage-state <path>       path to the storage state file for isolated
+                               sessions.
+  --user-agent <ua string>     specify user agent string
+  --user-data-dir <path>       path to the user data directory. If not
+                               specified, a temporary directory will be created.
+  --viewport-size <size>       specify browser viewport size in pixels, for
+                               example "1280, 720"
+  --vision                     Run server that uses screenshots (Aria snapshots
+                               are used by default)
+```
+
+<!--- End of options generated section -->

 ### User profile

-Playwright MCP will launch the browser with the new profile, located at
+You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.

-```
- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux
+**Persistent profile**
+
+All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.
+Persistent profile is located at the following locations and you can override it with the `--user-data-dir` argument.
+
+```bash
+# Windows
+%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
+
+# macOS
+- ~/Library/Caches/ms-playwright/mcp-{channel}-profile
+
+# Linux
+- ~/.cache/ms-playwright/mcp-{channel}-profile
 ```

-All the logged in information will be stored in that profile, you can delete it between sessions if you'd like to clear the offline state.
+**Isolated**
+
+In the isolated mode, each session is started in the isolated profile. Every time you ask MCP to close the browser,
+the session is closed and all the storage state for this session is lost. You can provide initial storage state
+to the browser via the config's `contextOptions` or via the `--storage-state` argument. Learn more about the storage
+state [here](https://playwright.dev/docs/auth).
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--isolated",
+        "--storage-state={path/to/storage.json}
+      ]
+    }
+  }
+}
+```

 ### Configuration file

-The Playwright MCP server can be configured using a JSON configuration file. Here's the complete configuration format:
+The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
+using the `--config` command line option:
+
+```bash
+npx @playwright/mcp@latest --config path/to/config.json
+```
+
+<details>
+<summary>Configuration file schema</summary>

 ```typescript
 {
@@ -105,6 +222,9 @@ The Playwright MCP server can be configured using a JSON configuration file. Her
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

+    // Keep the browser profile in memory, do not save it to disk.
+    isolated?: boolean;
+
    // Path to user data directory for browser profile persistence
    userDataDir?: string;

@@ -170,14 +290,9 @@ The Playwright MCP server can be configured using a JSON configuration file. Her
  noImageResponses?: boolean;
 }
 ```
+</details>

-You can specify the configuration file using the `--config` command line option:
-
-```bash
-npx @playwright/mcp@latest --config path/to/config.json
-```
-
-### Running on Linux
+### Standalone MCP server

 When running headed browser on system w/o display or from worker processes of the IDEs,
 run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.
@@ -198,7 +313,8 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 }
 ```

-### Docker
+<details>
+<summary><b>Docker</b></summary>

 **NOTE:** The Docker implementation only supports headless chromium at the moment.

@@ -207,7 +323,7 @@ And then in MCP client config, set the `url` to the SSE endpoint:
  "mcpServers": {
    "playwright": {
      "command": "docker",
-      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
+      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
 }
@@ -216,30 +332,33 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 You can build the Docker image yourself.

 ```
-docker build -t mcp/playwright .
+docker build -t mcr.microsoft.com/playwright/mcp .
 ```
+</details>

-### Programmatic usage
+<details>
+<summary><b>Programmatic usage</b></summary>

 ```js
 import http from 'http';

-import { createServer } from '@playwright/mcp';
+import { createConnection } from '@playwright/mcp';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

 http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
-  const connection = await createConnection({ headless: true });
+  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
 });
 ```
+</details>

-### Tool modes
+### Tools

 The tools are available in two modes:

@@ -265,10 +384,10 @@ To use Vision Mode, add the `--vision` flag when starting the server:
 Vision Mode works best with the computer use models that are able to interact with elements using
 X Y coordinate space, based on the provided screenshot.

+<!--- Tools generated by update-readme.js -->

-<!--- Generated by update-readme.js -->
-
-### Snapshot-based Interactions
+<details>
+<summary><b>Interactions</b></summary>

 <!-- NOTE: This has been generated via update-readme.js -->

@@ -336,16 +455,206 @@ X Y coordinate space, based on the provided screenshot.

 <!-- NOTE: This has been generated via update-readme.js -->

+- **browser_press_key**
+  - Title: Press a key
+  - Description: Press a key on the keyboard
+  - Parameters:
+    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
+  - Parameters:
+    - `time` (number, optional): The time to wait in seconds
+    - `text` (string, optional): The text to wait for
+    - `textGone` (string, optional): The text to wait for to disappear
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_file_upload**
+  - Title: Upload files
+  - Description: Upload one or multiple files
+  - Parameters:
+    - `paths` (array): The absolute paths to the files to upload. Can be a single file or multiple files.
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_handle_dialog**
+  - Title: Handle a dialog
+  - Description: Handle a dialog
+  - Parameters:
+    - `accept` (boolean): Whether to accept the dialog.
+    - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Navigation</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate**
+  - Title: Navigate to a URL
+  - Description: Navigate to a URL
+  - Parameters:
+    - `url` (string): The URL to navigate to
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate_back**
+  - Title: Go back
+  - Description: Go back to the previous page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate_forward**
+  - Title: Go forward
+  - Description: Go forward to the next page
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Resources</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
 - **browser_take_screenshot**
  - Title: Take a screenshot
  - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
  - Parameters:
    - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
+    - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.
    - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
    - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
  - Read-only: **true**

-### Vision-based Interactions
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_pdf_save**
+  - Title: Save as PDF
+  - Description: Save page as PDF
+  - Parameters:
+    - `filename` (string, optional): File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_network_requests**
+  - Title: List network requests
+  - Description: Returns all network requests since loading the page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_console_messages**
+  - Title: Get console messages
+  - Description: Returns all console messages
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Utilities</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_install**
+  - Title: Install the browser specified in the config
+  - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_close**
+  - Title: Close browser
+  - Description: Close the page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_resize**
+  - Title: Resize browser window
+  - Description: Resize the browser window
+  - Parameters:
+    - `width` (number): Width of the browser window
+    - `height` (number): Height of the browser window
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Tabs</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_list**
+  - Title: List tabs
+  - Description: List browser tabs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_new**
+  - Title: Open a new tab
+  - Description: Open a new tab
+  - Parameters:
+    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_select**
+  - Title: Select a tab
+  - Description: Select a tab by index
+  - Parameters:
+    - `index` (number): The index of the tab to select
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_close**
+  - Title: Close a tab
+  - Description: Close a tab
+  - Parameters:
+    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Testing</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_generate_playwright_test**
+  - Title: Generate a Playwright test
+  - Description: Generate a Playwright test for given scenario
+  - Parameters:
+    - `name` (string): The name of the test
+    - `description` (string): The description of the test
+    - `steps` (array): The steps of the test
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Vision mode</b></summary>

 <!-- NOTE: This has been generated via update-readme.js -->

@@ -400,72 +709,6 @@ X Y coordinate space, based on the provided screenshot.
    - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
  - Read-only: **false**

-### Tab Management
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_tab_list**
-  - Title: List tabs
-  - Description: List browser tabs
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_tab_new**
-  - Title: Open a new tab
-  - Description: Open a new tab
-  - Parameters:
-    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_tab_select**
-  - Title: Select a tab
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_tab_close**
-  - Title: Close a tab
-  - Description: Close a tab
-  - Parameters:
-    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
-  - Read-only: **false**
-
-### Navigation
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_navigate**
-  - Title: Navigate to a URL
-  - Description: Navigate to a URL
-  - Parameters:
-    - `url` (string): The URL to navigate to
-  - Read-only: **false**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_navigate_back**
-  - Title: Go back
-  - Description: Go back to the previous page
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_navigate_forward**
-  - Title: Go forward
-  - Description: Go forward to the next page
-  - Parameters: None
-  - Read-only: **true**
-
-### Keyboard
-
 <!-- NOTE: This has been generated via update-readme.js -->

 - **browser_press_key**
@@ -475,18 +718,17 @@ X Y coordinate space, based on the provided screenshot.
    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
  - Read-only: **false**

-### Console
-
 <!-- NOTE: This has been generated via update-readme.js -->

- **browser_console_messages**
-  - Title: Get console messages
-  - Description: Returns all console messages
-  - Parameters: None
+- **browser_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
+  - Parameters:
+    - `time` (number, optional): The time to wait in seconds
+    - `text` (string, optional): The text to wait for
+    - `textGone` (string, optional): The text to wait for to disappear
  - Read-only: **true**

-### Files and Media
-
 <!-- NOTE: This has been generated via update-readme.js -->

 - **browser_file_upload**
@@ -498,51 +740,6 @@ X Y coordinate space, based on the provided screenshot.

 <!-- NOTE: This has been generated via update-readme.js -->

- **browser_pdf_save**
-  - Title: Save as PDF
-  - Description: Save page as PDF
-  - Parameters: None
-  - Read-only: **true**
-
-### Utilities
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_close**
-  - Title: Close browser
-  - Description: Close the page
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_wait**
-  - Title: Wait
-  - Description: Wait for a specified time in seconds
-  - Parameters:
-    - `time` (number): The time to wait in seconds
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_resize**
-  - Title: Resize browser window
-  - Description: Resize the browser window
-  - Parameters:
-    - `width` (number): Width of the browser window
-    - `height` (number): Height of the browser window
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_install**
-  - Title: Install the browser specified in the config
-  - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
-  - Parameters: None
-  - Read-only: **false**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
 - **browser_handle_dialog**
  - Title: Handle a dialog
  - Description: Handle a dialog
@@ -551,25 +748,7 @@ X Y coordinate space, based on the provided screenshot.
    - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.
  - Read-only: **false**

-<!-- NOTE: This has been generated via update-readme.js -->
+</details>

- **browser_network_requests**
-  - Title: List network requests
-  - Description: Returns all network requests since loading the page
-  - Parameters: None
-  - Read-only: **true**

-### Testing
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
- **browser_generate_playwright_test**
-  - Title: Generate a Playwright test
-  - Description: Generate a Playwright test for given scenario
-  - Parameters:
-    - `name` (string): The name of the test
-    - `description` (string): The description of the test
-    - `steps` (array): The steps of the test
-  - Read-only: **true**
-
-<!--- End of generated section -->
+<!--- End of tools generated section -->
--- a/config.d.ts
+++ b/config.d.ts
@@ -28,6 +28,11 @@ export type Config = {
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

+    /**
+     * Keep the browser profile in memory, do not save it to disk.
+     */
+    isolated?: boolean;
+
    /**
     * Path to a user data directory for browser profile persistence.
     * Temporary directory is created by default.
@@ -40,7 +45,7 @@ export type Config = {
     *
     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
     */
-    launchOptions?: playwright.BrowserLaunchOptions;
+    launchOptions?: playwright.LaunchOptions;

    /**
     * Context options for the browser context.
@@ -89,6 +94,11 @@ export type Config = {
   */
  vision?: boolean;

+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
  /**
   * The directory to save output files.
   */
--- a/index.js
+++ b/index.js
@@ -16,4 +16,4 @@
 */

 import { createConnection } from './lib/index';
-export default { createConnection };
+export { createConnection };
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,18 +1,17 @@
 {
  "name": "@playwright/mcp",
-  "version": "0.0.21",
+  "version": "0.0.26",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@playwright/mcp",
-      "version": "0.0.21",
+      "version": "0.0.26",
      "license": "Apache-2.0",
      "dependencies": {
        "@modelcontextprotocol/sdk": "^1.11.0",
        "commander": "^13.1.0",
-        "playwright": "1.53.0-alpha-1746218818000",
-        "yaml": "^2.7.1",
+        "playwright": "1.53.0-alpha-1746832516000",
        "zod-to-json-schema": "^3.24.4"
      },
      "bin": {
@@ -21,7 +20,7 @@
      "devDependencies": {
        "@eslint/eslintrc": "^3.2.0",
        "@eslint/js": "^9.19.0",
-        "@playwright/test": "1.53.0-alpha-1746218818000",
+        "@playwright/test": "1.53.0-alpha-1746832516000",
        "@stylistic/eslint-plugin": "^3.0.1",
        "@types/node": "^22.13.10",
        "@typescript-eslint/eslint-plugin": "^8.26.1",
@@ -287,13 +286,13 @@
      }
    },
    "node_modules/@playwright/test": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-J05FD0oOCVbjbp4IjQi5tOPKywchi5EENS9jRjgkA5N9jd/+BaZ3jT8HlLMIgALdk/eLsprQa7vh9h45Q1FOPA==",
+      "version": "1.53.0-alpha-1746832516000",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.53.0-alpha-1746832516000.tgz",
+      "integrity": "sha512-Sec+6uzpA4MfwmQqJFBFVazffynqVwLO5swDxG7WoqgpUdn9gQX4K4tDG64SV6f4nOpwdM5LKTasPSXu02nn/Q==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
-        "playwright": "1.53.0-alpha-1746218818000"
+        "playwright": "1.53.0-alpha-1746832516000"
      },
      "bin": {
        "playwright": "cli.js"
@@ -3299,12 +3298,12 @@
      }
    },
    "node_modules/playwright": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-mVIjtdqIawIqWVyvCaLmV6XTALCT4oWWrbMjoHyyWRln3jQjnm3RUO9LkaINz+Yh88O3FkuY6RfjGXPXeFeJ4Q==",
+      "version": "1.53.0-alpha-1746832516000",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.53.0-alpha-1746832516000.tgz",
+      "integrity": "sha512-kcC1B2XJr4VaDAcVzi61SbYGkodq1QIqQXuPieXsNgZZ7cEKWzO2sI42yp2yie6wlCx0oLkSS2Q6jWSRVRLeaw==",
      "license": "Apache-2.0",
      "dependencies": {
-        "playwright-core": "1.53.0-alpha-1746218818000"
+        "playwright-core": "1.53.0-alpha-1746832516000"
      },
      "bin": {
        "playwright": "cli.js"
@@ -3317,9 +3316,9 @@
      }
    },
    "node_modules/playwright-core": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-iaIZmhO/psGssWpxIprJkFrn2h4xFjgL0jZsKGtReAMZ/XhlqMUJxtSitwWM4BV+wxJIptsZD0s5Ml2KU62Z3w==",
+      "version": "1.53.0-alpha-1746832516000",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.53.0-alpha-1746832516000.tgz",
+      "integrity": "sha512-4O98y4zV0rOP6CepMLC/VGuzqGaR1sS9AVh+i0CghWMQHM/8bxPJI8W38QndO0JU0V5nBD6j7DQeNt1mJ+CZ+g==",
      "license": "Apache-2.0",
      "bin": {
        "playwright-core": "cli.js"
@@ -4350,18 +4349,6 @@
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    },
-    "node_modules/yaml": {
-      "version": "2.7.1",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.7.1.tgz",
-      "integrity": "sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==",
-      "license": "ISC",
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14"
-      }
-    },
    "node_modules/yocto-queue": {
      "version": "0.1.0",
      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@playwright/mcp",
-  "version": "0.0.21",
+  "version": "0.0.26",
  "description": "Playwright Tools for MCP",
  "type": "module",
  "repository": {
@@ -37,14 +37,13 @@
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.11.0",
    "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-1746218818000",
-    "yaml": "^2.7.1",
+    "playwright": "1.53.0-alpha-1746832516000",
    "zod-to-json-schema": "^3.24.4"
  },
  "devDependencies": {
    "@eslint/eslintrc": "^3.2.0",
    "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.53.0-alpha-1746218818000",
+    "@playwright/test": "1.53.0-alpha-1746832516000",
    "@stylistic/eslint-plugin": "^3.0.1",
    "@types/node": "^22.13.10",
    "@typescript-eslint/eslint-plugin": "^8.26.1",
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -29,6 +29,7 @@ export default defineConfig<TestOptions>({
    { name: 'chrome' },
    { name: 'msedge', use: { mcpBrowser: 'msedge' } },
    { name: 'chromium', use: { mcpBrowser: 'chromium' } },
+    ...process.env.MCP_IN_DOCKER ? [{ name: 'chromium-docker', use: { mcpBrowser: 'chromium', mcpMode: 'docker' as const } }] : [],
    { name: 'firefox', use: { mcpBrowser: 'firefox' } },
    { name: 'webkit', use: { mcpBrowser: 'webkit' } },
  ],
--- a/src/config.ts
+++ b/src/config.ts
@@ -25,29 +25,40 @@ import type { BrowserContextOptions, LaunchOptions } from 'playwright';
 import { sanitizeForFilePath } from './tools/utils.js';

 export type CLIOptions = {
+  allowedOrigins?: string[];
+  blockedOrigins?: string[];
+  blockServiceWorkers?: boolean;
  browser?: string;
  caps?: string;
  cdpEndpoint?: string;
+  config?: string;
+  device?: string;
  executablePath?: string;
  headless?: boolean;
-  device?: string;
-  userDataDir?: string;
-  port?: number;
  host?: string;
-  vision?: boolean;
-  config?: string;
-  allowedOrigins?: string[];
-  blockedOrigins?: string[];
+  ignoreHttpsErrors?: boolean;
+  isolated?: boolean;
+  imageResponses: boolean;
+  sandbox: boolean;
  outputDir?: string;
-  noImageResponses?: boolean;
+  port?: number;
+  proxyBypass?: string;
+  proxyServer?: string;
+  saveTrace?: boolean;
+  storageState?: string;
+  userAgent?: string;
+  userDataDir?: string;
+  viewportSize?: string;
+  vision?: boolean;
 };

-const defaultConfig: Config = {
+const defaultConfig: FullConfig = {
  browser: {
    browserName: 'chromium',
    launchOptions: {
      channel: 'chrome',
      headless: os.platform() === 'linux' && !process.env.DISPLAY,
+      chromiumSandbox: true,
    },
    contextOptions: {
      viewport: null,
@@ -57,12 +68,33 @@ const defaultConfig: Config = {
    allowedOrigins: undefined,
    blockedOrigins: undefined,
  },
+  outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };

-export async function resolveConfig(cliOptions: CLIOptions): Promise<Config> {
-  const config = await loadConfig(cliOptions.config);
+type BrowserUserConfig = NonNullable<Config['browser']>;
+
+export type FullConfig = Config & {
+  browser: BrowserUserConfig & {
+    browserName: NonNullable<BrowserUserConfig['browserName']>;
+    launchOptions: NonNullable<BrowserUserConfig['launchOptions']>;
+    contextOptions: NonNullable<BrowserUserConfig['contextOptions']>;
+  },
+  network: NonNullable<Config['network']>,
+  outputDir: string;
+};
+
+export async function resolveConfig(config: Config): Promise<FullConfig> {
+  return mergeConfig(defaultConfig, config);
+}
+
+export async function resolveCLIConfig(cliOptions: CLIOptions): Promise<FullConfig> {
+  const configInFile = await loadConfig(cliOptions.config);
  const cliOverrides = await configFromCLIOptions(cliOptions);
-  return mergeConfig(defaultConfig, mergeConfig(config, cliOverrides));
+  const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+  // Derive artifact output directory from config.outputDir
+  if (result.saveTrace)
+    result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+  return result;
 }

 export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Config> {
@@ -92,20 +124,58 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
      channel = 'chrome';
  }

+  // Launch options
  const launchOptions: LaunchOptions = {
    channel,
    executablePath: cliOptions.executablePath,
    headless: cliOptions.headless,
  };

-  if (browserName === 'chromium')
-    (launchOptions as any).webSocketPort = await findFreePort();
+  if (browserName === 'chromium') {
+    (launchOptions as any).cdpPort = await findFreePort();
+    if (!cliOptions.sandbox) {
+      // --no-sandbox was passed, disable the sandbox
+      launchOptions.chromiumSandbox = false;
+    }
+  }

-  const contextOptions: BrowserContextOptions | undefined = cliOptions.device ? devices[cliOptions.device] : undefined;
+  if (cliOptions.proxyServer) {
+    launchOptions.proxy = {
+      server: cliOptions.proxyServer
+    };
+    if (cliOptions.proxyBypass)
+      launchOptions.proxy.bypass = cliOptions.proxyBypass;
+  }

-  return {
+  // Context options
+  const contextOptions: BrowserContextOptions = cliOptions.device ? devices[cliOptions.device] : {};
+  if (cliOptions.storageState)
+    contextOptions.storageState = cliOptions.storageState;
+
+  if (cliOptions.userAgent)
+    contextOptions.userAgent = cliOptions.userAgent;
+
+  if (cliOptions.viewportSize) {
+    try {
+      const [width, height] = cliOptions.viewportSize.split(',').map(n => +n);
+      if (isNaN(width) || isNaN(height))
+        throw new Error('bad values');
+      contextOptions.viewport = { width, height };
+    } catch (e) {
+      throw new Error('Invalid viewport size format: use "width,height", for example --viewport-size="800,600"');
+    }
+  }
+
+  if (cliOptions.ignoreHttpsErrors)
+    contextOptions.ignoreHTTPSErrors = true;
+
+  if (cliOptions.blockServiceWorkers)
+    contextOptions.serviceWorkers = 'block';
+
+  const result: Config = {
    browser: {
      browserName,
+      isolated: cliOptions.isolated,
      userDataDir: cliOptions.userDataDir,
      launchOptions,
      contextOptions,
@@ -121,8 +191,16 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
      allowedOrigins: cliOptions.allowedOrigins,
      blockedOrigins: cliOptions.blockedOrigins,
    },
+    saveTrace: cliOptions.saveTrace,
    outputDir: cliOptions.outputDir,
  };
+
+  if (!cliOptions.imageResponses) {
+    // --no-image-responses was passed, disable image responses
+    result.noImageResponses = true;
+  }
+
+  return result;
 }

 async function findFreePort() {
@@ -147,11 +225,10 @@ async function loadConfig(configFile: string | undefined): Promise<Config> {
  }
 }

-export async function outputFile(config: Config, name: string): Promise<string> {
-  const result = config.outputDir ?? os.tmpdir();
-  await fs.promises.mkdir(result, { recursive: true });
+export async function outputFile(config: FullConfig, name: string): Promise<string> {
+  await fs.promises.mkdir(config.outputDir, { recursive: true });
  const fileName = sanitizeForFilePath(name);
-  return path.join(result, fileName);
+  return path.join(config.outputDir, fileName);
 }

 function pickDefined<T extends object>(obj: T | undefined): Partial<T> {
@@ -160,10 +237,10 @@ function pickDefined<T extends object>(obj: T | undefined): Partial<T> {
  ) as Partial<T>;
 }

-function mergeConfig(base: Config, overrides: Config): Config {
-  const browser: Config['browser'] = {
-    ...pickDefined(base.browser),
-    ...pickDefined(overrides.browser),
+function mergeConfig(base: FullConfig, overrides: Config): FullConfig {
+  const browser: FullConfig['browser'] = {
+    browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
+    isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
    launchOptions: {
      ...pickDefined(base.browser?.launchOptions),
      ...pickDefined(overrides.browser?.launchOptions),
@@ -173,9 +250,12 @@ function mergeConfig(base: Config, overrides: Config): Config {
      ...pickDefined(base.browser?.contextOptions),
      ...pickDefined(overrides.browser?.contextOptions),
    },
+    userDataDir: overrides.browser?.userDataDir ?? base.browser?.userDataDir,
+    cdpEndpoint: overrides.browser?.cdpEndpoint ?? base.browser?.cdpEndpoint,
+    remoteEndpoint: overrides.browser?.remoteEndpoint ?? base.browser?.remoteEndpoint,
  };

-  if (browser.browserName !== 'chromium')
+  if (browser.browserName !== 'chromium' && browser.launchOptions)
    delete browser.launchOptions.channel;

  return {
@@ -185,6 +265,6 @@ function mergeConfig(base: Config, overrides: Config): Config {
    network: {
      ...pickDefined(base.network),
      ...pickDefined(overrides.network),
-    },
-  };
+    }
+  } as FullConfig;
 }
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -19,13 +19,13 @@ import { CallToolRequestSchema, ListToolsRequestSchema, Tool as McpTool } from '
 import { zodToJsonSchema } from 'zod-to-json-schema';

 import { Context, packageJSON } from './context.js';
-import { snapshotTools, screenshotTools } from './tools.js';
+import { snapshotTools, visionTools } from './tools.js';

-import type { Config } from '../config.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { FullConfig } from './config.js';

-export async function createConnection(config: Config): Promise<Connection> {
-  const allTools = config.vision ? screenshotTools : snapshotTools;
+export async function createConnection(config: FullConfig): Promise<Connection> {
+  const allTools = config.vision ? visionTools : snapshotTools;
  const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));

  const context = new Context(tools, config);
--- a/src/context.ts
+++ b/src/context.ts
@@ -21,32 +21,35 @@ import path from 'node:path';

 import * as playwright from 'playwright';

-import { waitForCompletion } from './tools/utils.js';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
 import { Tab } from './tab.js';
+import { outputFile } from './config.js';

 import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
 import type { ModalState, Tool, ToolActionResult } from './tools/tool.js';
-import type { Config } from '../config.js';
-import { outputFile } from './config.js';
+import type { FullConfig } from './config.js';

 type PendingAction = {
  dialogShown: ManualPromise<void>;
 };

+type BrowserContextAndBrowser = {
+  browser?: playwright.Browser;
+  browserContext: playwright.BrowserContext;
+};
+
 export class Context {
  readonly tools: Tool[];
-  readonly config: Config;
-  private _browser: playwright.Browser | undefined;
-  private _browserContext: playwright.BrowserContext | undefined;
-  private _createBrowserContextPromise: Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> | undefined;
+  readonly config: FullConfig;
+  private _browserContextPromise: Promise<BrowserContextAndBrowser> | undefined;
  private _tabs: Tab[] = [];
  private _currentTab: Tab | undefined;
  private _modalStates: (ModalState & { tab: Tab })[] = [];
  private _pendingAction: PendingAction | undefined;
  private _downloads: { download: playwright.Download, finished: boolean, outputFile: string }[] = [];

-  constructor(tools: Tool[], config: Config) {
+  constructor(tools: Tool[], config: FullConfig) {
    this.tools = tools;
    this.config = config;
  }
@@ -85,7 +88,7 @@ export class Context {
  }

  async newTab(): Promise<Tab> {
-    const browserContext = await this._ensureBrowserContext();
+    const { browserContext } = await this._ensureBrowserContext();
    const page = await browserContext.newPage();
    this._currentTab = this._tabs.find(t => t.page === page)!;
    return this._currentTab;
@@ -97,9 +100,9 @@ export class Context {
  }

  async ensureTab(): Promise<Tab> {
-    const context = await this._ensureBrowserContext();
+    const { browserContext } = await this._ensureBrowserContext();
    if (!this._currentTab)
-      await context.newPage();
+      await browserContext.newPage();
    return this._currentTab!;
  }

@@ -109,7 +112,7 @@ export class Context {
    const lines: string[] = ['### Open tabs'];
    for (let i = 0; i < this._tabs.length; i++) {
      const tab = this._tabs[i];
-      const title = await tab.page.title();
+      const title = await tab.title();
      const url = tab.page.url();
      const current = tab === this._currentTab ? ' (current)' : '';
      lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
@@ -125,7 +128,7 @@ export class Context {

  async run(tool: Tool, params: Record<string, unknown> | undefined) {
    // Tab management is done outside of the action() call.
-    const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params));
+    const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params || {}));
    const { code, action, waitForNetwork, captureSnapshot, resultOverride } = toolResult;
    const racingAction = action ? () => this._raceAgainstModalDialogs(action) : undefined;

@@ -146,7 +149,7 @@ export class Context {
    let actionResult: { content?: (ImageContent | TextContent)[] } | undefined;
    try {
      if (waitForNetwork)
-        actionResult = await waitForCompletion(this, tab.page, async () => racingAction?.()) ?? undefined;
+        actionResult = await waitForCompletion(this, tab, async () => racingAction?.()) ?? undefined;
      else
        actionResult = await racingAction?.() ?? undefined;
    } finally {
@@ -190,7 +193,7 @@ ${code.join('\n')}

    result.push(
        `- Page URL: ${tab.page.url()}`,
-        `- Page Title: ${await tab.page.title()}`
+        `- Page Title: ${await tab.title()}`
    );

    if (captureSnapshot && tab.hasSnapshot())
@@ -210,10 +213,14 @@ ${code.join('\n')}
  }

  async waitForTimeout(time: number) {
-    if (this._currentTab && !this._javaScriptBlocked())
-      await this._currentTab.page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-    else
+    if (!this._currentTab || this._javaScriptBlocked()) {
      await new Promise(f => setTimeout(f, time));
+      return;
+    }
+
+    await callOnPageNoTrace(this._currentTab.page, page => {
+      return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+    });
  }

  private async _raceAgainstModalDialogs(action: () => Promise<ToolActionResult>): Promise<ToolActionResult> {
@@ -273,22 +280,24 @@ ${code.join('\n')}

    if (this._currentTab === tab)
      this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
-    if (this._browserContext && !this._tabs.length)
+    if (!this._tabs.length)
      void this.close();
  }

  async close() {
-    if (!this._browserContext)
+    if (!this._browserContextPromise)
      return;
-    const browserContext = this._browserContext;
-    const browser = this._browser;
-    this._createBrowserContextPromise = undefined;
-    this._browserContext = undefined;
-    this._browser = undefined;

-    await browserContext?.close().then(async () => {
-      await browser?.close();
-    }).catch(() => {});
+    const promise = this._browserContextPromise;
+    this._browserContextPromise = undefined;
+
+    await promise.then(async ({ browserContext, browser }) => {
+      if (this.config.saveTrace)
+        await browserContext.tracing.stop();
+      await browserContext.close().then(async () => {
+        await browser?.close();
+      }).catch(() => {});
+    });
  }

  private async _setupRequestInterception(context: playwright.BrowserContext) {
@@ -305,30 +314,34 @@ ${code.join('\n')}
    }
  }

-  private async _ensureBrowserContext() {
-    if (!this._browserContext) {
-      const context = await this._createBrowserContext();
-      this._browser = context.browser;
-      this._browserContext = context.browserContext;
-      await this._setupRequestInterception(this._browserContext);
-      for (const page of this._browserContext.pages())
-        this._onPageCreated(page);
-      this._browserContext.on('page', page => this._onPageCreated(page));
-    }
-    return this._browserContext;
-  }
-
-  private async _createBrowserContext(): Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> {
-    if (!this._createBrowserContextPromise) {
-      this._createBrowserContextPromise = this._innerCreateBrowserContext();
-      void this._createBrowserContextPromise.catch(() => {
-        this._createBrowserContextPromise = undefined;
+  private _ensureBrowserContext() {
+    if (!this._browserContextPromise) {
+      this._browserContextPromise = this._setupBrowserContext();
+      this._browserContextPromise.catch(() => {
+        this._browserContextPromise = undefined;
      });
    }
-    return this._createBrowserContextPromise;
+    return this._browserContextPromise;
  }

-  private async _innerCreateBrowserContext(): Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> {
+  private async _setupBrowserContext(): Promise<BrowserContextAndBrowser> {
+    const { browser, browserContext } = await this._createBrowserContext();
+    await this._setupRequestInterception(browserContext);
+    for (const page of browserContext.pages())
+      this._onPageCreated(page);
+    browserContext.on('page', page => this._onPageCreated(page));
+    if (this.config.saveTrace) {
+      await browserContext.tracing.start({
+        name: 'trace',
+        screenshots: false,
+        snapshots: true,
+        sources: false,
+      });
+    }
+    return { browser, browserContext };
+  }
+
+  private async _createBrowserContext(): Promise<BrowserContextAndBrowser> {
    if (this.config.browser?.remoteEndpoint) {
      const url = new URL(this.config.browser?.remoteEndpoint);
      if (this.config.browser.browserName)
@@ -342,21 +355,23 @@ ${code.join('\n')}

    if (this.config.browser?.cdpEndpoint) {
      const browser = await playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-      const browserContext = browser.contexts()[0];
+      const browserContext = this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
      return { browser, browserContext };
    }

-    const browserContext = await launchPersistentContext(this.config.browser);
-    return { browserContext };
+    return this.config.browser?.isolated ?
+      await createIsolatedContext(this.config.browser) :
+      await launchPersistentContext(this.config.browser);
  }
 }

-async function launchPersistentContext(browserConfig: Config['browser']): Promise<playwright.BrowserContext> {
+async function createIsolatedContext(browserConfig: FullConfig['browser']): Promise<BrowserContextAndBrowser> {
  try {
    const browserName = browserConfig?.browserName ?? 'chromium';
-    const userDataDir = browserConfig?.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
    const browserType = playwright[browserName];
-    return await browserType.launchPersistentContext(userDataDir, { ...browserConfig?.launchOptions, ...browserConfig?.contextOptions });
+    const browser = await browserType.launch(browserConfig.launchOptions);
+    const browserContext = await browser.newContext(browserConfig.contextOptions);
+    return { browser, browserContext };
  } catch (error: any) {
    if (error.message.includes('Executable doesn\'t exist'))
      throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
@@ -364,7 +379,21 @@ async function launchPersistentContext(browserConfig: Config['browser']): Promis
  }
 }

-async function createUserDataDir(browserConfig: Config['browser']) {
+async function launchPersistentContext(browserConfig: FullConfig['browser']): Promise<BrowserContextAndBrowser> {
+  try {
+    const browserName = browserConfig.browserName ?? 'chromium';
+    const userDataDir = browserConfig.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
+    const browserType = playwright[browserName];
+    const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig.launchOptions, ...browserConfig.contextOptions });
+    return { browserContext };
+  } catch (error: any) {
+    if (error.message.includes('Executable doesn\'t exist'))
+      throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+    throw error;
+  }
+}
+
+async function createUserDataDir(browserConfig: FullConfig['browser']) {
  let cacheDirectory: string;
  if (process.platform === 'linux')
    cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
@@ -374,14 +403,10 @@ async function createUserDataDir(browserConfig: Config['browser']) {
    cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
  else
    throw new Error('Unsupported platform: ' + process.platform);
-  const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig?.launchOptions.channel ?? browserConfig?.browserName}-profile`);
+  const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
  await fs.promises.mkdir(result, { recursive: true });
  return result;
 }

-export async function generateLocator(locator: playwright.Locator): Promise<string> {
-  return (locator as any)._generateLocatorString();
-}
-
 const __filename = url.fileURLToPath(import.meta.url);
 export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));
--- a/src/index.ts
+++ b/src/index.ts
@@ -14,10 +14,12 @@
 * limitations under the License.
 */

-import { Connection } from './connection.js';
+import { Connection, createConnection as createConnectionImpl } from './connection.js';
+import { resolveConfig } from './config.js';

 import type { Config } from '../config.js';

-export async function createConnection(config: Config = {}): Promise<Connection> {
-  return createConnection(config);
+export async function createConnection(userConfig: Config = {}): Promise<Connection> {
+  const config = await resolveConfig(userConfig);
+  return createConnectionImpl(config);
 }
--- a/src/pageSnapshot.ts
+++ b/src/pageSnapshot.ts
@@ -15,20 +15,23 @@
 */

 import * as playwright from 'playwright';
-import yaml from 'yaml';
+import { callOnPageNoTrace } from './tools/utils.js';

-type PageOrFrameLocator = playwright.Page | playwright.FrameLocator;
+type PageEx = playwright.Page & {
+  _snapshotForAI: () => Promise<string>;
+};

 export class PageSnapshot {
-  private _frameLocators: PageOrFrameLocator[] = [];
+  private _page: playwright.Page;
  private _text!: string;

-  constructor() {
+  constructor(page: playwright.Page) {
+    this._page = page;
  }

  static async create(page: playwright.Page): Promise<PageSnapshot> {
-    const snapshot = new PageSnapshot();
-    await snapshot._build(page);
+    const snapshot = new PageSnapshot(page);
+    await snapshot._build();
    return snapshot;
  }

@@ -36,66 +39,20 @@ export class PageSnapshot {
    return this._text;
  }

-  private async _build(page: playwright.Page) {
-    const yamlDocument = await this._snapshotFrame(page);
+  private async _build() {
+    // FIXME: Rountrip evaluate to ensure _snapshotForAI works.
+    // This probably broke once we moved off locator snapshots
+    await this._page.evaluate(() => 1);
+    const snapshot = await callOnPageNoTrace(this._page, page => (page as PageEx)._snapshotForAI());
    this._text = [
      `- Page Snapshot`,
      '```yaml',
-      yamlDocument.toString({ indentSeq: false }).trim(),
+      snapshot,
      '```',
    ].join('\n');
  }

-  private async _snapshotFrame(frame: playwright.Page | playwright.FrameLocator) {
-    const frameIndex = this._frameLocators.push(frame) - 1;
-    const snapshotString = await frame.locator('body').ariaSnapshot({ ref: true, emitGeneric: true });
-    const snapshot = yaml.parseDocument(snapshotString);
-
-    const visit = async (node: any): Promise<unknown> => {
-      if (yaml.isPair(node)) {
-        await Promise.all([
-          visit(node.key).then(k => node.key = k),
-          visit(node.value).then(v => node.value = v)
-        ]);
-      } else if (yaml.isSeq(node) || yaml.isMap(node)) {
-        node.items = await Promise.all(node.items.map(visit));
-      } else if (yaml.isScalar(node)) {
-        if (typeof node.value === 'string') {
-          const value = node.value;
-          if (frameIndex > 0)
-            node.value = value.replace('[ref=', `[ref=f${frameIndex}`);
-          if (value.startsWith('iframe ')) {
-            const ref = value.match(/\[ref=(.*)\]/)?.[1];
-            if (ref) {
-              try {
-                const childSnapshot = await this._snapshotFrame(frame.frameLocator(`aria-ref=${ref}`));
-                return snapshot.createPair(node.value, childSnapshot);
-              } catch (error) {
-                return snapshot.createPair(node.value, '<could not take iframe snapshot>');
-              }
-            }
-          }
-        }
-      }
-
-      return node;
-    };
-    await visit(snapshot.contents);
-    return snapshot;
-  }
-
  refLocator(ref: string): playwright.Locator {
-    let frame = this._frameLocators[0];
-    const match = ref.match(/^f(\d+)(.*)/);
-    if (match) {
-      const frameIndex = parseInt(match[1], 10);
-      frame = this._frameLocators[frameIndex];
-      ref = match[2];
-    }
-
-    if (!frame)
-      throw new Error(`Frame does not exist. Provide ref from the most current snapshot.`);
-
-    return frame.locator(`aria-ref=${ref}`);
+    return this._page.locator(`aria-ref=${ref}`);
  }
 }
--- a/src/program.ts
+++ b/src/program.ts
@@ -17,7 +17,9 @@
 import { program } from 'commander';

 import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveConfig } from './config.js';
+import { resolveCLIConfig } from './config.js';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';

 import type { Connection } from './connection.js';
 import { packageJSON } from './context.js';
@@ -25,23 +27,33 @@ import { packageJSON } from './context.js';
 program
    .version('Version ' + packageJSON.version)
    .name(packageJSON.name)
-    .option('--browser <browser>', 'Browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
-    .option('--caps <caps>', 'Comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
+    .option('--allowed-origins <origins>', 'semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
+    .option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
+    .option('--block-service-workers', 'block service workers')
+    .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--caps <caps>', 'comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
    .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
-    .option('--executable-path <path>', 'Path to the browser executable.')
-    .option('--headless', 'Run browser in headless mode, headed by default')
-    .option('--device <device>', 'Device to emulate, for example: "iPhone 15"')
-    .option('--user-data-dir <path>', 'Path to the user data directory')
-    .option('--port <port>', 'Port to listen on for SSE transport.')
-    .option('--host <host>', 'Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
-    .option('--allowed-origins <origins>', 'Semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
-    .option('--blocked-origins <origins>', 'Semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
+    .option('--config <path>', 'path to the configuration file.')
+    .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
+    .option('--executable-path <path>', 'path to the browser executable.')
+    .option('--headless', 'run browser in headless mode, headed by default')
+    .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--ignore-https-errors', 'ignore https errors')
+    .option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
+    .option('--no-image-responses', 'do not send image responses to the client.')
+    .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
+    .option('--output-dir <path>', 'path to the directory for output files.')
+    .option('--port <port>', 'port to listen on for SSE transport.')
+    .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
+    .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
+    .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
+    .option('--user-agent <ua string>', 'specify user agent string')
+    .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
+    .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
    .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
-    .option('--no-image-responses', 'Do not send image responses to the client.')
-    .option('--output-dir <path>', 'Path to the directory for output files.')
-    .option('--config <path>', 'Path to the configuration file.')
    .action(async options => {
-      const config = await resolveConfig(options);
+      const config = await resolveCLIConfig(options);
      const connectionList: Connection[] = [];
      setupExitWatchdog(connectionList);

@@ -49,6 +61,14 @@ program
        startHttpTransport(config, +options.port, options.host, connectionList);
      else
        await startStdioTransport(config, connectionList);
+
+      if (config.saveTrace) {
+        const server = await startTraceViewerServer();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+      }
    });

 function setupExitWatchdog(connectionList: Connection[]) {
--- a/src/tab.ts
+++ b/src/tab.ts
@@ -19,11 +19,12 @@ import * as playwright from 'playwright';
 import { PageSnapshot } from './pageSnapshot.js';

 import type { Context } from './context.js';
+import { callOnPageNoTrace } from './tools/utils.js';

 export class Tab {
  readonly context: Context;
  readonly page: playwright.Page;
-  private _console: playwright.ConsoleMessage[] = [];
+  private _consoleMessages: playwright.ConsoleMessage[] = [];
  private _requests: Map<playwright.Request, playwright.Response | null> = new Map();
  private _snapshot: PageSnapshot | undefined;
  private _onPageClose: (tab: Tab) => void;
@@ -32,13 +33,9 @@ export class Tab {
    this.context = context;
    this.page = page;
    this._onPageClose = onPageClose;
-    page.on('console', event => this._console.push(event));
+    page.on('console', event => this._consoleMessages.push(event));
    page.on('request', request => this._requests.set(request, null));
    page.on('response', response => this._requests.set(response.request(), response));
-    page.on('framenavigated', frame => {
-      if (!frame.parentFrame())
-        this._clearCollectedArtifacts();
-    });
    page.on('close', () => this._onClose());
    page.on('filechooser', chooser => {
      this.context.setModalState({
@@ -56,7 +53,7 @@ export class Tab {
  }

  private _clearCollectedArtifacts() {
-    this._console.length = 0;
+    this._consoleMessages.length = 0;
    this._requests.clear();
  }

@@ -65,10 +62,39 @@ export class Tab {
    this._onPageClose(this);
  }

+  async title(): Promise<string> {
+    return await callOnPageNoTrace(this.page, page => page.title());
+  }
+
+  async waitForLoadState(state: 'load', options?: { timeout?: number }): Promise<void> {
+    await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => {}));
+  }
+
  async navigate(url: string) {
-    await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    this._clearCollectedArtifacts();
+
+    const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => {}));
+    try {
+      await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    } catch (_e: unknown) {
+      const e = _e as Error;
+      const mightBeDownload =
+        e.message.includes('net::ERR_ABORTED') // chromium
+        || e.message.includes('Download is starting'); // firefox + webkit
+      if (!mightBeDownload)
+        throw e;
+
+      // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
+      const download = await Promise.race([
+        downloadEvent,
+        new Promise(resolve => setTimeout(resolve, 500)),
+      ]);
+      if (!download)
+        throw e;
+    }
+
    // Cap load event to 5 seconds, the page is operational at this point.
-    await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
+    await this.waitForLoadState('load', { timeout: 5000 });
  }

  hasSnapshot(): boolean {
@@ -81,8 +107,8 @@ export class Tab {
    return this._snapshot;
  }

-  console(): playwright.ConsoleMessage[] {
-    return this._console;
+  consoleMessages(): playwright.ConsoleMessage[] {
+    return this._consoleMessages;
  }

  requests(): Map<playwright.Request, playwright.Response | null> {
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -25,8 +25,10 @@ import network from './tools/network.js';
 import pdf from './tools/pdf.js';
 import snapshot from './tools/snapshot.js';
 import tabs from './tools/tabs.js';
-import screen from './tools/screen.js';
+import screenshot from './tools/screenshot.js';
 import testing from './tools/testing.js';
+import vision from './tools/vision.js';
+import wait from './tools/wait.js';

 import type { Tool } from './tools/tool.js';

@@ -40,12 +42,14 @@ export const snapshotTools: Tool<any>[] = [
  ...navigate(true),
  ...network,
  ...pdf,
+  ...screenshot,
  ...snapshot,
  ...tabs(true),
  ...testing,
+  ...wait(true),
 ];

-export const screenshotTools: Tool<any>[] = [
+export const visionTools: Tool<any>[] = [
  ...common(false),
  ...console,
  ...dialogs(false),
@@ -55,7 +59,8 @@ export const screenshotTools: Tool<any>[] = [
  ...navigate(false),
  ...network,
  ...pdf,
-  ...screen,
  ...tabs(false),
  ...testing,
+  ...vision,
+  ...wait(false),
 ];
--- a/src/tools/common.ts
+++ b/src/tools/common.ts
@@ -17,29 +17,6 @@
 import { z } from 'zod';
 import { defineTool, type ToolFactory } from './tool.js';

-const wait: ToolFactory = captureSnapshot => defineTool({
-  capability: 'wait',
-
-  schema: {
-    name: 'browser_wait',
-    title: 'Wait',
-    description: 'Wait for a specified time in seconds',
-    inputSchema: z.object({
-      time: z.number().describe('The time to wait in seconds'),
-    }),
-    type: 'readOnly',
-  },
-
-  handle: async (context, params) => {
-    await new Promise(f => setTimeout(f, Math.min(10000, params.time * 1000)));
-    return {
-      code: [`// Waited for ${params.time} seconds`],
-      captureSnapshot,
-      waitForNetwork: false,
-    };
-  },
-});
-
 const close = defineTool({
  capability: 'core',

@@ -54,7 +31,7 @@ const close = defineTool({
  handle: async context => {
    await context.close();
    return {
-      code: [`// Internal to close the page`],
+      code: [`await page.close()`],
      captureSnapshot: false,
      waitForNetwork: false,
    };
@@ -97,6 +74,5 @@ const resize: ToolFactory = captureSnapshot => defineTool({

 export default (captureSnapshot: boolean) => [
  close,
-  wait(captureSnapshot),
  resize(captureSnapshot)
 ];
--- a/src/tools/console.ts
+++ b/src/tools/console.ts
@@ -27,7 +27,7 @@ const console = defineTool({
    type: 'readOnly',
  },
  handle: async context => {
-    const messages = context.currentTabOrDie().console();
+    const messages = context.currentTabOrDie().consoleMessages();
    const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).join('\n');
    return {
      code: [`// <internal code to get console messages>`],
--- a/src/tools/install.ts
+++ b/src/tools/install.ts
@@ -33,7 +33,7 @@ const install = defineTool({
  },

  handle: async context => {
-    const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.launchOptions.browserName ?? 'chrome';
+    const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'chrome';
    const cliUrl = import.meta.resolve('playwright/package.json');
    const cliPath = path.join(fileURLToPath(cliUrl), '..', 'cli.js');
    const child = fork(cliPath, ['install', channel], {
--- a/src/tools/pdf.ts
+++ b/src/tools/pdf.ts
@@ -20,6 +20,10 @@ import { defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';

+const pdfSchema = z.object({
+  filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
+});
+
 const pdf = defineTool({
  capability: 'pdf',

@@ -27,13 +31,13 @@ const pdf = defineTool({
    name: 'browser_pdf_save',
    title: 'Save as PDF',
    description: 'Save page as PDF',
-    inputSchema: z.object({}),
+    inputSchema: pdfSchema,
    type: 'readOnly',
  },

-  handle: async context => {
+  handle: async (context, params) => {
    const tab = context.currentTabOrDie();
-    const fileName = await outputFile(context.config, `page-${new Date().toISOString()}.pdf`);
+    const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);

    const code = [
      `// Save page as ${fileName}`,
--- a/src/tools/screenshot.ts
+++ b/src/tools/screenshot.ts
@@ -0,0 +1,90 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+
+import { defineTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
+import { generateLocator } from './utils.js';
+
+import type * as playwright from 'playwright';
+
+const screenshotSchema = z.object({
+  raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+  filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
+  element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
+  ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
+}).refine(data => {
+  return !!data.element === !!data.ref;
+}, {
+  message: 'Both element and ref must be provided or neither.',
+  path: ['ref', 'element']
+});
+
+const screenshot = defineTool({
+  capability: 'core',
+  schema: {
+    name: 'browser_take_screenshot',
+    title: 'Take a screenshot',
+    description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
+    inputSchema: screenshotSchema,
+    type: 'readOnly',
+  },
+
+  handle: async (context, params) => {
+    const tab = context.currentTabOrDie();
+    const snapshot = tab.snapshotOrDie();
+    const fileType = params.raw ? 'png' : 'jpeg';
+    const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
+    const options: playwright.PageScreenshotOptions = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
+    const isElementScreenshot = params.element && params.ref;
+
+    const code = [
+      `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
+    ];
+
+    const locator = params.ref ? snapshot.refLocator(params.ref) : null;
+
+    if (locator)
+      code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+    else
+      code.push(`await page.screenshot(${javascript.formatObject(options)});`);
+
+    const includeBase64 = !context.config.noImageResponses;
+    const action = async () => {
+      const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+      return {
+        content: includeBase64 ? [{
+          type: 'image' as 'image',
+          data: screenshot.toString('base64'),
+          mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+        }] : []
+      };
+    };
+
+    return {
+      code,
+      action,
+      captureSnapshot: true,
+      waitForNetwork: false,
+    };
+  }
+});
+
+export default [
+  screenshot,
+];
--- a/src/tools/snapshot.ts
+++ b/src/tools/snapshot.ts
@@ -18,9 +18,7 @@ import { z } from 'zod';

 import { defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
-import { outputFile } from '../config.js';
-
-import type * as playwright from 'playwright';
+import { generateLocator } from './utils.js';

 const snapshot = defineTool({
  capability: 'core',
@@ -218,71 +216,6 @@ const selectOption = defineTool({
  },
 });

-const screenshotSchema = z.object({
-  raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
-  element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
-  ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
-}).refine(data => {
-  return !!data.element === !!data.ref;
-}, {
-  message: 'Both element and ref must be provided or neither.',
-  path: ['ref', 'element']
-});
-
-const screenshot = defineTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_take_screenshot',
-    title: 'Take a screenshot',
-    description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
-    inputSchema: screenshotSchema,
-    type: 'readOnly',
-  },
-
-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const snapshot = tab.snapshotOrDie();
-    const fileType = params.raw ? 'png' : 'jpeg';
-    const fileName = await outputFile(context.config, `page-${new Date().toISOString()}.${fileType}`);
-    const options: playwright.PageScreenshotOptions = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
-    const isElementScreenshot = params.element && params.ref;
-
-    const code = [
-      `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
-    ];
-
-    const locator = params.ref ? snapshot.refLocator(params.ref) : null;
-
-    if (locator)
-      code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
-    else
-      code.push(`await page.screenshot(${javascript.formatObject(options)});`);
-
-    const includeBase64 = !context.config.noImageResponses;
-    const action = async () => {
-      const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
-      return {
-        content: includeBase64 ? [{
-          type: 'image' as 'image',
-          data: screenshot.toString('base64'),
-          mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
-        }] : []
-      };
-    };
-
-    return {
-      code,
-      action,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
-  }
-});
-
-export async function generateLocator(locator: playwright.Locator): Promise<string> {
-  return (locator as any)._generateLocatorString();
-}
-
 export default [
  snapshot,
  click,
@@ -290,5 +223,4 @@ export default [
  hover,
  type,
  selectOption,
-  screenshot,
 ];
--- a/src/tools/utils.ts
+++ b/src/tools/utils.ts
@@ -16,8 +16,9 @@

 import type * as playwright from 'playwright';
 import type { Context } from '../context.js';
+import type { Tab } from '../tab.js';

-export async function waitForCompletion<R>(context: Context, page: playwright.Page, callback: () => Promise<R>): Promise<R> {
+export async function waitForCompletion<R>(context: Context, tab: Tab, callback: () => Promise<R>): Promise<R> {
  const requests = new Set<playwright.Request>();
  let frameNavigated = false;
  let waitCallback: () => void = () => {};
@@ -36,9 +37,7 @@ export async function waitForCompletion<R>(context: Context, page: playwright.Pa
    frameNavigated = true;
    dispose();
    clearTimeout(timeout);
-    void frame.waitForLoadState('load').then(() => {
-      waitCallback();
-    });
+    void tab.waitForLoadState('load').then(waitCallback);
  };

  const onTimeout = () => {
@@ -46,15 +45,15 @@ export async function waitForCompletion<R>(context: Context, page: playwright.Pa
    waitCallback();
  };

-  page.on('request', requestListener);
-  page.on('requestfinished', requestFinishedListener);
-  page.on('framenavigated', frameNavigateListener);
+  tab.page.on('request', requestListener);
+  tab.page.on('requestfinished', requestFinishedListener);
+  tab.page.on('framenavigated', frameNavigateListener);
  const timeout = setTimeout(onTimeout, 10000);

  const dispose = () => {
-    page.off('request', requestListener);
-    page.off('requestfinished', requestFinishedListener);
-    page.off('framenavigated', frameNavigateListener);
+    tab.page.off('request', requestListener);
+    tab.page.off('requestfinished', requestFinishedListener);
+    tab.page.off('framenavigated', frameNavigateListener);
    clearTimeout(timeout);
  };

@@ -77,3 +76,11 @@ export function sanitizeForFilePath(s: string) {
    return sanitize(s);
  return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }
+
+export async function generateLocator(locator: playwright.Locator): Promise<string> {
+  return (locator as any)._frame._wrapApiCall(() => (locator as any)._generateLocatorString(), true);
+}
+
+export async function callOnPageNoTrace<T>(page: playwright.Page, callback: (page: playwright.Page) => Promise<T>): Promise<T> {
+  return await (page as any)._wrapApiCall(() => callback(page), true);
+}
--- a/src/tools/vision.ts
+++ b/src/tools/vision.ts
--- a/src/tools/wait.ts
+++ b/src/tools/wait.ts
@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import { defineTool, type ToolFactory } from './tool.js';
+
+const wait: ToolFactory = captureSnapshot => defineTool({
+  capability: 'wait',
+
+  schema: {
+    name: 'browser_wait_for',
+    title: 'Wait for',
+    description: 'Wait for text to appear or disappear or a specified time to pass',
+    inputSchema: z.object({
+      time: z.number().optional().describe('The time to wait in seconds'),
+      text: z.string().optional().describe('The text to wait for'),
+      textGone: z.string().optional().describe('The text to wait for to disappear'),
+    }),
+    type: 'readOnly',
+  },
+
+  handle: async (context, params) => {
+    if (!params.text && !params.textGone && !params.time)
+      throw new Error('Either time, text or textGone must be provided');
+
+    const code: string[] = [];
+
+    if (params.time) {
+      code.push(`await new Promise(f => setTimeout(f, ${params.time!} * 1000));`);
+      await new Promise(f => setTimeout(f, Math.min(10000, params.time! * 1000)));
+    }
+
+    const tab = context.currentTabOrDie();
+    const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
+    const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
+
+    if (goneLocator) {
+      code.push(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+      await goneLocator.waitFor({ state: 'hidden' });
+    }
+
+    if (locator) {
+      code.push(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+      await locator.waitFor({ state: 'visible' });
+    }
+
+    return {
+      code,
+      captureSnapshot,
+      waitForNetwork: false,
+    };
+  },
+});
+
+export default (captureSnapshot: boolean) => [
+  wait(captureSnapshot),
+];
--- a/src/transport.ts
+++ b/src/transport.ts
@@ -24,16 +24,16 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

 import { createConnection } from './connection.js';

-import type { Config } from '../config.js';
 import type { Connection } from './connection.js';
+import type { FullConfig } from './config.js';

-export async function startStdioTransport(config: Config, connectionList: Connection[]) {
+export async function startStdioTransport(config: FullConfig, connectionList: Connection[]) {
  const connection = await createConnection(config);
  await connection.connect(new StdioServerTransport());
  connectionList.push(connection);
 }

-async function handleSSE(config: Config, req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, SSEServerTransport>, connectionList: Connection[]) {
+async function handleSSE(config: FullConfig, req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, SSEServerTransport>, connectionList: Connection[]) {
  if (req.method === 'POST') {
    const sessionId = url.searchParams.get('sessionId');
    if (!sessionId) {
@@ -68,7 +68,7 @@ async function handleSSE(config: Config, req: http.IncomingMessage, res: http.Se
  res.end('Method not allowed');
 }

-async function handleStreamable(config: Config, req: http.IncomingMessage, res: http.ServerResponse, sessions: Map<string, StreamableHTTPServerTransport>, connectionList: Connection[]) {
+async function handleStreamable(config: FullConfig, req: http.IncomingMessage, res: http.ServerResponse, sessions: Map<string, StreamableHTTPServerTransport>, connectionList: Connection[]) {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  if (sessionId) {
    const transport = sessions.get(sessionId);
@@ -104,7 +104,7 @@ async function handleStreamable(config: Config, req: http.IncomingMessage, res:
  res.end('Invalid request');
 }

-export function startHttpTransport(config: Config, port: number, hostname: string | undefined, connectionList: Connection[]) {
+export function startHttpTransport(config: FullConfig, port: number, hostname: string | undefined, connectionList: Connection[]) {
  const sseSessions = new Map<string, SSEServerTransport>();
  const streamableSessions = new Map<string, StreamableHTTPServerTransport>();
  const httpServer = http.createServer(async (req, res) => {
@@ -140,6 +140,6 @@ export function startHttpTransport(config: Config, port: number, hostname: strin
      'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
    ].join('\n');
    // eslint-disable-next-line no-console
-    console.log(message);
+    console.error(message);
  });
 }
--- a/tests/capabilities.spec.ts
+++ b/tests/capabilities.spec.ts
@@ -43,7 +43,7 @@ test('test snapshot tool list', async ({ client }) => {
    'browser_tab_new',
    'browser_tab_select',
    'browser_take_screenshot',
-    'browser_wait',
+    'browser_wait_for',
  ]));
 });

@@ -72,7 +72,7 @@ test('test vision tool list', async ({ visionClient }) => {
    'browser_tab_list',
    'browser_tab_new',
    'browser_tab_select',
-    'browser_wait',
+    'browser_wait_for',
  ]));
 });

--- a/tests/cdp.spec.ts
+++ b/tests/cdp.spec.ts
@@ -16,18 +16,21 @@

 import { test, expect } from './fixtures.js';

-test('cdp server', async ({ cdpEndpoint, startClient }) => {
-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+test('cdp server', async ({ cdpServer, startClient, server }) => {
+  await cdpServer.start();
+  const client = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 });

-test('cdp server reuse tab', async ({ cdpEndpoint, startClient }) => {
-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+test('cdp server reuse tab', async ({ cdpServer, startClient, server }) => {
+  const browserContext = await cdpServer.start();
+  const client = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
+
+  const [page] = browserContext.pages();
+  await page.goto(server.HELLO_WORLD);

  expect(await client.callTool({
    name: 'browser_click',
@@ -39,36 +42,36 @@ test('cdp server reuse tab', async ({ cdpEndpoint, startClient }) => {

  expect(await client.callTool({
    name: 'browser_snapshot',
-    arguments: {},
  })).toHaveTextContent(`
 - Ran Playwright code:
 \`\`\`js
 // <internal code to capture accessibility snapshot>
 \`\`\`

- Page URL: data:text/html,hello world
- Page Title: 
+- Page URL: ${server.HELLO_WORLD}
+- Page Title: Title
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s1e2]: hello world
+- generic [ref=e1]: Hello, world!
 \`\`\`
 `);
 });

-test('should throw connection error and allow re-connecting', async ({ cdpEndpoint, startClient }) => {
-  const port = 3200 + test.info().parallelIndex;
-  const client = await startClient({ args: [`--cdp-endpoint=http://localhost:${port}`] });
+test('should throw connection error and allow re-connecting', async ({ cdpServer, startClient, server }) => {
+  const client = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
+
+  server.setContent('/', `
+    <title>Title</title>
+    <body>Hello, world!</body>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.PREFIX },
  })).toContainTextContent(`Error: browserType.connectOverCDP: connect ECONNREFUSED`);
-  await cdpEndpoint(port);
+  await cdpServer.start();
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 });
--- a/tests/config.spec.ts
+++ b/tests/config.spec.ts
@@ -19,21 +19,24 @@ import fs from 'node:fs';
 import { Config } from '../config.js';
 import { test, expect } from './fixtures.js';

-test('config user data dir', async ({ startClient, mcpBrowser }, testInfo) => {
+test('config user data dir', async ({ startClient, localOutputPath, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>Hello, world!</body>
+  `, 'text/html');
+
  const config: Config = {
    browser: {
-      userDataDir: testInfo.outputPath('user-data-dir'),
+      userDataDir: localOutputPath('user-data-dir'),
    },
  };
-  const configPath = testInfo.outputPath('config.json');
+  const configPath = localOutputPath('config.json');
  await fs.promises.writeFile(configPath, JSON.stringify(config, null, 2));

  const client = await startClient({ args: ['--config', configPath] });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.PREFIX },
  })).toContainTextContent(`Hello, world!`);

  const files = await fs.promises.readdir(config.browser!.userDataDir!);
--- a/tests/console.spec.ts
+++ b/tests/console.spec.ts
@@ -16,17 +16,26 @@

 import { test, expect } from './fixtures.js';

-test('browser_console_messages', async ({ client }) => {
+test('browser_console_messages', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <script>
+        console.log("Hello, world!");
+        console.error("Error");
+      </script>
+    </html>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
    arguments: {
-      url: 'data:text/html,<html><script>console.log("Hello, world!");console.error("Error"); </script></html>',
+      url: server.PREFIX,
    },
  });

  const resource = await client.callTool({
    name: 'browser_console_messages',
-    arguments: {},
  });
  expect(resource).toHaveTextContent([
    '[LOG] Hello, world!',
--- a/tests/core.spec.ts
+++ b/tests/core.spec.ts
@@ -16,42 +16,43 @@

 import { test, expect } from './fixtures.js';

-test('browser_navigate', async ({ client }) => {
+test('browser_navigate', async ({ client, server }) => {
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
  })).toHaveTextContent(`
 - Ran Playwright code:
 \`\`\`js
-// Navigate to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-await page.goto('data:text/html,<html><title>Title</title><body>Hello, world!</body></html>');
+// Navigate to ${server.HELLO_WORLD}
+await page.goto('${server.HELLO_WORLD}');
 \`\`\`

- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
+- Page URL: ${server.HELLO_WORLD}
 - Page Title: Title
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s1e2]: Hello, world!
+- generic [ref=e1]: Hello, world!
 \`\`\`
 `
  );
 });

-test('browser_click', async ({ client }) => {
+test('browser_click', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <button>Submit</button>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button>Submit</button></html>',
-    },
+    arguments: { url: server.PREFIX },
  });

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Submit button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toHaveTextContent(`
 - Ran Playwright code:
@@ -60,28 +61,34 @@ test('browser_click', async ({ client }) => {
 await page.getByRole('button', { name: 'Submit' }).click();
 \`\`\`

- Page URL: data:text/html,<html><title>Title</title><button>Submit</button></html>
+- Page URL: ${server.PREFIX}
 - Page Title: Title
 - Page Snapshot
 \`\`\`yaml
- button "Submit" [ref=s2e3]
+- button "Submit" [ref=e2]
 \`\`\`
 `);
 });

-test('browser_select_option', async ({ client }) => {
+test('browser_select_option', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <select>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+    </select>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><select><option value="foo">Foo</option><option value="bar">Bar</option></select></html>',
-    },
+    arguments: { url: server.PREFIX },
  });

  expect(await client.callTool({
    name: 'browser_select_option',
    arguments: {
      element: 'Select',
-      ref: 's1e3',
+      ref: 'e2',
      values: ['bar'],
    },
  })).toHaveTextContent(`
@@ -91,30 +98,37 @@ test('browser_select_option', async ({ client }) => {
 await page.getByRole('combobox').selectOption(['bar']);
 \`\`\`

- Page URL: data:text/html,<html><title>Title</title><select><option value="foo">Foo</option><option value="bar">Bar</option></select></html>
+- Page URL: ${server.PREFIX}
 - Page Title: Title
 - Page Snapshot
 \`\`\`yaml
- combobox [ref=s2e3]:
+- combobox [ref=e2]:
  - option "Foo"
  - option "Bar" [selected]
 \`\`\`
 `);
 });

-test('browser_select_option (multiple)', async ({ client }) => {
+test('browser_select_option (multiple)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <select multiple>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+      <option value="baz">Baz</option>
+    </select>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><select multiple><option value="foo">Foo</option><option value="bar">Bar</option><option value="baz">Baz</option></select></html>',
-    },
+    arguments: { url: server.PREFIX },
  });

  expect(await client.callTool({
    name: 'browser_select_option',
    arguments: {
      element: 'Select',
-      ref: 's1e3',
+      ref: 'e2',
      values: ['bar', 'baz'],
    },
  })).toHaveTextContent(`
@@ -124,52 +138,62 @@ test('browser_select_option (multiple)', async ({ client }) => {
 await page.getByRole('listbox').selectOption(['bar', 'baz']);
 \`\`\`

- Page URL: data:text/html,<html><title>Title</title><select multiple><option value="foo">Foo</option><option value="bar">Bar</option><option value="baz">Baz</option></select></html>
+- Page URL: ${server.PREFIX}
 - Page Title: Title
 - Page Snapshot
 \`\`\`yaml
- listbox [ref=s2e3]:
-  - option "Foo" [ref=s2e4]
-  - option "Bar" [selected] [ref=s2e5]
-  - option "Baz" [selected] [ref=s2e6]
+- listbox [ref=e2]:
+  - option "Foo" [ref=e3]
+  - option "Bar" [selected] [ref=e4]
+  - option "Baz" [selected] [ref=e5]
 \`\`\`
 `);
 });

-test('browser_type', async ({ client }) => {
+test('browser_type', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>
+    </html>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
    arguments: {
-      url: `data:text/html,<input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>`,
+      url: server.PREFIX,
    },
  });
  await client.callTool({
    name: 'browser_type',
    arguments: {
      element: 'textbox',
-      ref: 's1e3',
+      ref: 'e2',
      text: 'Hi!',
      submit: true,
    },
  });
  expect(await client.callTool({
    name: 'browser_console_messages',
-    arguments: {},
  })).toHaveTextContent('[LOG] Key pressed: Enter , Text: Hi!');
 });

-test('browser_type (slowly)', async ({ client }) => {
+test('browser_type (slowly)', async ({ client, server }) => {
+  server.setContent('/', `
+    <input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>
+  `, 'text/html');
+
  await client.callTool({
    name: 'browser_navigate',
    arguments: {
-      url: `data:text/html,<input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>`,
+      url: server.PREFIX,
    },
  });
  await client.callTool({
    name: 'browser_type',
    arguments: {
      element: 'textbox',
-      ref: 's1e3',
+      ref: 'e2',
      text: 'Hi!',
      submit: true,
      slowly: true,
@@ -177,7 +201,6 @@ test('browser_type (slowly)', async ({ client }) => {
  });
  expect(await client.callTool({
    name: 'browser_console_messages',
-    arguments: {},
  })).toHaveTextContent([
    '[LOG] Key pressed: H Text: ',
    '[LOG] Key pressed: i Text: H',
@@ -186,12 +209,18 @@ test('browser_type (slowly)', async ({ client }) => {
  ].join('\n'));
 });

-test('browser_resize', async ({ client }) => {
+test('browser_resize', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Resize Test</title>
+    <body>
+      <div id="size">Waiting for resize...</div>
+      <script>new ResizeObserver(() => { document.getElementById("size").textContent = \`Window size: \${window.innerWidth}x\${window.innerHeight}\`; }).observe(document.body);
+      </script>
+    </body>
+  `, 'text/html');
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Resize Test</title><body><div id="size">Waiting for resize...</div><script>new ResizeObserver(() => { document.getElementById("size").textContent = `Window size: ${window.innerWidth}x${window.innerHeight}`; }).observe(document.body);</script></body></html>',
-    },
+    arguments: { url: server.PREFIX },
  });

  const response = await client.callTool({
@@ -206,5 +235,5 @@ test('browser_resize', async ({ client }) => {
 // Resize browser window to 390x780
 await page.setViewportSize({ width: 390, height: 780 });
 \`\`\``);
-  await expect.poll(() => client.callTool({ name: 'browser_snapshot', arguments: {} })).toContainTextContent('Window size: 390x780');
+  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent('Window size: 390x780');
 });
--- a/tests/dialogs.spec.ts
+++ b/tests/dialogs.spec.ts
@@ -19,19 +19,18 @@ import { test, expect } from './fixtures.js';
 // https://github.com/microsoft/playwright/issues/35663
 test.skip(({ mcpBrowser, mcpHeadless }) => mcpBrowser === 'webkit' && mcpHeadless);

-test('alert dialog', async ({ client }) => {
+test('alert dialog', async ({ client, server }) => {
+  server.setContent('/', `<button onclick="alert('Alert')">Button</button>`, 'text/html');
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="alert(\'Alert\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toHaveTextContent(`- Ran Playwright code:
 \`\`\`js
@@ -55,29 +54,35 @@ await page.getByRole('button', { name: 'Button' }).click();
 // <internal code to handle "alert" dialog>
 \`\`\`

- Page URL: data:text/html,<html><title>Title</title><button onclick="alert('Alert')">Button</button></html>
- Page Title: Title
+- Page URL: ${server.PREFIX}
+- Page Title: 
 - Page Snapshot
 \`\`\`yaml
- button "Button" [ref=s2e3]
+- button "Button" [ref=e2]
 \`\`\`
 `);
 });

-test('two alert dialogs', async ({ client }) => {
+test('two alert dialogs', async ({ client, server }) => {
  test.fixme(true, 'Race between the dialog and ariaSnapshot');
+
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="alert('Alert 1');alert('Alert 2');">Button</button>
+    </body>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="alert(\'Alert 1\');alert(\'Alert 2\');">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toHaveTextContent(`- Ran Playwright code:
 \`\`\`js
@@ -98,19 +103,24 @@ await page.getByRole('button', { name: 'Button' }).click();
  expect(result).not.toContainTextContent('### Modal state');
 });

-test('confirm dialog (true)', async ({ client }) => {
+test('confirm dialog (true)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = confirm('Confirm')">Button</button>
+    </body>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = confirm(\'Confirm\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
 - ["confirm" dialog with message "Confirm"]: can be handled by the "browser_handle_dialog" tool`);
@@ -126,23 +136,28 @@ test('confirm dialog (true)', async ({ client }) => {
  expect(result).toContainTextContent('// <internal code to handle "confirm" dialog>');
  expect(result).toContainTextContent(`- Page Snapshot
 \`\`\`yaml
- generic [ref=s2e2]: "true"
+- generic [ref=e1]: "true"
 \`\`\``);
 });

-test('confirm dialog (false)', async ({ client }) => {
+test('confirm dialog (false)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = confirm('Confirm')">Button</button>
+    </body>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = confirm(\'Confirm\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
 - ["confirm" dialog with message "Confirm"]: can be handled by the "browser_handle_dialog" tool`);
@@ -156,23 +171,28 @@ test('confirm dialog (false)', async ({ client }) => {

  expect(result).toContainTextContent(`- Page Snapshot
 \`\`\`yaml
- generic [ref=s2e2]: "false"
+- generic [ref=e1]: "false"
 \`\`\``);
 });

-test('prompt dialog', async ({ client }) => {
+test('prompt dialog', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = prompt('Prompt')">Button</button>
+    </body>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = prompt(\'Prompt\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
 - ["prompt" dialog with message "Prompt"]: can be handled by the "browser_handle_dialog" tool`);
@@ -187,6 +207,6 @@ test('prompt dialog', async ({ client }) => {

  expect(result).toContainTextContent(`- Page Snapshot
 \`\`\`yaml
- generic [ref=s2e2]: Answer
+- generic [ref=e1]: Answer
 \`\`\``);
 });
--- a/tests/files.spec.ts
+++ b/tests/files.spec.ts
@@ -18,16 +18,20 @@ import { test, expect } from './fixtures.js';
 import fs from 'fs/promises';
 import path from 'path';

-test('browser_file_upload', async ({ client }) => {
+test('browser_file_upload', async ({ client, localOutputPath, server }) => {
+  server.setContent('/', `
+    <input type="file" />
+    <button>Button</button>
+  `, 'text/html');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><input type="file" /><button>Button</button></html>',
-    },
+    arguments: { url: server.PREFIX },
  })).toContainTextContent(`
 \`\`\`yaml
- button "Choose File" [ref=s1e3]
- button "Button" [ref=s1e4]
+- generic [ref=e1]:
+  - button "Choose File" [ref=e2]
+  - button "Button" [ref=e3]
 \`\`\``);

  {
@@ -45,12 +49,12 @@ The tool "browser_file_upload" can only be used when there is related modal stat
    name: 'browser_click',
    arguments: {
      element: 'Textbox',
-      ref: 's1e3',
+      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
 - [File chooser]: can be handled by the "browser_file_upload" tool`);

-  const filePath = test.info().outputPath('test.txt');
+  const filePath = localOutputPath('test.txt');
  await fs.writeFile(filePath, 'Hello, world!');

  {
@@ -64,8 +68,9 @@ The tool "browser_file_upload" can only be used when there is related modal stat
    expect(response).not.toContainTextContent('### Modal state');
    expect(response).toContainTextContent(`
 \`\`\`yaml
- button "Choose File" [ref=s3e3]
- button "Button" [ref=s3e4]
+- generic [ref=e1]:
+  - button "Choose File" [ref=e2]
+  - button "Button" [ref=e3]
 \`\`\``);
  }

@@ -74,7 +79,7 @@ The tool "browser_file_upload" can only be used when there is related modal stat
      name: 'browser_click',
      arguments: {
        element: 'Textbox',
-        ref: 's3e3',
+        ref: 'e2',
      },
    });

@@ -86,7 +91,7 @@ The tool "browser_file_upload" can only be used when there is related modal stat
      name: 'browser_click',
      arguments: {
        element: 'Button',
-        ref: 's4e4',
+        ref: 'e3',
      },
    });

@@ -96,26 +101,50 @@ The tool "browser_file_upload" can only be used when there is related modal stat
  }
 });

-test('clicking on download link emits download', async ({ startClient }, testInfo) => {
-  const outputDir = testInfo.outputPath('output');
+test('clicking on download link emits download', async ({ startClient, localOutputPath, server }) => {
+  const outputDir = localOutputPath('output');
  const client = await startClient({
    config: { outputDir },
  });

+  server.setContent('/', `<a href="/download" download="test.txt">Download</a>`, 'text/html');
+  server.setContent('/download', 'Data', 'text/plain');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- link "Download" [ref=e2]');
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Download link',
+      ref: 'e2',
+    },
+  });
+  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent(`
+### Downloads
+- Downloaded file test.txt to ${path.join(outputDir, 'test.txt')}`);
+});
+
+test('navigating to download link emits download', async ({ startClient, localOutputPath, mcpBrowser, server }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    args: ['--output-dir', outputDir],
+  });
+
+  test.skip(mcpBrowser === 'webkit' && process.platform === 'linux', 'https://github.com/microsoft/playwright/blob/8e08fdb52c27bb75de9bf87627bf740fadab2122/tests/library/download.spec.ts#L436');
+  server.route('/download', (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/plain',
+      'Content-Disposition': 'attachment; filename=test.txt',
+    });
+    res.end('Hello world!');
+  });
+
  expect(await client.callTool({
    name: 'browser_navigate',
    arguments: {
-      url: 'data:text/html,<a href="data:text/plain,Hello world!" download="test.txt">Download</a>',
+      url: server.PREFIX + 'download',
    },
-  })).toContainTextContent('- link "Download" [ref=s1e3]');
-  await client.callTool({
-    name: 'browser_click',
-    arguments: {
-      element: 'Download link',
-      ref: 's1e3',
-    },
-  });
-  await expect.poll(() => client.callTool({ name: 'browser_snapshot', arguments: {} })).toContainTextContent(`
-### Downloads
- Downloaded file test.txt to ${path.join(outputDir, 'test.txt')}`);
+  })).toContainTextContent('### Downloads');
 });
--- a/tests/fixtures.ts
+++ b/tests/fixtures.ts
@@ -22,13 +22,19 @@ import { chromium } from 'playwright';
 import { test as baseTest, expect as baseExpect } from '@playwright/test';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
 import { TestServer } from './testserver/index.ts';

 import type { Config } from '../config';
+import type { BrowserContext } from 'playwright';

 export type TestOptions = {
  mcpBrowser: string | undefined;
+  mcpMode: 'docker' | undefined;
+};
+
+type CDPServer = {
+  endpoint: string;
+  start: () => Promise<BrowserContext>;
 };

 type TestFixtures = {
@@ -36,10 +42,11 @@ type TestFixtures = {
  visionClient: Client;
  startClient: (options?: { clientName?: string, args?: string[], config?: Config }) => Promise<Client>;
  wsEndpoint: string;
-  cdpEndpoint: (port?: number) => Promise<string>;
+  cdpServer: CDPServer;
  server: TestServer;
  httpsServer: TestServer;
  mcpHeadless: boolean;
+  localOutputPath: (filePath: string) => string;
 };

 type WorkerFixtures = {
@@ -56,12 +63,15 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
    await use(await startClient({ args: ['--vision'] }));
  },

-  startClient: async ({ mcpHeadless, mcpBrowser }, use, testInfo) => {
+  startClient: async ({ mcpHeadless, mcpBrowser, mcpMode }, use, testInfo) => {
    const userDataDir = testInfo.outputPath('user-data-dir');
+    const configDir = path.dirname(test.info().config.configFile!);
    let client: Client | undefined;

    await use(async options => {
-      const args = ['--user-data-dir', userDataDir];
+      const args = ['--user-data-dir', path.relative(configDir, userDataDir)];
+      if (process.env.CI && process.platform === 'linux')
+        args.push('--no-sandbox');
      if (mcpHeadless)
        args.push('--headless');
      if (mcpBrowser)
@@ -71,15 +81,11 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
      if (options?.config) {
        const configFile = testInfo.outputPath('config.json');
        await fs.promises.writeFile(configFile, JSON.stringify(options.config, null, 2));
-        args.push(`--config=${configFile}`);
+        args.push(`--config=${path.relative(configDir, configFile)}`);
      }
-      // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
-      const __filename = url.fileURLToPath(import.meta.url);
-      const transport = new StdioClientTransport({
-        command: 'node',
-        args: [path.join(path.dirname(__filename), '../cli.js'), ...args],
-      });
+
      client = new Client({ name: options?.clientName ?? 'test', version: '1.0.0' });
+      const transport = createTransport(args, mcpMode);
      await client.connect(transport);
      await client.ping();
      return client;
@@ -94,34 +100,25 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
    await browserServer.close();
  },

-  cdpEndpoint: async ({ }, use, testInfo) => {
-    let browserProcess: ChildProcessWithoutNullStreams | undefined;
+  cdpServer: async ({ mcpBrowser }, use, testInfo) => {
+    test.skip(!['chrome', 'msedge', 'chromium'].includes(mcpBrowser!), 'CDP is not supported for non-Chromium browsers');

-    await use(async port => {
-      if (!port)
-        port = 3200 + test.info().parallelIndex;
-      if (browserProcess)
-        return `http://localhost:${port}`;
-      browserProcess = spawn(chromium.executablePath(), [
-        `--user-data-dir=${testInfo.outputPath('user-data-dir')}`,
-        `--remote-debugging-port=${port}`,
-        `--no-first-run`,
-        `--no-sandbox`,
-        `--headless`,
-        '--use-mock-keychain',
-        `data:text/html,hello world`,
-      ], {
-        stdio: 'pipe',
-      });
-      await new Promise<void>(resolve => {
-        browserProcess!.stderr.on('data', data => {
-          if (data.toString().includes('DevTools listening on '))
-            resolve();
+    let browserContext: BrowserContext | undefined;
+    const port = 3200 + test.info().parallelIndex;
+    await use({
+      endpoint: `http://localhost:${port}`,
+      start: async () => {
+        browserContext = await chromium.launchPersistentContext(testInfo.outputPath('cdp-user-data-dir'), {
+          channel: mcpBrowser,
+          headless: true,
+          args: [
+            `--remote-debugging-port=${port}`,
+          ],
        });
-      });
-      return `http://localhost:${port}`;
+        return browserContext;
+      }
    });
-    browserProcess?.kill();
+    await browserContext?.close();
  },

  mcpHeadless: async ({ headless }, use) => {
@@ -130,6 +127,15 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(

  mcpBrowser: ['chrome', { option: true }],

+  mcpMode: [undefined, { option: true }],
+
+  localOutputPath: async ({ mcpMode }, use, testInfo) => {
+    await use(filePath => {
+      test.skip(mcpMode === 'docker', 'Mounting files is not supported in docker mode');
+      return testInfo.outputPath(filePath);
+    });
+  },
+
  _workerServers: [async ({}, use, workerInfo) => {
    const port = 8907 + workerInfo.workerIndex * 4;
    const server = await TestServer.create(port);
@@ -156,6 +162,24 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
  },
 });

+function createTransport(args: string[], mcpMode: TestOptions['mcpMode']) {
+  // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+  const __filename = url.fileURLToPath(import.meta.url);
+  if (mcpMode === 'docker') {
+    const dockerArgs = ['run', '--rm', '-i', '--network=host', '-v', `${test.info().project.outputDir}:/app/test-results`];
+    return new StdioClientTransport({
+      command: 'docker',
+      args: [...dockerArgs, 'playwright-mcp-dev:latest', ...args],
+    });
+  }
+  return new StdioClientTransport({
+    command: 'node',
+    args: [path.join(path.dirname(__filename), '../cli.js'), ...args],
+    cwd: path.join(path.dirname(__filename), '..'),
+    env: process.env as Record<string, string>,
+  });
+}
+
 type Response = Awaited<ReturnType<Client['callTool']>>;

 export const expect = baseExpect.extend({
--- a/tests/headed.spec.ts
+++ b/tests/headed.spec.ts
@@ -20,6 +20,7 @@ for (const mcpHeadless of [false, true]) {
  test.describe(`mcpHeadless: ${mcpHeadless}`, () => {
    test.use({ mcpHeadless });
    test.skip(process.platform === 'linux', 'Auto-detection wont let this test run on linux');
+    test.skip(({ mcpMode, mcpHeadless }) => mcpMode === 'docker' && !mcpHeadless, 'Headed mode is not supported in docker');
    test('browser', async ({ client, server, mcpBrowser }) => {
      test.skip(!['chrome', 'msedge', 'chromium'].includes(mcpBrowser ?? ''), 'Only chrome is supported for this test');
      server.route('/', (req, res) => {
--- a/tests/iframes.spec.ts
+++ b/tests/iframes.spec.ts
@@ -24,19 +24,21 @@ test('stitched aria frames', async ({ client }) => {
    },
  })).toContainTextContent(`
 \`\`\`yaml
- heading "Hello" [level=1] [ref=s1e3]
- iframe [ref=s1e4]:
-  - button "World" [ref=f1s1e3]
-  - main [ref=f1s1e4]:
-    - iframe [ref=f1s1e5]:
-      - paragraph [ref=f2s1e3]: Nested
+- generic [ref=e1]:
+  - heading "Hello" [level=1] [ref=e2]
+  - iframe [ref=e3]:
+    - generic [ref=f1e1]:
+      - button "World" [ref=f1e2]
+      - main [ref=f1e3]:
+        - iframe [ref=f1e4]:
+          - paragraph [ref=f2e2]: Nested
 \`\`\``);

  expect(await client.callTool({
    name: 'browser_click',
    arguments: {
      element: 'World',
-      ref: 'f1s1e3',
+      ref: 'f1e2',
    },
  })).toContainTextContent(`// Click World`);
 });
--- a/tests/install.spec.ts
+++ b/tests/install.spec.ts
@@ -20,6 +20,5 @@ test('browser_install', async ({ client, mcpBrowser }) => {
  test.skip(mcpBrowser !== 'chromium', 'Test only chromium');
  expect(await client.callTool({
    name: 'browser_install',
-    arguments: {},
  })).toContainTextContent(`No open pages available.`);
 });
--- a/tests/launch.spec.ts
+++ b/tests/launch.spec.ts
@@ -14,36 +14,122 @@
 * limitations under the License.
 */

+import fs from 'fs';
+
 import { test, expect } from './fixtures.js';

-test('test reopen browser', async ({ client }) => {
+test('test reopen browser', async ({ client, server }) => {
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
  });

  expect(await client.callTool({
    name: 'browser_close',
-    arguments: {},
  })).toContainTextContent('No open pages available');

  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 });

-test('executable path', async ({ startClient }) => {
+test('executable path', async ({ startClient, server }) => {
  const client = await startClient({ args: [`--executable-path=bogus`] });
  const response = await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
  });
  expect(response).toContainTextContent(`executable doesn't exist`);
 });
+
+test('persistent context', async ({ startClient, server }) => {
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = localStorage.getItem('test') ? 'Storage: YES' : 'Storage: NO';
+      localStorage.setItem('test', 'test');
+    </script>
+  `, 'text/html');
+
+  const client = await startClient();
+  const response = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: NO`);
+
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  await client.callTool({
+    name: 'browser_close',
+  });
+
+  const client2 = await startClient();
+  const response2 = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(response2).toContainTextContent(`Storage: YES`);
+});
+
+test('isolated context', async ({ startClient, server }) => {
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = localStorage.getItem('test') ? 'Storage: YES' : 'Storage: NO';
+      localStorage.setItem('test', 'test');
+    </script>
+  `, 'text/html');
+
+  const client = await startClient({ args: [`--isolated`] });
+  const response = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: NO`);
+
+  await client.callTool({
+    name: 'browser_close',
+  });
+
+  const client2 = await startClient({ args: [`--isolated`] });
+  const response2 = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response2).toContainTextContent(`Storage: NO`);
+});
+
+test('isolated context with storage state', async ({ startClient, server, localOutputPath }) => {
+  const storageStatePath = localOutputPath('storage-state.json');
+  await fs.promises.writeFile(storageStatePath, JSON.stringify({
+    origins: [
+      {
+        origin: server.PREFIX,
+        localStorage: [{ name: 'test', value: 'session-value' }],
+      },
+    ],
+  }));
+
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = 'Storage: ' + localStorage.getItem('test');
+    </script>
+  `, 'text/html');
+
+  const client = await startClient({ args: [
+    `--isolated`,
+    `--storage-state=${storageStatePath}`,
+  ] });
+  const response = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: session-value`);
+});
--- a/tests/network.spec.ts
+++ b/tests/network.spec.ts
@@ -17,15 +17,11 @@
 import { test, expect } from './fixtures.js';

 test('browser_network_requests', async ({ client, server }) => {
-  server.route('/', (req, res) => {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end(`<button onclick="fetch('/json')">Click me</button>`);
-  });
+  server.setContent('/', `
+    <button onclick="fetch('/json')">Click me</button>
+  `, 'text/html');

-  server.route('/json', (req, res) => {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ name: 'John Doe' }));
-  });
+  server.setContent('/json', JSON.stringify({ name: 'John Doe' }), 'application/json');

  await client.callTool({
    name: 'browser_navigate',
@@ -38,12 +34,12 @@ test('browser_network_requests', async ({ client, server }) => {
    name: 'browser_click',
    arguments: {
      element: 'Click me button',
-      ref: 's1e3',
+      ref: 'e2',
    },
  });

  await expect.poll(() => client.callTool({
    name: 'browser_network_requests',
-    arguments: {},
-  })).toHaveTextContent(`[GET] http://localhost:${server.PORT}/json => [200] OK`);
+  })).toHaveTextContent(`[GET] ${`${server.PREFIX}`} => [200] OK
+[GET] ${`${server.PREFIX}json`} => [200] OK`);
 });
--- a/tests/pdf.spec.ts
+++ b/tests/pdf.spec.ts
@@ -14,15 +14,15 @@
 * limitations under the License.
 */

+import fs from 'fs';
+
 import { test, expect } from './fixtures.js';

-test('save as pdf unavailable', async ({ startClient }) => {
+test('save as pdf unavailable', async ({ startClient, server }) => {
  const client = await startClient({ args: ['--caps="no-pdf"'] });
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
  });

  expect(await client.callTool({
@@ -30,18 +30,55 @@ test('save as pdf unavailable', async ({ startClient }) => {
  })).toHaveTextContent(/Tool \"browser_pdf_save\" not found/);
 });

-test('save as pdf', async ({ client, mcpBrowser }) => {
+test('save as pdf', async ({ startClient, mcpBrowser, server, localOutputPath }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    config: { outputDir },
+  });
+
  test.skip(!!mcpBrowser && !['chromium', 'chrome', 'msedge'].includes(mcpBrowser), 'Save as PDF is only supported in Chromium.');
+
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);

  const response = await client.callTool({
    name: 'browser_pdf_save',
-    arguments: {},
  });
  expect(response).toHaveTextContent(/Save page as.*page-[^:]+.pdf/);
 });
+
+test('save as pdf (filename: output.pdf)', async ({ startClient, mcpBrowser, server, localOutputPath }) => {
+  test.skip(!!mcpBrowser && !['chromium', 'chrome', 'msedge'].includes(mcpBrowser), 'Save as PDF is only supported in Chromium.');
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    config: { outputDir },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
+
+  expect(await client.callTool({
+    name: 'browser_pdf_save',
+    arguments: {
+      filename: 'output.pdf',
+    },
+  })).toEqual({
+    content: [
+      {
+        type: 'text',
+        text: expect.stringContaining(`output.pdf`),
+      },
+    ],
+  });
+
+  const files = [...fs.readdirSync(outputDir)];
+
+  expect(fs.existsSync(outputDir)).toBeTruthy();
+  const pdfFiles = files.filter(f => f.endsWith('.pdf'));
+  expect(pdfFiles).toHaveLength(1);
+  expect(pdfFiles[0]).toMatch(/^output.pdf$/);
+});
--- a/tests/request-blocking.spec.ts
+++ b/tests/request-blocking.spec.ts
@@ -31,11 +31,8 @@ const fetchPage = async (client: Client, url: string) => {
 };

 test('default to allow all', async ({ server, client }) => {
-  server.route('/ppp', (_req, res) => {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end('content:PPP');
-  });
-  const result = await fetchPage(client, server.PREFIX + '/ppp');
+  server.setContent('/ppp', 'content:PPP', 'text/html');
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
  expect(result).toContain('content:PPP');
 });

@@ -48,14 +45,11 @@ test('blocked works', async ({ startClient }) => {
 });

 test('allowed works', async ({ server, startClient }) => {
-  server.route('/ppp', (_req, res) => {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end('content:PPP');
-  });
+  server.setContent('/ppp', 'content:PPP', 'text/html');
  const client = await startClient({
    args: ['--allowed-origins', `microsoft.com;${new URL(server.PREFIX).host};playwright.dev`]
  });
-  const result = await fetchPage(client, server.PREFIX + '/ppp');
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
  expect(result).toContain('content:PPP');
 });

@@ -79,13 +73,10 @@ test('allowed without blocked blocks all non-explicitly specified origins', asyn
 });

 test('blocked without allowed allows non-explicitly specified origins', async ({ server, startClient }) => {
-  server.route('/ppp', (_req, res) => {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end('content:PPP');
-  });
+  server.setContent('/ppp', 'content:PPP', 'text/html');
  const client = await startClient({
    args: ['--blocked-origins', 'example.com'],
  });
-  const result = await fetchPage(client, server.PREFIX + '/ppp');
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
  expect(result).toContain('content:PPP');
 });
--- a/tests/screenshot.spec.ts
+++ b/tests/screenshot.spec.ts
@@ -18,17 +18,18 @@ import fs from 'fs';

 import { test, expect } from './fixtures.js';

-test('browser_take_screenshot (viewport)', async ({ client }) => {
+test('browser_take_screenshot (viewport)', async ({ startClient, server, localOutputPath }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    args: ['--output-dir', outputDir],
+  });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);

  expect(await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  })).toEqual({
    content: [
      {
@@ -44,19 +45,21 @@ test('browser_take_screenshot (viewport)', async ({ client }) => {
  });
 });

-test('browser_take_screenshot (element)', async ({ client }) => {
+test('browser_take_screenshot (element)', async ({ startClient, server, localOutputPath }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    args: ['--output-dir', outputDir],
+  });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button>Hello, world!</button></html>',
-    },
-  })).toContainTextContent(`[ref=s1e3]`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`[ref=e1]`);

  expect(await client.callTool({
    name: 'browser_take_screenshot',
    arguments: {
      element: 'hello button',
-      ref: 's1e3',
+      ref: 'e1',
    },
  })).toEqual({
    content: [
@@ -66,78 +69,130 @@ test('browser_take_screenshot (element)', async ({ client }) => {
        type: 'image',
      },
      {
-        text: expect.stringContaining(`page.getByRole('button', { name: 'Hello, world!' }).screenshot`),
+        text: expect.stringContaining(`page.getByText('Hello, world!').screenshot`),
        type: 'text',
      },
    ],
  });
 });

-test('--output-dir should work', async ({ startClient }, testInfo) => {
-  const outputDir = testInfo.outputPath('output');
+test('--output-dir should work', async ({ startClient, localOutputPath, server }) => {
+  const outputDir = localOutputPath('output');
  const client = await startClient({
    args: ['--output-dir', outputDir],
  });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);

  await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  });

  expect(fs.existsSync(outputDir)).toBeTruthy();
-  expect([...fs.readdirSync(outputDir)]).toHaveLength(1);
+  const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith('.jpeg'));
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^page-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.jpeg$/);
 });

+for (const raw of [undefined, true]) {
+  test(`browser_take_screenshot (raw: ${raw})`, async ({ startClient, localOutputPath, server }) => {
+    const ext = raw ? 'png' : 'jpeg';
+    const outputDir = localOutputPath('output');
+    const client = await startClient({
+      config: { outputDir },
+    });
+    expect(await client.callTool({
+      name: 'browser_navigate',
+      arguments: { url: server.PREFIX },
+    })).toContainTextContent(`Navigate to http://localhost`);

-test('browser_take_screenshot (outputDir)', async ({ startClient }, testInfo) => {
-  const outputDir = testInfo.outputPath('output');
+    expect(await client.callTool({
+      name: 'browser_take_screenshot',
+      arguments: { raw },
+    })).toEqual({
+      content: [
+        {
+          data: expect.any(String),
+          mimeType: `image/${ext}`,
+          type: 'image',
+        },
+        {
+          text: expect.stringMatching(
+              new RegExp(`page-\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}\\-\\d{3}Z\\.${ext}`)
+          ),
+          type: 'text',
+        },
+      ],
+    });
+
+    const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith(`.${ext}`));
+
+    expect(fs.existsSync(outputDir)).toBeTruthy();
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatch(
+        new RegExp(`^page-\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-\\d{3}Z\\.${ext}$`)
+    );
+  });
+
+}
+
+test('browser_take_screenshot (filename: "output.jpeg")', async ({ startClient, localOutputPath, server }) => {
+  const outputDir = localOutputPath('output');
  const client = await startClient({
    config: { outputDir },
  });
  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);

-  await client.callTool({
+  expect(await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
+    arguments: {
+      filename: 'output.jpeg',
+    },
+  })).toEqual({
+    content: [
+      {
+        data: expect.any(String),
+        mimeType: 'image/jpeg',
+        type: 'image',
+      },
+      {
+        text: expect.stringContaining(`output.jpeg`),
+        type: 'text',
+      },
+    ],
  });

+  const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith('.jpeg'));
+
  expect(fs.existsSync(outputDir)).toBeTruthy();
-  expect([...fs.readdirSync(outputDir)]).toHaveLength(1);
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^output\.jpeg$/);
 });

-test('browser_take_screenshot (noImageResponses)', async ({ startClient }) => {
+test('browser_take_screenshot (noImageResponses)', async ({ startClient, server, localOutputPath }) => {
  const client = await startClient({
    config: {
+      outputDir: localOutputPath('output'),
      noImageResponses: true,
    },
  });

  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);

  await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  });

  expect(await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  })).toEqual({
    content: [
      {
@@ -148,24 +203,24 @@ test('browser_take_screenshot (noImageResponses)', async ({ startClient }) => {
  });
 });

-test('browser_take_screenshot (cursor)', async ({ startClient }) => {
-  const client = await startClient({ clientName: 'cursor:vscode' });
+test('browser_take_screenshot (cursor)', async ({ startClient, server, localOutputPath }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    clientName: 'cursor:vscode',
+    config: { outputDir },
+  });

  expect(await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);

  await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  });

  expect(await client.callTool({
    name: 'browser_take_screenshot',
-    arguments: {},
  })).toEqual({
    content: [
      {
--- a/tests/sse.spec.ts
+++ b/tests/sse.spec.ts
@@ -15,10 +15,18 @@
 */

 import url from 'node:url';
+import http from 'node:http';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
-import { test as baseTest } from './fixtures.js';
-import { expect } from 'playwright/test';
+import type { AddressInfo } from 'node:net';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+import { createConnection } from '@playwright/mcp';
+
+import { test as baseTest, expect } from './fixtures.js';

 // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
 const __filename = url.fileURLToPath(import.meta.url);
@@ -27,10 +35,10 @@ const test = baseTest.extend<{ serverEndpoint: string }>({
  serverEndpoint: async ({}, use) => {
    const cp = spawn('node', [path.join(path.dirname(__filename), '../cli.js'), '--port', '0'], { stdio: 'pipe' });
    try {
-      let stdout = '';
-      const url = await new Promise<string>(resolve => cp.stdout?.on('data', data => {
-        stdout += data.toString();
-        const match = stdout.match(/Listening on (http:\/\/.*)/);
+      let stderr = '';
+      const url = await new Promise<string>(resolve => cp.stderr?.on('data', data => {
+        stderr += data.toString();
+        const match = stderr.match(/Listening on (http:\/\/.*)/);
        if (match)
          resolve(match[1]);
      }));
@@ -43,9 +51,6 @@ const test = baseTest.extend<{ serverEndpoint: string }>({
 });

 test('sse transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
  const transport = new SSEClientTransport(new URL(serverEndpoint));
  const client = new Client({ name: 'test', version: '1.0.0' });
  await client.connect(transport);
@@ -53,12 +58,52 @@ test('sse transport', async ({ serverEndpoint }) => {
 });

 test('streamable http transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
  const transport = new StreamableHTTPClientTransport(new URL('/mcp', serverEndpoint));
  const client = new Client({ name: 'test', version: '1.0.0' });
  await client.connect(transport);
  await client.ping();
  expect(transport.sessionId, 'has session support').toBeDefined();
 });
+
+test('sse transport via public API', async ({ server, localOutputPath }) => {
+  const userDataDir = localOutputPath('user-data-dir');
+  const sessions = new Map<string, SSEServerTransport>();
+  const mcpServer = http.createServer(async (req, res) => {
+    if (req.method === 'GET') {
+      const connection = await createConnection({
+        browser: {
+          userDataDir,
+          launchOptions: { headless: true }
+        },
+      });
+      const transport = new SSEServerTransport('/sse', res);
+      sessions.set(transport.sessionId, transport);
+      await connection.connect(transport);
+    } else if (req.method === 'POST') {
+      const url = new URL(`http://localhost${req.url}`);
+      const sessionId = url.searchParams.get('sessionId');
+      if (!sessionId) {
+        res.statusCode = 400;
+        return res.end('Missing sessionId');
+      }
+      const transport = sessions.get(sessionId);
+      if (!transport) {
+        res.statusCode = 404;
+        return res.end('Session not found');
+      }
+      void transport.handlePostMessage(req, res);
+    }
+  });
+  await new Promise<void>(resolve => mcpServer.listen(0, () => resolve()));
+  const serverUrl = `http://localhost:${(mcpServer.address() as AddressInfo).port}/sse`;
+  const transport = new SSEClientTransport(new URL(serverUrl));
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
+  await client.close();
+  mcpServer.close();
+});
--- a/tests/tabs.spec.ts
+++ b/tests/tabs.spec.ts
@@ -14,8 +14,6 @@
 * limitations under the License.
 */

-import { chromium } from 'playwright';
-
 import { test, expect } from './fixtures.js';

 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -32,7 +30,6 @@ async function createTab(client: Client, title: string, body: string) {
 test('list initial tabs', async ({ client }) => {
  expect(await client.callTool({
    name: 'browser_tab_list',
-    arguments: {},
  })).toHaveTextContent(`### Open tabs
 - 1: (current) [] (about:blank)`);
 });
@@ -41,7 +38,6 @@ test('list first tab', async ({ client }) => {
  await createTab(client, 'Tab one', 'Body one');
  expect(await client.callTool({
    name: 'browser_tab_list',
-    arguments: {},
  })).toHaveTextContent(`### Open tabs
 - 1: [] (about:blank)
 - 2: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`);
@@ -63,7 +59,7 @@ test('create new tab', async ({ client }) => {
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s1e2]: Body one
+- generic [ref=e1]: Body one
 \`\`\``);

  expect(await createTab(client, 'Tab two', 'Body two')).toHaveTextContent(`
@@ -82,7 +78,7 @@ test('create new tab', async ({ client }) => {
 - Page Title: Tab two
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s1e2]: Body two
+- generic [ref=e1]: Body two
 \`\`\``);
 });

@@ -110,7 +106,7 @@ test('select tab', async ({ client }) => {
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s2e2]: Body one
+- generic [ref=e1]: Body one
 \`\`\``);
 });

@@ -137,21 +133,18 @@ test('close tab', async ({ client }) => {
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
- generic [ref=s2e2]: Body one
+- generic [ref=e1]: Body one
 \`\`\``);
 });

-test('reuse first tab when navigating', async ({ startClient, cdpEndpoint }) => {
-  const browser = await chromium.connectOverCDP(await cdpEndpoint());
-  const [context] = browser.contexts();
-  const pages = context.pages();
+test('reuse first tab when navigating', async ({ startClient, cdpServer, server }) => {
+  const browserContext = await cdpServer.start();
+  const pages = browserContext.pages();

-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+  const client = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
  await client.callTool({
    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<title>Title</title><body>Body</body>',
-    },
+    arguments: { url: server.HELLO_WORLD },
  });

  expect(pages.length).toBe(1);
--- a/tests/testserver/index.ts
+++ b/tests/testserver/index.ts
@@ -38,6 +38,7 @@ export class TestServer {
  readonly PORT: number;
  readonly PREFIX: string;
  readonly CROSS_PROCESS_PREFIX: string;
+  readonly HELLO_WORLD: string;

  static async create(port: number): Promise<TestServer> {
    const server = new TestServer(port);
@@ -67,8 +68,9 @@ export class TestServer {
    const same_origin = 'localhost';
    const protocol = sslOptions ? 'https' : 'http';
    this.PORT = port;
-    this.PREFIX = `${protocol}://${same_origin}:${port}`;
-    this.CROSS_PROCESS_PREFIX = `${protocol}://${cross_origin}:${port}`;
+    this.PREFIX = `${protocol}://${same_origin}:${port}/`;
+    this.CROSS_PROCESS_PREFIX = `${protocol}://${cross_origin}:${port}/`;
+    this.HELLO_WORLD = `${this.PREFIX}hello-world`;
  }

  setCSP(path: string, csp: string) {
@@ -88,6 +90,13 @@ export class TestServer {
    this._routes.set(path, handler);
  }

+  setContent(path: string, content: string, mimeType: string) {
+    this.route(path, (req, res) => {
+      res.writeHead(200, { 'Content-Type': mimeType });
+      res.end(mimeType === 'text/html' ? `<!DOCTYPE html>${content}` : content);
+    });
+  }
+
  redirect(from: string, to: string) {
    this.route(from, (req, res) => {
      const headers = this._extraHeaders.get(req.url!) || {};
@@ -120,6 +129,15 @@ export class TestServer {
    for (const subscriber of this._requestSubscribers.values())
      subscriber[rejectSymbol].call(null, error);
    this._requestSubscribers.clear();
+
+    this.setContent('/favicon.ico', '', 'image/x-icon');
+
+    this.setContent('/', ``, 'text/html');
+
+    this.setContent('/hello-world', `
+      <title>Title</title>
+      <body>Hello, world!</body>
+    `, 'text/html');
  }

  _onRequest(request: http.IncomingMessage, response: http.ServerResponse) {
@@ -144,7 +162,11 @@ export class TestServer {
      this._requestSubscribers.delete(path);
    }
    const handler = this._routes.get(path);
-    if (handler)
+    if (handler) {
      handler.call(null, request, response);
+    } else {
+      response.writeHead(404);
+      response.end();
+    }
  }
 }
--- a/tests/trace.spec.ts
+++ b/tests/trace.spec.ts
@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { test, expect } from './fixtures.js';
+
+test('check that trace is saved', async ({ startClient, server, localOutputPath }) => {
+  const outputDir = localOutputPath('output');
+  const client = await startClient({
+    args: ['--save-trace', `--output-dir=${outputDir}`],
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  expect(fs.existsSync(path.join(outputDir, 'traces', 'trace.trace'))).toBeTruthy();
+});
--- a/tests/wait.spec.ts
+++ b/tests/wait.spec.ts
@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test, expect } from './fixtures.js';
+
+test('browser_wait_for(text)', async ({ client, server }) => {
+  server.setContent('/', `
+    <script>
+      function update() {
+        setTimeout(() => {
+          document.querySelector('div').textContent = 'Text to appear';
+        }, 1000);
+      }
+    </script>
+    <body>
+      <button onclick="update()">Click me</button>
+      <div>Text to disappear</div>
+    </body>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_wait_for',
+    arguments: { text: 'Text to appear' },
+  })).toContainTextContent(`- generic [ref=e3]: Text to appear`);
+});
+
+test('browser_wait_for(textGone)', async ({ client, server }) => {
+  server.setContent('/', `
+    <script>
+      function update() {
+        setTimeout(() => {
+          document.querySelector('div').textContent = 'Text to appear';
+        }, 1000);
+      }
+    </script>
+    <body>
+      <button onclick="update()">Click me</button>
+      <div>Text to disappear</div>
+    </body>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_wait_for',
+    arguments: { textGone: 'Text to disappear' },
+  })).toContainTextContent(`- generic [ref=e3]: Text to appear`);
+});
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,7 +1,6 @@
 {
  "compilerOptions": {
    "target": "ESNext",
-    "skipLibCheck": true,
    "esModuleInterop": true,
    "moduleResolution": "nodenext",
    "strict": true,
--- a/utils/update-readme.js
+++ b/utils/update-readme.js
@@ -32,65 +32,67 @@ import networkTools from '../lib/tools/network.js';
 import pdfTools from '../lib/tools/pdf.js';
 import snapshotTools from '../lib/tools/snapshot.js';
 import tabsTools from '../lib/tools/tabs.js';
-import screenTools from '../lib/tools/screen.js';
+import screenshotTools from '../lib/tools/screenshot.js';
 import testTools from '../lib/tools/testing.js';
+import visionTools from '../lib/tools/vision.js';
+import waitTools from '../lib/tools/wait.js';
+import { execSync } from 'node:child_process';

-// Category definitions for tools
 const categories = {
-  'Snapshot-based Interactions': [
+  'Interactions': [
    ...snapshotTools,
-  ],
-  'Vision-based Interactions': [
-    ...screenTools
-  ],
-  'Tab Management': [
-    ...tabsTools(true),
+    ...keyboardTools(true),
+    ...waitTools(true),
+    ...filesTools(true),
+    ...dialogsTools(true),
  ],
  'Navigation': [
    ...navigateTools(true),
  ],
-  'Keyboard': [
-    ...keyboardTools(true)
-  ],
-  'Console': [
-    ...consoleTools
-  ],
-  'Files and Media': [
-    ...filesTools(true),
-    ...pdfTools
+  'Resources': [
+    ...screenshotTools,
+    ...pdfTools,
+    ...networkTools,
+    ...consoleTools,
  ],
  'Utilities': [
-    ...commonTools(true),
    ...installTools,
-    ...dialogsTools(true),
-    ...networkTools,
+    ...commonTools(true),
+  ],
+  'Tabs': [
+    ...tabsTools(true),
  ],
  'Testing': [
    ...testTools,
  ],
+  'Vision mode': [
+    ...visionTools,
+    ...keyboardTools(),
+    ...waitTools(false),
+    ...filesTools(false),
+    ...dialogsTools(false),
+  ],
 };

 // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
 const __filename = url.fileURLToPath(import.meta.url);

-const kStartMarker = `<!--- Generated by ${path.basename(__filename)} -->`;
-const kEndMarker = `<!--- End of generated section -->`;
-
 /**
 * @param {import('../src/tools/tool.js').ToolSchema<any>} tool 
- * @returns {string}
+ * @returns {string[]}
 */
 function formatToolForReadme(tool) {
  const lines = /** @type {string[]} */ ([]);
-  lines.push(`<!-- NOTE: This has been generated via ${path.basename(__filename)} -->\n\n`);
-  lines.push(`- **${tool.name}**\n`);
-  lines.push(`  - Title: ${tool.title}\n`);
-  lines.push(`  - Description: ${tool.description}\n`);
+  lines.push(`<!-- NOTE: This has been generated via ${path.basename(__filename)} -->`);
+  lines.push(``);
+  lines.push(`- **${tool.name}**`);
+  lines.push(`  - Title: ${tool.title}`);
+  lines.push(`  - Description: ${tool.description}`);

  const inputSchema = /** @type {any} */ (zodToJsonSchema(tool.inputSchema || {}));
  const requiredParams = inputSchema.required || [];
  if (inputSchema.properties && Object.keys(inputSchema.properties).length) {
-    lines.push(`  - Parameters:\n`);
+    lines.push(`  - Parameters:`);
    Object.entries(inputSchema.properties).forEach(([name, param]) => {
      const optional = !requiredParams.includes(name);
      const meta = /** @type {string[]} */ ([]);
@@ -98,52 +100,94 @@ function formatToolForReadme(tool) {
        meta.push(param.type);
      if (optional)
        meta.push('optional');
-      lines.push(`    - \`${name}\` ${meta.length ? `(${meta.join(', ')})` : ''}: ${param.description}\n`);
+      lines.push(`    - \`${name}\` ${meta.length ? `(${meta.join(', ')})` : ''}: ${param.description}`);
    });
  } else {
-    lines.push(`  - Parameters: None\n`);
+    lines.push(`  - Parameters: None`);
  }
-  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**\n`);
-  lines.push('\n');
-  return lines.join('');
+  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**`);
+  lines.push('');
+  return lines;
 }

-async function updateReadme() {
+/**
+ * @param {string} content
+ * @param {string} startMarker
+ * @param {string} endMarker
+ * @param {string[]} generatedLines
+ * @returns {Promise<string>}
+ */
+async function updateSection(content, startMarker, endMarker, generatedLines) {
+  const startMarkerIndex = content.indexOf(startMarker);
+  const endMarkerIndex = content.indexOf(endMarker);
+  if (startMarkerIndex === -1 || endMarkerIndex === -1)
+    throw new Error('Markers for generated section not found in README');
+
+  return [
+    content.slice(0, startMarkerIndex + startMarker.length),
+    '',
+    generatedLines.join('\n'),
+    '',
+    content.slice(endMarkerIndex),
+  ].join('\n');
+}
+
+/**
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+async function updateTools(content) {
  console.log('Loading tool information from compiled modules...');

-  // Count the tools processed
  const totalTools = Object.values(categories).flat().length;
  console.log(`Found ${totalTools} tools`);

  const generatedLines = /** @type {string[]} */ ([]);
-
  for (const [category, categoryTools] of Object.entries(categories)) {
-    generatedLines.push(`### ${category}\n\n`);
+    generatedLines.push(`<details>\n<summary><b>${category}</b></summary>`);
+    generatedLines.push('');
    for (const tool of categoryTools)
-      generatedLines.push(formatToolForReadme(tool.schema));
+      generatedLines.push(...formatToolForReadme(tool.schema));
+    generatedLines.push(`</details>`);
+    generatedLines.push('');
  }

+  const startMarker = `<!--- Tools generated by ${path.basename(__filename)} -->`;
+  const endMarker = `<!--- End of tools generated section -->`;
+  return updateSection(content, startMarker, endMarker, generatedLines);
+}
+
+/**
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+async function updateOptions(content) {
+  console.log('Listing options...');
+  const output = execSync('node cli.js --help');
+  const lines = output.toString().split('\n');
+  const firstLine = lines.findIndex(line => line.includes('--version'));
+  lines.splice(0, firstLine + 1);
+  const lastLine = lines.findIndex(line => line.includes('--help'));
+  lines.splice(lastLine);
+  const startMarker = `<!--- Options generated by ${path.basename(__filename)} -->`;
+  const endMarker = `<!--- End of options generated section -->`;
+  return updateSection(content, startMarker, endMarker, [
+    '```',
+    '> npx @playwright/mcp@latest --help',
+    ...lines,
+    '```',
+  ]);
+}
+
+async function updateReadme() {
  const readmePath = path.join(path.dirname(__filename), '..', 'README.md');
  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');
-  const startMarker = readmeContent.indexOf(kStartMarker);
-  const endMarker = readmeContent.indexOf(kEndMarker);
-  if (startMarker === -1 || endMarker === -1)
-    throw new Error('Markers for generated section not found in README');
-
-  const newReadmeContent = [
-    readmeContent.slice(0, startMarker),
-    kStartMarker + '\n\n',
-    generatedLines.join(''),
-    kEndMarker,
-    readmeContent.slice(endMarker + kEndMarker.length),
-  ].join('');
-
-  // Write updated README
-  await fs.promises.writeFile(readmePath, newReadmeContent, 'utf-8');
+  const withTools = await updateTools(readmeContent);
+  const withOptions = await updateOptions(withTools);
+  await fs.promises.writeFile(readmePath, withOptions, 'utf-8');
  console.log('README updated successfully');
 }

-// Run the update
 updateReadme().catch(err => {
  console.error('Error updating README:', err);
  process.exit(1);
Author	SHA1	Message	Date
Pavel Feldman	c318f13895	chore: mark v0.0.26 (#441 )	2025-05-17 08:20:37 -07:00
Pavel Feldman	1318e39fac	chore: fix operation over cdp (#440 ) Ref https://github.com/microsoft/playwright-mcp/issues/439	2025-05-17 08:20:22 -07:00
Pavel Feldman	c2b7fb29de	chore: start trace server (#427 )	2025-05-14 20:15:09 -07:00
Pavel Feldman	aa6ac51f92	feat(trace): allow saving trajectory as trace (#426 )	2025-05-14 18:08:44 -07:00
Pavel Feldman	fea50e6840	chore: introduce resolved config (#425 )	2025-05-14 16:01:08 -07:00
Pavel Feldman	746c9fc124	chore: mark v0.0.25 (#414 )	2025-05-13 16:24:04 -07:00
Pavel Feldman	ee33097abe	chore: normalize --no- options (#413 )	2025-05-13 16:17:45 -07:00
Pavel Feldman	ab20175826	chore: generate readme options (#411 )	2025-05-13 15:52:30 -07:00
Pavel Feldman	c506027aec	chore: run w/ sandbox by default (#412 )	2025-05-13 15:30:02 -07:00
Pavel Feldman	7be0c8872e	feat(args): allow configuring proxy, UA, viewport, https errors (#410 )	2025-05-13 14:40:03 -07:00
Pavel Feldman	ce72367208	feat(storage): allow passing storage state for isolated contexts (#409 ) Fixes https://github.com/microsoft/playwright-mcp/issues/403 Ref https://github.com/microsoft/playwright-mcp/issues/367	2025-05-13 13:14:04 -07:00
Pavel Feldman	949f956378	feat(ephemeral): allow for non-persistent context operation (#405 ) Ref: https://github.com/microsoft/playwright-mcp/issues/367 Ref: https://github.com/microsoft/playwright-mcp/issues/393	2025-05-12 18:18:53 -07:00
Pavel Feldman	a1eee8351e	chore: collapse readme (#404 )	2025-05-12 16:42:47 -07:00
Pavel Feldman	fea3f26e85	chore: mark v0.0.24 (#401 )	2025-05-12 09:40:59 -07:00
Pavel Feldman	dd5b41f1d8	chore: account for undefined arguments (#400 )	2025-05-12 09:35:33 -07:00
Pavel Feldman	05dc5d915b	chore: mark v0.0.23 (#399 )	2025-05-12 09:13:48 -07:00
Taiga Mikami	65a229c79f	Fix import in README from createServer to createConnection (#396 ) Probably, `createServer` is not from `@playwright/mcp`.	2025-05-12 08:46:21 -07:00
Max Schmitt	84664d4b09	test: unflake 'should throw connection error and allow re-connecting' (#398 ) Fixes https://github.com/microsoft/playwright-mcp/actions/runs/14940263450/job/41976152764#step:8:315	2025-05-12 09:45:09 +02:00
Pavel Feldman	445170a76b	chore: roll playwright 5/9 (#394 )	2025-05-09 18:01:17 -07:00
Pavel Feldman	c28b480b51	feat(wait): allow waiting for given text (#390 ) Fixes https://github.com/microsoft/playwright-mcp/issues/389	2025-05-09 15:35:28 -07:00
Max Schmitt	65716b60dd	fix: createConnection() via public API (#384 ) Fixes https://github.com/microsoft/playwright-mcp/issues/382	2025-05-09 21:50:38 +02:00
Max Schmitt	75f74a54bc	docs: reference to new Docker image (#380 )	2025-05-09 21:01:10 +02:00
Max Schmitt	ef41c626ef	chore: unset skipLibCheck in tsconfig.json (#386 ) Follow-up for https://github.com/microsoft/playwright-mcp/pull/385#discussion_r2081541865. > `skipLibCheck`: Skip type checking all .d.ts files.	2025-05-09 14:35:09 +02:00
Max Schmitt	95ca08fdb7	fix: use of wrong launchOptions type in public API (#385 )	2025-05-09 14:16:04 +02:00
Max Schmitt	053c2f3d32	test: fix SSE MCP SDK imports (#383 )	2025-05-09 14:08:19 +02:00
Pavel Feldman	57b3c14276	chore: only reset network log upon explicit navigation (#377 ) Fixes https://github.com/microsoft/playwright-mcp/issues/376	2025-05-08 17:02:09 -07:00
おがどら	85c85bd2fb	chore: support custom filename in screenshot function (#349 )	2025-05-08 11:04:18 -07:00
Max Schmitt	09ba7989c3	test: run tests on MCP server inside Docker (#361 ) https://github.com/microsoft/playwright-mcp/issues/346	2025-05-07 18:04:20 +02:00
Max Schmitt	a115c31953	chore: rename console to consoleMessages (#372 ) Motivation: `console` is a global object in Node.js and having a method like that confuses intellisense.	2025-05-07 16:40:08 +02:00
Max Schmitt	b5be37e5e7	chore: mark v0.0.22 (#370 )	2025-05-07 12:49:11 +02:00
Simon Knott	c2255246a3	fix: don't error on navigating to a download link (#328 )	2025-05-07 12:47:45 +02:00
Max Schmitt	950d0d1d34	devops: fix Docker publishing (#369 )	2025-05-07 11:46:33 +02:00