v1.59.0

## 🎬 Screencast

New [page.screencast](https://playwright.dev/docs/api/class-page#page-screencast) API provides a unified interface for capturing page content with:
- Screencast recordings
- Action annotations
- Visual overlays
- Real-time frame capture
- Agentic video receipts

<center>

<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-screencast-demo.gif" alt="Demo" width="500" height="313" />

</center>

**Screencast recording** — record video with precise start/stop control, as an alternative to the [`recordVideo`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-video) option:

```js
await page.screencast.start({ path: 'video.webm' });
// ... perform actions ...
await page.screencast.stop();
```

**Action annotations** — enable built-in visual annotations that highlight interacted elements and display action titles during recording:

```js
await page.screencast.showActions({ position: 'top-right' });
```

[screencast.showActions()](https://playwright.dev/docs/api/class-screencast#screencast-show-actions) accepts `position` (`'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'`), `duration` (ms per annotation), and `fontSize` (px). Returns a disposable to stop showing actions.

Action annotations can also be enabled in test fixtures via the `video` option:

```js
// playwright.config.ts
export default defineConfig({
  use: {
    video: {
      mode: 'on',
      show: {
        actions: { position: 'top-left' },
        test: { position: 'top-right' },
      },
    },
  },
});
```

**Visual overlays** — add chapter titles and custom HTML overlays on top of the page for richer narration:

```js
await page.screencast.showChapter('Adding TODOs', {
  description: 'Type and press enter for each TODO',
  duration: 1000,
});

await page.screencast.showOverlay('<div style="color: red">Recording</div>');
```

**Real-time frame capture** — stream JPEG-encoded frames for custom processing like thumbnails, live previews, AI vision, and more:

```js
await page.screencast.start({
  onFrame: ({ data }) => sendToVisionModel(data),
  size: { width: 800, height: 600 },
});
```

**Agentic video receipts** — coding agents can produce video evidence of their work. After completing a task, an agent can record a walkthrough video with rich annotations for human review:

```js
await page.screencast.start({ path: 'receipt.webm' });
await page.screencast.showActions({ position: 'top-right' });

await page.screencast.showChapter('Verifying checkout flow', {
  description: 'Added coupon code support per ticket #1234',
});

// Agent performs the verification steps...
await page.locator('#coupon').fill('SAVE20');
await page.locator('#apply-coupon').click();
await expect(page.locator('.discount')).toContainText('20%');

await page.screencast.showChapter('Done', {
  description: 'Coupon applied, discount reflected in total',
});

await page.screencast.stop();
```

The resulting video serves as a receipt: chapter titles provide context, action annotations highlight each interaction, and the visual walkthrough is faster to review than text logs.

## 🔗 Interoperability

New [browser.bind()](https://playwright.dev/docs/api/class-browser#browser-bind) API makes a launched browser available for `playwright-cli`, `@playwright/mcp`, and other clients to connect to.

**Bind a browser** — start a browser and bind it so others can connect:

```js
const { endpoint } = await browser.bind('my-session', {
  workspaceDir: '/my/project',
});
```

**Connect from playwright-cli** — connect to the running browser from your favorite coding agent.

```bash
playwright-cli attach my-session
playwright-cli -s my-session snapshot
```

**Connect from @playwright/mcp** — or point your MCP server to the running browser.

```bash
@playwright/mcp --endpoint=my-session
```

**Connect from a Playwright client** — use API to connect to the browser. Multiple clients at a time are supported!

```js
const browser = await chromium.connect(endpoint);
```

Pass `host` and `port` options to bind over WebSocket instead of a named pipe:

```js
const { endpoint } = await browser.bind('my-session', {
  host: 'localhost',
  port: 0,
});
// endpoint is a ws:// URL
```

Call [browser.unbind()](https://playwright.dev/docs/api/class-browser#browser-unbind) to stop accepting new connections.

## 📊 Observability

Run `playwright-cli show` to open the Dashboard that lists all the bound browsers, their statuses, and allows interacting with them:
- See what your agent is doing on the background browsers
- Click into the sessions for manual interventions
- Open DevTools to inspect pages from the background browsers.

<center>

<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-dashboard.png" alt="Demo" width="1169" height="835" />

</center>
- `playwright-cli` binds all of its browsers automatically, so you can see what your agents are doing.
- Pass `PLAYWRIGHT_DASHBOARD=1` env variable to see all `@playwright/test` browsers in the dashboard.

## 🐛 CLI debugger for agents

Coding agents can now run `npx playwright test --debug=cli` to attach and debug tests over `playwright-cli` — perfect for automatically fixing tests in agentic workflows:

```bash
$ npx playwright test --debug=cli
### Debugging Instructions
- Run "playwright-cli attach tw-87b59e" to attach to this test

$ playwright-cli attach tw-87b59e
### Session `tw-87b59e` created, attached to `tw-87b59e`.
Run commands with: playwright-cli --session=tw-87b59e <command>
### Paused
- Navigate to "/" at output/tests/example.spec.ts:4

$ playwright-cli --session tw-87b59e step-over
### Page
- Page URL: https://playwright.dev/
- Page Title: Fast and reliable end-to-end testing for modern web apps | Playwright
### Paused
- Expect "toHaveTitle" at output/tests/example.spec.ts:7
```

## 📋 CLI trace analysis for agents

Coding agents can run `npx playwright trace` to explore [Playwright Trace](https://playwright.dev/docs/trace-viewer) and understand failing or flaky tests from the command line:

```bash
$ npx playwright trace open test-results/example-has-title-chromium/trace.zip
  Title:        example.spec.ts:3 › has title

$ npx playwright trace actions --grep="expect"
     # Time       Action                                                  Duration
  ──── ─────────  ─────────────────────────────────────────────────────── ────────
    9. 0:00.859  Expect "toHaveTitle"                                        5.1s  ✗

$ npx playwright trace action 9
  Expect "toHaveTitle"
  Error: expect(page).toHaveTitle(expected) failed
    Expected pattern: /Wrong Title/
    Received string:  "Fast and reliable end-to-end testing for modern web apps | Playwright"
    Timeout: 5000ms
  Snapshots
    available: before, after
    usage:     npx playwright trace snapshot 9 --name <before|after>

$ npx playwright trace snapshot 9 --name after
### Page
- Page Title: Fast and reliable end-to-end testing for modern web apps | Playwright

$ npx playwright trace close
```

## ♻️ `await using`

Many APIs now return [async disposables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncDispose), enabling the `await using` syntax for automatic cleanup:

```js
await using page = await context.newPage();
{
  await using route = await page.route('**/*', route => route.continue());
  await using script = await page.addInitScript('console.log("init script here")');
  await page.goto('https://playwright.dev');
  // do something
}
// route and init script have been removed at this point
```

## 🔍 Snapshots and Locators
- Method [page.ariaSnapshot()](https://playwright.dev/docs/api/class-page#page-aria-snapshot) to capture the aria snapshot of the page — equivalent to `page.locator('body').ariaSnapshot()`.
- Options `depth` and `mode` in [locator.ariaSnapshot()](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
- Method [locator.normalize()](https://playwright.dev/docs/api/class-locator#locator-normalize) converts a locator to follow best practices like test ids and aria roles.
- Method [page.pickLocator()](https://playwright.dev/docs/api/class-page#page-pick-locator) enters an interactive mode where hovering over elements highlights them and shows the corresponding locator. Click an element to get its [Locator](https://playwright.dev/docs/api/class-locator) back. Use [page.cancelPickLocator()](https://playwright.dev/docs/api/class-page#page-cancel-pick-locator) to cancel.

## New APIs

### Screencast
- [page.screencast](https://playwright.dev/docs/api/class-page#page-screencast) provides video recording, real-time frame streaming, and overlay management.
- Methods [screencast.start()](https://playwright.dev/docs/api/class-screencast#screencast-start) and [screencast.stop()](https://playwright.dev/docs/api/class-screencast#screencast-stop) for recording and frame capture.
- Methods [screencast.showActions()](https://playwright.dev/docs/api/class-screencast#screencast-show-actions) and [screencast.hideActions()](https://playwright.dev/docs/api/class-screencast#screencast-hide-actions) for action annotations.
- Methods [screencast.showChapter()](https://playwright.dev/docs/api/class-screencast#screencast-show-chapter) and [screencast.showOverlay()](https://playwright.dev/docs/api/class-screencast#screencast-show-overlay) for visual overlays.
- Methods [screencast.showOverlays()](https://playwright.dev/docs/api/class-screencast#screencast-show-overlays) and [screencast.hideOverlays()](https://playwright.dev/docs/api/class-screencast#screencast-hide-overlays) for overlay visibility control.

### Storage, Console and Errors
- Method [browserContext.setStorageState()](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-storage-state) clears existing cookies, local storage, and IndexedDB for all origins and sets a new storage state — no need to create a new context.
- Methods [page.clearConsoleMessages()](https://playwright.dev/docs/api/class-page#page-clear-console-messages) and [page.clearPageErrors()](https://playwright.dev/docs/api/class-page#page-clear-page-errors) to clear stored messages and errors.
- Option `filter` in [page.consoleMessages()](https://playwright.dev/docs/api/class-page#page-console-messages) and [page.pageErrors()](https://playwright.dev/docs/api/class-page#page-page-errors) controls which messages are returned.
- Method [consoleMessage.timestamp()](https://playwright.dev/docs/api/class-consolemessage#console-message-timestamp).

### Miscellaneous
- [browserContext.debugger](https://playwright.dev/docs/api/class-browsercontext#browser-context-debugger) provides programmatic control over the Playwright debugger.
- Method [browserContext.isClosed()](https://playwright.dev/docs/api/class-browsercontext#browser-context-is-closed).
- Method [request.existingResponse()](https://playwright.dev/docs/api/class-request#request-existing-response) returns the response without waiting.
- Method [response.httpVersion()](https://playwright.dev/docs/api/class-response#response-http-version) returns the HTTP version used by the response.
- Events [cdpSession.on('event')](https://playwright.dev/docs/api/class-cdpsession#cdp-session-event-event) and [cdpSession.on('close')](https://playwright.dev/docs/api/class-cdpsession#cdp-session-event-close) for CDP sessions.
- Option `live` in [tracing.start()](https://playwright.dev/docs/api/class-tracing#tracing-start) for real-time trace updates.
- Option `artifactsDir` in [browserType.launch()](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) to configure the artifacts directory.

## 🛠️ Other improvements
- UI Mode has an option to only show tests affected by source changes.
- UI Mode and Trace Viewer have improved action filtering.
- HTML Reporter shows the list of runs from the same worker.
- HTML Reporter allows filtering test steps for quick search.
- New trace mode `'retain-on-failure-and-retries'` records a trace for each test run and retains all traces when an attempt fails — great for comparing a passing trace with a failing one from a flaky test.

## Known Issues ⚠️⚠️
- `navigator.platform` emulation can cause Ctrl or Meta dispatching errors (https://github.com/microsoft/playwright/issues/40009). Pass `PLAYWRIGHT_NO_UA_PLATFORM = '1'` environment variable while we are issuing a patch release. Let us know in the issue how it affected you.

## Breaking Changes ⚠️
- Removed macOS 14 support for WebKit. We recommend upgrading your macOS version, or keeping an older Playwright version.
- Removed `@playwright/experimental-ct-svelte` package.
- `junit` test reporter now differentiates between types of errors, so some of the previous `<failure>`s are now reported as `<error>`s. 

## Browser Versions
- Chromium 147.0.7727.15
- Mozilla Firefox 148.0.2
- WebKit 26.4

This version was also tested against the following stable channels:
- Google Chrome 146
- Microsoft Edge 146