Playwright v1.59.0 — Release Notes & Engineering Impact

## 🎬 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