0
# Web Test Runner Playwright
1

2
Web Test Runner Playwright provides a Playwright browser launcher for the Web Test Runner ecosystem, enabling cross-browser testing with Chromium, Firefox, and WebKit using bundled browser versions. It offers comprehensive testing capabilities with configurable launch options, custom browser context and page creation, experimental window focus support, and flexible concurrency control.
3

4
## Package Information
5

6
- **Package Name**: @web/test-runner-playwright
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @web/test-runner-playwright`
10
- **Node.js**: >=18.0.0
11

12
## Core Imports
13

14
```typescript
15
import { playwrightLauncher, PlaywrightLauncher, devices, playwright, ProductType } from "@web/test-runner-playwright";
16
import type { LaunchOptions, Browser, BrowserContext, Page } from 'playwright';
17
import type { TestRunnerCoreConfig, CoverageMapData, SessionResult, BrowserLauncher } from '@web/test-runner-core';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { playwrightLauncher, PlaywrightLauncher, devices, playwright, ProductType } = require("@web/test-runner-playwright");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { playwrightLauncher } from "@web/test-runner-playwright";
30

31
// Basic launcher configuration
32
const browsers = [
33
  playwrightLauncher({ product: 'chromium' }),
34
  playwrightLauncher({ product: 'firefox' }),
35
  playwrightLauncher({ product: 'webkit' }),
36
];
37

38
// Web Test Runner config
39
export default {
40
  browsers,
41
  // other config options...
42
};
43
```
44

45
## Advanced Usage
46

47
```typescript
48
import { playwrightLauncher, playwright } from "@web/test-runner-playwright";
49

50
// Advanced configuration with custom options
51
const launcher = playwrightLauncher({
52
  product: 'chromium',
53
  launchOptions: {
54
    headless: false,
55
    devtools: true,
56
    args: ['--disable-web-security'],
57
  },
58
  createBrowserContext: ({ browser }) => 
59
    browser.newContext({
60
      viewport: { width: 1920, height: 1080 },
61
      locale: 'en-US',
62
    }),
63
  createPage: ({ context }) => context.newPage(),
64
  concurrency: 4,
65
  __experimentalWindowFocus__: true,
66
});
67
```
68

69
## Capabilities
70

71
### Playwright Launcher Factory
72

73
Creates a configured PlaywrightLauncher instance for use with Web Test Runner.
74

75
```typescript { .api }
76
/**
77
 * Factory function that creates a PlaywrightLauncher instance
78
 * @param args - Optional configuration arguments
79
 * @returns Configured PlaywrightLauncher instance
80
 */
81
function playwrightLauncher(args?: PlaywrightLauncherArgs): PlaywrightLauncher;
82

83
interface PlaywrightLauncherArgs {
84
  /** Browser engine to use - defaults to 'chromium' */
85
  product?: ProductType;
86
  /** Playwright launch options for browser startup */
87
  launchOptions?: LaunchOptions;
88
  /** Custom function for creating browser contexts */
89
  createBrowserContext?: CreateBrowserContextFn;
90
  /** Custom function for creating pages within contexts */
91
  createPage?: CreatePageFn;
92
  /** Experimental window focus feature - defaults to false */
93
  __experimentalWindowFocus__?: boolean;
94
  /** Maximum number of concurrent browser instances */
95
  concurrency?: number;
96
}
97
```
98

99
### PlaywrightLauncher Class
100

101
Main launcher class that implements the BrowserLauncher interface for Web Test Runner integration.
102

103
```typescript { .api }
104
/**
105
 * Main launcher class implementing BrowserLauncher interface
106
 * Manages browser instances and test sessions
107
 */
108
class PlaywrightLauncher implements BrowserLauncher {
109
  /** Human-readable browser name (e.g., "Chromium", "Firefox") */
110
  public name: string;
111
  /** Fixed identifier "playwright" */
112
  public type: string;
113
  /** Maximum number of concurrent browser instances */
114
  public concurrency?: number;
115
  /** Experimental window focus feature flag */
116
  public __experimentalWindowFocus__: boolean;
117

118
  constructor(
119
    product: ProductType,
120
    launchOptions: LaunchOptions,
121
    createBrowserContextFn: CreateBrowserContextFn,
122
    createPageFn: CreatePageFn,
123
    __experimentalWindowFocus__?: boolean,
124
    concurrency?: number
125
  );
126

127
  /** Initialize the launcher with test runner configuration */
128
  initialize(config: TestRunnerCoreConfig, testFiles: string[]): Promise<void>;
129

130
  /** Stop all browser instances and clean up resources */
131
  stop(): Promise<void>;
132

133
  /** Start a new test session with given session ID and URL */
134
  startSession(sessionId: string, url: string): Promise<void>;
135

136
  /** Check if a session is currently active */
137
  isActive(sessionId: string): boolean;
138

139
  /** Get the current browser URL for a session */
140
  getBrowserUrl(sessionId: string): string;
141

142
  /** Start a debug session with visible browser window */
143
  startDebugSession(sessionId: string, url: string): Promise<void>;
144

145
  /** Stop a session and return test results with optional coverage */
146
  stopSession(sessionId: string): Promise<SessionResult>;
147

148
  /** Get the Playwright page instance for a session */
149
  getPage(sessionId: string): Page;
150
}
151
```
152

153
### Browser Context and Page Creation
154

155
Custom functions for creating browser contexts and pages with specific configurations.
156

157
```typescript { .api }
158
/**
159
 * Function type for creating custom browser contexts
160
 * @param args - Browser and configuration objects
161
 * @returns Browser context (sync or async)
162
 */
163
type CreateBrowserContextFn = (args: CreateArgs) => BrowserContext | Promise<BrowserContext>;
164

165
/**
166
 * Function type for creating custom pages
167
 * @param args - Browser, context, and configuration objects
168
 * @returns Promise resolving to a Playwright page
169
 */
170
type CreatePageFn = (args: CreateArgs & { context: BrowserContext }) => Promise<Page>;
171

172
// CreateArgs interface is defined in the Types section below
173
```
174

175
### Type Exports
176

177
Core type definitions exported from the package.
178

179
```typescript { .api }
180
/**
181
 * Browser engine type defining supported Playwright browsers
182
 * Exported as a standalone type from the package
183
 */
184
export type ProductType = 'chromium' | 'firefox' | 'webkit';
185
```
186

187
### Playwright Integration
188

189
Direct access to Playwright APIs and device configurations.
190

191
```typescript { .api }
192
/**
193
 * Complete Playwright API namespace for advanced usage
194
 * Provides access to all Playwright functionality beyond the launcher
195
 */
196
const playwright: typeof import('playwright');
197

198
/**
199
 * Playwright device configurations for mobile testing
200
 * Contains predefined device settings for various mobile devices
201
 */
202
const devices: typeof import('playwright').devices;
203
```
204

205
## Types
206

207
```typescript { .api }
208
// Core type definitions
209

210
/**
211
 * Playwright launch options for browser startup configuration
212
 * Imported from 'playwright' package
213
 */
214
type LaunchOptions = import('playwright').LaunchOptions;
215

216
/**
217
 * Test Runner configuration interface
218
 * Imported from '@web/test-runner-core'
219
 */
220
type TestRunnerCoreConfig = import('@web/test-runner-core').TestRunnerCoreConfig;
221

222
/**
223
 * Istanbul coverage data format
224
 * Imported from '@web/test-runner-core' (re-exported from 'istanbul-lib-coverage')
225
 */
226
type CoverageMapData = import('@web/test-runner-core').CoverageMapData;
227

228
/**
229
 * Playwright browser types
230
 * Imported from 'playwright' package
231
 */
232
type Browser = import('playwright').Browser;
233
type BrowserContext = import('playwright').BrowserContext;
234
type Page = import('playwright').Page;
235

236
/**
237
 * Browser launcher interface from @web/test-runner-core
238
 * Defines the contract for browser launchers in the Web Test Runner ecosystem
239
 */
240
type BrowserLauncher = import('@web/test-runner-core').BrowserLauncher;
241

242
/**
243
 * Arguments for browser context and page creation functions
244
 */
245
interface CreateArgs {
246
  /** Playwright browser instance */
247
  browser: Browser;
248
  /** Web Test Runner configuration */
249
  config: TestRunnerCoreConfig;
250
}
251

252
/**
253
 * Session result interface - imported from @web/test-runner-core
254
 * Returned when stopping test sessions
255
 */
256
interface SessionResult {
257
  /** Test coverage data if coverage collection is enabled */
258
  testCoverage?: CoverageMapData;
259
  /** Array of test execution errors */
260
  errors?: TestResultError[];
261
  /** Browser console logs */
262
  browserLogs?: any[][];
263
}
264

265
interface TestResultError {
266
  message: string;
267
  name?: string;
268
  stack?: string;
269
  expected?: string;
270
  actual?: string;
271
}
272
```
273

274
## Error Handling
275

276
The package throws errors in the following scenarios:
277

278
- **Invalid Product Type**: When an unsupported browser engine is specified in `playwrightLauncher()`
279
- **Session Not Found**: When attempting operations on non-existent session IDs
280
- **Session Already Stopped**: When trying to stop an already closed session
281
- **Coverage Collection Failures**: When coverage is enabled but collection fails
282

283
Example error handling:
284

285
```typescript
286
try {
287
  const launcher = playwrightLauncher({ product: 'invalid' as ProductType });
288
} catch (error) {
289
  // Error: Invalid product: invalid. Valid product types: chromium, firefox, webkit
290
}
291
```
292

293
## Platform and Browser Support
294

295
- **Node.js**: Version 18.0.0 or higher required
296
- **Browsers**: 
297
  - Chromium (with DevTools support)
298
  - Firefox 
299
  - WebKit
300
- **Operating Systems**: Cross-platform support via Playwright
301
- **Coverage**: V8 native instrumentation (Chromium only) and JavaScript-based coverage
302

303
## Integration Notes
304

305
- Implements the `BrowserLauncher` interface from `@web/test-runner-core`
306
- Integrates with Web Test Runner's session management and coverage collection
307
- Supports both headless and headed browser execution
308
- Compatible with Web Test Runner's parallel testing capabilities
309
- Works with the broader Modern Web ecosystem of testing tools