# Playwright Knowledge Patch > Playwright - Skill: `nevaberry/playwright-knowledge-patch-2` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add nevaberry/playwright-knowledge-patch-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/playwright-knowledge-patch-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/playwright-knowledge-patch-2 --- # Playwright Knowledge Patch Use this skill for Playwright browser automation, component tests, the test runner, MCP, or test-agent workflows. ## Reference index | Reference | Topics | | --- | --- | | [Browser automation](references/browser-automation.md) | Screencasts, bound sessions, cancellation, storage and passkeys, screenshots, locators, diagnostics, protocol metadata, and resource disposal | | [Component testing](references/component-testing.md) | Story gallery, mounting by story id, typed props, update, and unmount | | [Test runner and debugging](references/test-runner-and-debugging.md) | Removed support, CLI debugging, traces, retry scheduling, video, reporters, runner data, recordings, artifacts, and platforms | | [MCP server](references/mcp-server.md) | Entry points, snapshot interaction, profiles, initialization, capabilities, configuration, guardrails, HTTP, and embedding | | [Test agents](references/test-agents.md) | Initialization, planner/generator/healer roles, seed tests, plans, generated artifacts, and regeneration | ## Breaking removals and compatibility changes - WebKit no longer supports macOS 14. - `@playwright/experimental-ct-svelte` has been removed. - Ubuntu 26.04 is supported. - The supplied MCP container image supports headless Chromium only. - Regenerate bundled test-agent definitions after every Playwright upgrade so their instructions and tools remain synchronized with the installed version. ## Cancel operations independently Most operations and web-first assertions accept an `AbortSignal`. The normal timeout remains active when a signal is supplied; set `timeout: 0` when the signal alone should bound the operation. ```ts const controller = new AbortController(); setTimeout(() => controller.abort(), 1_000); await page.getByRole('button', { name: 'Submit' }).click({ signal: controller.signal, }); await expect(page.getByText('Done')).toBeVisible({ signal: controller.signal, }); ``` Actions also accept `scroll: 'auto' | 'none'`. Use `'none'` when Playwright must not scroll the target into view. ## Use story-based component tests Define concrete component scenarios as stories and let the served gallery render them on demand. `mount(storyId)` returns a locator scoped to the story's root; use that locator for assertions and interactions, and call its `update(props)` or `unmount()` methods for lifecycle tests. ```ts test('click should expand', async ({ mount }) => { const component = await mount('components/Expandable/Stateful'); await component.getByRole('button').click(); await expect(component.getByTestId('expanded')).toHaveValue('true'); }); ``` Supply the story type as a type argument when props should be checked. See [Component testing](references/component-testing.md) for the workflow. ## Persist and exercise passkeys Each browser context exposes a cross-browser `credentials` virtual authenticator. Seed a backend-provisioned credential, install the authenticator, then exercise the page's normal WebAuthn ceremony without a hardware key. ```ts await context.credentials.create('example.com', { id: credentialId, userHandle, privateKey, publicKey, }); await context.credentials.install(); await page.goto('https://example.com/login'); ``` Use `credentials.get()` to retrieve an app-created credential for reuse. Add `credentials` to storage state when passkeys must seed later contexts. ## Work with storage directly `page.localStorage` and `page.sessionStorage` expose the current origin's Web Storage without evaluating page code. ```ts await page.localStorage.setItem('token', 'abc'); const token = await page.localStorage.getItem('token'); const sessionItems = await page.sessionStorage.items(); ``` Use `browserContext.setStorageState()` to replace a live context's state. It first clears cookies, local-storage origins, and IndexedDB origins, then applies the replacement state. ## Record and annotate screencasts Use `page.screencast` for explicit recording control, JPEG frame delivery, or presentation overlays. ```ts await page.screencast.start({ path: 'video.webm', onFrame: ({ data, timestamp }) => consumeFrame(data, timestamp), size: { width: 800, height: 600 }, quality: 90, }); await using actions = await page.screencast.showActions({ cursor }); await page.screencast.showChapter('Checkout'); await page.screencast.stop(); ``` `size` is an aspect-ratio-preserving maximum; without it, the viewport is scaled within 800x800. A screencast already started by tracing or video can override that size. Quality ranges from 0 through 100. See [Browser automation](references/browser-automation.md) for overlays and the regular test `video.show` annotations. ## Share a launched browser Bind a launched browser when multiple Playwright, CLI, or MCP clients must use one session. ```ts const { endpoint } = await browser.bind('review-session', { workspaceDir: process.cwd(), host: 'localhost', port: 0, }); const attached = await chromium.connect(endpoint); browser.unbind(); ``` Without `host` and `port`, binding uses a named pipe; with them, it exposes a WebSocket endpoint. `browser.unbind()` stops accepting new clients. ## Generate WebP visual artifacts End a visual snapshot name in `.webp` to select WebP. Standalone page and locator screenshots accept `type: 'webp'`; quality 100 is lossless and is the default, while lower values enable lossy compression. ```ts await expect(page).toHaveScreenshot('homepage.webp'); await page.screenshot({ path: 'homepage.webp', quality: 50 }); ``` ## Inspect locators and page accessibility - `page.ariaSnapshot()` snapshots the whole page, like a body locator. - Locator ARIA snapshots accept `depth` and `mode`. - `locator.normalize()` rewrites a locator toward recommended test-id and ARIA-role forms. - `page.pickLocator()` lets a person select an element interactively; `page.cancelPickLocator()` cancels the picker. ## Use disposable resources JavaScript resources such as pages, routes, and init scripts support `await using`; scope exit closes the page or removes the installed resource. ```ts await using page = await context.newPage(); { await using route = await page.route('**/*', route => route.continue()); await using script = await page.addInitScript('console.log("ready")'); await page.goto('https://example.com'); } ``` Evaluation methods accept functions as argument values. Page and context `addInitScript()` methods also accept functions as init-script arguments. ## Debug from the command line Start a test with the command-controlled debugger, attach to the bound session, then issue debugger commands: ```bash npx playwright test --debug=cli playwright-cli attach step-over ``` Inspect a saved trace without the GUI: ```bash npx playwright trace open trace.zip actions action snapshot --name before snapshot --name after close ``` Use `tracing.start({ live: true })` for real-time trace updates. For flaky tests, retain every attempt's trace when any attempt fails with `'retain-on-failure-and-retries'`. ## Configure retries, videos, and soft polls Set `testConfig.retryStrategy` to `'isolated'` to defer retries until the end and run them serially in one worker. The default `'immediate'` schedules each retry when a worker becomes available. Video mode accepts `'on-all-retries'`, `'retain-on-first-failure'`, and `'retain-on-failure-and-retries'`. Use `expect.soft.poll()` when a polling failure should be collected without immediately stopping the test. ## Launch the MCP server The MCP server requires Node.js 18 or newer. It is bundled with Playwright and can be launched from the main package: ```bash npx playwright mcp npx playwright cli ``` For automation, take a structured accessibility snapshot and pass an element's exact `ref` to the interaction tool. Use screenshots for visual verification, not action targeting. Read [MCP server](references/mcp-server.md) before enabling remote access, file access, origin rules, or secrets. ## Generate built-in test agents Generate definitions for the consuming client loop: ```bash npx playwright init-agents --loop=vscode ``` The planner explores the application and writes a plan under `specs/`; the generator validates selectors and assertions and writes tests under `tests/`; the healer replays failures, repairs tests within guardrails, and reruns them. Use a seed test to provide ready application state, fixtures, setup, project dependencies, and the preferred generated-test style. See [Test agents](references/test-agents.md) for the artifact and audit-link flow.