0
# Playwright Test
1

2
Playwright Test (@playwright/test) is a comprehensive end-to-end testing framework for modern web applications that enables automated testing across Chromium, Firefox, and WebKit browsers with a single API. It provides built-in test runner capabilities, parallel test execution, automatic waiting, screenshot and video recording, network interception, mobile device emulation, and cross-browser compatibility testing with robust debugging tools and CI/CD integration support.
3

4
## Package Information
5

6
- **Package Name**: @playwright/test
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @playwright/test`
10

11
## Core Imports
12

13
```typescript
14
import { test, expect } from "@playwright/test";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { test, expect } = require("@playwright/test");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { test, expect } from "@playwright/test";
27

28
test("basic navigation and interaction", async ({ page }) => {
29
  // Navigate to a page
30
  await page.goto("https://example.com");
31
  
32
  // Interact with elements
33
  await page.click("button");
34
  await page.fill("input[name='username']", "testuser");
35
  
36
  // Make assertions
37
  await expect(page.locator("h1")).toHaveText("Welcome");
38
  await expect(page).toHaveURL(/.*dashboard/);
39
});
40

41
test.describe("User Authentication", () => {
42
  test("successful login", async ({ page }) => {
43
    await page.goto("/login");
44
    await page.fill("#username", "admin");
45
    await page.fill("#password", "secret");
46
    await page.click("button[type='submit']");
47
    
48
    await expect(page).toHaveURL("/dashboard");
49
  });
50
});
51
```
52

53
## Architecture
54

55
Playwright Test is built around several key components:
56

57
- **Test Framework**: Core test declaration functions (`test`, `describe`) with built-in fixtures and lifecycle hooks
58
- **Browser Automation**: Cross-browser automation capabilities through Page, BrowserContext, and Browser objects
59
- **Assertion Library**: Web-specific assertions with built-in retry logic and automatic waiting
60
- **Fixture System**: Dependency injection for test setup including page, context, and browser instances
61
- **Configuration System**: Flexible configuration options for browsers, devices, execution modes, and reporting
62
- **Test Runner**: Parallel execution engine with worker isolation and intelligent test distribution
63

64
## Capabilities
65

66
### Test Framework Core
67

68
Essential test declaration, organization, and lifecycle management functions for structuring test suites.
69

70
```typescript { .api }
71
interface TestType<TestArgs, WorkerArgs> {
72
  (title: string, testFunction: (args: TestArgs) => Promise<void>): void;
73
  only: (title: string, testFunction: (args: TestArgs) => Promise<void>) => void;
74
  skip: (title: string, testFunction: (args: TestArgs) => Promise<void>) => void;
75
  fixme: (title: string, testFunction: (args: TestArgs) => Promise<void>) => void;
76
  slow: (title: string, testFunction: (args: TestArgs) => Promise<void>) => void;
77
  fail: (title: string, testFunction: (args: TestArgs) => Promise<void>) => void;
78
  
79
  describe: {
80
    (title: string, callback: () => void): void;
81
    only: (title: string, callback: () => void) => void;
82
    skip: (title: string, callback: () => void) => void;
83
    fixme: (title: string, callback: () => void) => void;
84
    serial: (title: string, callback: () => void) => void;
85
    parallel: (title: string, callback: () => void) => void;
86
    configure: (options: { mode?: 'default' | 'parallel' | 'serial' }) => void;
87
  };
88
  
89
  beforeEach: (hookFunction: (args: TestArgs) => Promise<void>) => void;
90
  afterEach: (hookFunction: (args: TestArgs) => Promise<void>) => void;
91
  beforeAll: (hookFunction: (args: WorkerArgs) => Promise<void>) => void;
92
  afterAll: (hookFunction: (args: WorkerArgs) => Promise<void>) => void;
93
  
94
  extend<T, W>(fixtures: Fixtures<T, W>): TestType<TestArgs & T, WorkerArgs & W>;
95
  use: (options: TestOptions) => void;
96
  step<T>(title: string, body: () => Promise<T>): Promise<T>;
97
  info(): TestInfo;
98
}
99

100
const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
101

102
/**
103
 * Base test without built-in fixtures - for custom test implementations
104
 */
105
const _baseTest: TestType<{}, {}>;
106
```
107

108
[Test Framework Core](./test-framework.md)
109

110
### Browser Automation
111

112
Complete browser automation API providing page interaction, element manipulation, and navigation across multiple browsers.
113

114
```typescript { .api }
115
interface Page {
116
  goto(url: string, options?: { waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' }): Promise<Response>;
117
  click(selector: string, options?: { timeout?: number }): Promise<void>;
118
  fill(selector: string, value: string): Promise<void>;
119
  press(selector: string, key: string): Promise<void>;
120
  waitForSelector(selector: string, options?: { timeout?: number }): Promise<ElementHandle>;
121
  locator(selector: string): Locator;
122
  screenshot(options?: { path?: string; fullPage?: boolean }): Promise<Buffer>;
123
}
124

125
interface BrowserContext {
126
  newPage(): Promise<Page>;
127
  close(): Promise<void>;
128
}
129

130
interface Browser {
131
  newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
132
  close(): Promise<void>;
133
}
134
```
135

136
[Browser Automation](./browser-automation.md)
137

138
### Assertions and Expectations
139

140
Web-specific assertion library with automatic waiting and retry logic for reliable test assertions.
141

142
```typescript { .api }
143
interface Expect {
144
  <T>(actual: T): PlaywrightAssertions<T>;
145
  soft<T>(actual: T): PlaywrightAssertions<T>;
146
  poll<T>(actual: () => T | Promise<T>): PlaywrightAssertions<T>;
147
  extend<T>(matchers: CustomMatchers<T>): void;
148
  configure(options: { timeout?: number; soft?: boolean }): void;
149
}
150

151
interface PlaywrightAssertions<T> {
152
  toEqual(expected: T): Promise<void>;
153
  toHaveText(expected: string | RegExp): Promise<void>;
154
  toHaveValue(expected: string): Promise<void>;
155
  toBeVisible(): Promise<void>;
156
  toBeEnabled(): Promise<void>;
157
  toHaveURL(expected: string | RegExp): Promise<void>;
158
}
159

160
const expect: Expect;
161
```
162

163
[Assertions](./assertions.md)
164

165
### Configuration and Setup
166

167
Configuration system for test execution, browser options, and project setup with support for multiple environments.
168

169
```typescript { .api }
170
interface PlaywrightTestConfig {
171
  projects?: TestProject[];
172
  use?: PlaywrightTestOptions;
173
  testDir?: string;
174
  timeout?: number;
175
  retries?: number;
176
  workers?: number;
177
  reporter?: ReporterDescription[];
178
  outputDir?: string;
179
}
180

181
interface TestProject {
182
  name: string;
183
  use?: PlaywrightTestOptions;
184
  testDir?: string;
185
  testIgnore?: string | RegExp | (string | RegExp)[];
186
}
187

188
function defineConfig(config: PlaywrightTestConfig): PlaywrightTestConfig;
189
```
190

191
[Configuration](./configuration.md)
192

193
### Test Reporting
194

195
Comprehensive reporting system with built-in reporters and custom reporter support for various output formats.
196

197
```typescript { .api }
198
interface Reporter {
199
  onBegin?(config: FullConfig, suite: Suite): void;
200
  onTestBegin?(test: TestCase, result: TestResult): void;
201
  onTestEnd?(test: TestCase, result: TestResult): void;
202
  onEnd?(result: FullResult): void;
203
}
204

205
interface TestResult {
206
  status: 'passed' | 'failed' | 'timedOut' | 'skipped';
207
  duration: number;
208
  errors: TestError[];
209
  attachments: Attachment[];
210
}
211

212
type ReporterDescription = 
213
  | 'list' 
214
  | 'dot' 
215
  | 'line' 
216
  | 'json' 
217
  | 'junit' 
218
  | 'html' 
219
  | 'blob' 
220
  | 'github'
221
  | [string, any];
222
```
223

224
[Reporting](./reporting.md)
225

226
## Core Types
227

228
### Built-in Fixtures
229

230
```typescript { .api }
231
interface PlaywrightTestArgs {
232
  page: Page;
233
  context: BrowserContext;
234
  browser: Browser;
235
  browserName: 'chromium' | 'firefox' | 'webkit';
236
  request: APIRequestContext;
237
}
238

239
interface PlaywrightWorkerArgs {
240
  playwright: Playwright;
241
  browserName: 'chromium' | 'firefox' | 'webkit';
242
}
243
```
244

245
### Test Configuration Options
246

247
```typescript { .api }
248
interface PlaywrightTestOptions {
249
  baseURL?: string;
250
  headless?: boolean;
251
  viewport?: { width: number; height: number } | null;
252
  ignoreHTTPSErrors?: boolean;
253
  screenshot?: 'off' | 'only-on-failure' | 'on';
254
  video?: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
255
  trace?: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
256
  storageState?: string | { cookies: Cookie[]; origins: Origin[] };
257
}
258
```
259

260
### Test Information
261

262
```typescript { .api }
263
interface TestInfo {
264
  annotations: Array<{
265
    type: string;
266
    description?: string;
267
  }>;
268
  attachments: Array<{
269
    name: string;
270
    contentType: string;
271
    path?: string;
272
    body?: string | Buffer;
273
  }>;
274
  column: number;
275
  config: FullConfig;
276
  duration: number;
277
  errors: Array<TestInfoError>;
278
  expectedStatus: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
279
  file: string;
280
  fn: Function;
281
  line: number;
282
  outputDir: string;
283
  parallelIndex: number;
284
  project: FullProject;
285
  repeatEachIndex: number;
286
  retry: number;
287
  snapshotDir: string;
288
  snapshotSuffix: string;
289
  status?: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
290
  tags: Array<string>;
291
  testId: string;
292
  timeout: number;
293
  title: string;
294
  titlePath: Array<string>;
295
  workerIndex: number;
296
  
297
  // Methods
298
  snapshotPath(...name: ReadonlyArray<string>): string;
299
  snapshotPath(name: string, options?: { kind?: 'screenshot' | 'aria' | 'snapshot' }): string;
300
  outputPath(...pathSegments: ReadonlyArray<string>): string;
301
  skip(condition?: boolean, description?: string): void;
302
  fixme(condition?: boolean, description?: string): void;
303
  fail(condition?: boolean, description?: string): void;
304
  slow(condition?: boolean, description?: string): void;
305
  setTimeout(timeout: number): void;
306
}
307

308
interface WorkerInfo {
309
  config: FullConfig;
310
  parallelIndex: number;
311
  project: FullProject;
312
  workerIndex: number;
313
}
314
```