This section covers specialized features and advanced architectural patterns in Playwright that extend beyond standard browser automation. Topics include component testing for UI frameworks, the internal protocol communication system, custom selector engines, schema-based validation, and advanced debugging capabilities.
For standard browser automation features, see Core API. For test framework capabilities, see Test Framework. For debugging tools, see Developer Tools.
Playwright provides a component testing solution that allows testing UI components in isolation across React, Vue, and Svelte frameworks. The architecture is built on a shared core with framework-specific adapters.
Sources: packages/playwright-ct-core/package.json1-34 packages/playwright-ct-react/package.json1-43 packages/playwright-ct-vue/package.json1-43 packages/playwright-ct-svelte/package.json1-43
| Phase | Component | Responsibility |
|---|---|---|
| Configuration | ct-core/lib/program | Load Vite config, setup framework plugin |
| Mounting | ct-core/lib/mount | Render component in isolated browser context |
| Testing | @playwright/test | Execute tests with standard Playwright API |
| Cleanup | ct-core | Teardown Vite server and browser |
The component testing packages depend on vite as a core dependency and use framework-specific Vite plugins to handle component transformation. Each framework adapter (ct-react, ct-vue, ct-svelte) provides:
register export for framework-specific initializationhooks export for component lifecycle managementFor detailed component testing architecture and usage, see Component Testing.
Sources: packages/playwright-ct-core/package.json17-27 packages/playwright-ct-react/package.json17-32 packages/playwright-ct-vue/package.json17-32 packages/playwright-ct-svelte/package.json17-32
Playwright uses a channel-based RPC protocol to communicate between the client (user code) and server (browser automation). This architecture enables language bindings, remote browser connections, and type-safe communication.
Sources: packages/protocol/src/protocol.yml1-15 packages/playwright-core/src/protocol/validator.ts1-22 packages/protocol/src/channels.d.ts1-22
The protocol.yml file defines the complete RPC interface using a declarative schema format:
| Element | Purpose | Example |
|---|---|---|
| Types | Data structures | SerializedValue, NetworkCookie, Point |
| Interfaces | RPC endpoints | Page, BrowserContext, Frame |
| Commands | Methods with parameters | Page.goto, Frame.click |
| Events | Server-to-client notifications | Page.close, Request.response |
| Mixins | Reusable property sets | LaunchOptions, ContextOptions |
Each command in the protocol includes:
The validator runtime (validator.ts) uses the schema to enforce type safety at the protocol boundary, preventing invalid messages from crossing the client-server divide.
Sources: packages/protocol/src/protocol.yml15-60 packages/playwright-core/src/protocol/validator.ts19-21
Each client-side object (Page, BrowserContext, etc.) extends ChannelOwner which provides:
_channel: Reference to the channel for sending commands_connection: WebSocket or pipe connection to serverEach server-side object extends Dispatcher which provides:
For detailed protocol architecture, see Protocol Communication Architecture.
Sources: packages/playwright-core/src/client/page.ts19-21 packages/playwright-core/src/server/dispatchers/pageDispatcher.ts1-25 packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts20-30
Playwright supports Zod schema validation for API responses, enabling type-safe data extraction from evaluated expressions.
The API types include conditional Zod support:
This allows methods like page.evaluate() to accept a Zod schema and return the inferred type:
The type system conditionally includes Zod types only when the zod package is installed, falling back to never when unavailable to maintain compatibility with projects not using Zod.
Sources: packages/playwright-core/types/types.d.ts34-39 packages/playwright-client/types/types.d.ts34-39
Playwright allows registration of custom selector engines for specialized element selection strategies.
The SelectorEngine type in the protocol defines custom selector registration:
Custom engines are registered via BrowserContext and can:
contentScript: false) for performancecontentScript: true) for isolationThe source property contains JavaScript code implementing the selector logic with a signature:
Sources: packages/protocol/src/protocol.yml157-163 packages/playwright-core/src/protocol/validator.ts95-99
Playwright provides advanced network mocking through HAR (HTTP Archive) replay, allowing tests to run against recorded network traffic.
HAR replay configuration options:
| Option | Values | Purpose |
|---|---|---|
url | glob/regexp | Filter which requests to intercept |
update | boolean | Update HAR with new requests |
updateContent | 'embed', 'attach' | How to store response bodies |
updateMode | 'full', 'minimal' | Recording verbosity |
notFound | 'abort', 'fallback' | Handle missing entries |
The HAR router integrates with the standard routing system and can be combined with custom route handlers for hybrid mocking strategies.
Sources: packages/protocol/src/protocol.yml295-313 packages/playwright-core/src/client/page.ts106 packages/playwright-core/src/client/harRouter.ts1-20
Playwright includes an experimental agentic interface that uses AI to interact with pages through natural language instructions.
Agent configuration parameters (from params.md):
The agent system converts natural language tasks into cached Playwright API calls, enabling higher-level test authoring while maintaining the reliability of explicit actions.
Sources: docs/src/api/params.md374-404 packages/playwright-core/src/client/page.ts44 packages/playwright-core/src/client/pageAgent.ts1-20
For advanced use cases, Playwright exposes browser-specific debugging protocols.
CDP access is available only in Chromium and provides:
The CDPSession class provides:
send(method, params): Send CDP commandson(event, handler): Listen to CDP eventsdetach(): Close the sessionSources: packages/playwright-core/src/client/cdpSession.ts1-20 packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts22
Browser-specific protocol types are maintained separately:
| Browser | Protocol File | Source |
|---|---|---|
| Chromium | chromium/protocol.d.ts | Chrome DevTools Protocol |
| Firefox | firefox/protocol.d.ts | Juggler Protocol |
| WebKit | webkit/protocol.d.ts | WebKit Inspector Protocol |
These definitions are generated from browser source code and kept synchronized with supported browser versions defined in browsers.json.
Sources: Diagram references packages/playwright-core/browsers.json1-50
Playwright's TypeScript types include several advanced patterns for type safety.
This enables type-safe element access where TypeScript knows the specific element type:
Many methods use extensive overloading for different argument combinations:
This provides optimal type inference while maintaining backward compatibility with optional parameters.
The types conditionally support the native URLPattern API:
This pattern allows using URLPattern in Node.js 22+ and modern browsers while gracefully degrading in older environments where it's not available.
Sources: packages/playwright-core/types/types.d.ts23-39 packages/playwright-client/types/types.d.ts23-39 packages/playwright-core/types/types.d.ts330-360
Advanced Playwright features enable:
For component testing details, see Component Testing. For protocol internals, see Protocol Communication Architecture.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.