0
# Providers
1

2
Browser automation providers for running tests in different browser environments, each with specific capabilities and configuration options supporting Playwright, WebdriverIO, and preview modes.
3

4
## Capabilities
5

6
### Provider System
7

8
@vitest/browser supports multiple browser automation providers, each with different strengths and use cases.
9

10
```typescript { .api }
11
/**
12
 * Playwright provider - Full browser automation with CDP access
13
 */
14
const playwright: BrowserProviderModule;
15

16
/**
17
 * WebdriverIO provider - Cross-browser testing with Selenium WebDriver
18
 */
19
const webdriverio: BrowserProviderModule;
20

21
/**
22
 * Preview provider - Development mode with simulated interactions
23
 */
24
const preview: BrowserProviderModule;
25
```
26

27
### Playwright Provider
28

29
Full-featured browser automation with Chrome DevTools Protocol support and advanced testing capabilities.
30

31
```typescript { .api }
32
import { playwright } from "@vitest/browser/providers";
33
```
34

35
**Configuration:**
36

37
```typescript
38
// vitest.config.ts
39
export default defineConfig({
40
  test: {
41
    browser: {
42
      enabled: true,
43
      provider: 'playwright',
44
      name: 'chromium', // or 'firefox', 'webkit'
45
      providerOptions: {
46
        launch: {
47
          // Playwright launch options
48
          headless: false,
49
          slowMo: 100,
50
          devtools: true
51
        },
52
        context: {
53
          // Browser context options
54
          viewport: { width: 1280, height: 720 },
55
          locale: 'en-US',
56
          actionTimeout: 5000
57
        }
58
      }
59
    }
60
  }
61
});
62
```
63

64
**Provider-Specific Type Augmentations:**
65

66
```typescript { .api }
67
// Module augmentation for vitest/node
68
declare module 'vitest/node' {
69
  interface BrowserProviderOptions {
70
    /** Playwright launch options */
71
    launch?: LaunchOptions;
72
    /** Connect to existing browser */
73
    connect?: {
74
      wsEndpoint: string;
75
      options?: ConnectOptions;
76
    };
77
    /** Browser context options */
78
    context?: Omit<BrowserContextOptions, 'ignoreHTTPSErrors' | 'serviceWorkers'> & {
79
      /** Maximum timeout for userEvent actions in milliseconds */
80
      actionTimeout?: number;
81
    };
82
  }
83

84
  interface BrowserCommandContext {
85
    /** Playwright page instance */
86
    page: Page;
87
    /** Get iframe frame */
88
    frame(): Promise<Frame>;
89
    /** Frame locator for iframe */
90
    iframe: FrameLocator;
91
    /** Browser context instance */
92
    context: BrowserContext;
93
  }
94
}
95

96
// Module augmentation for @vitest/browser/context
97
declare module '@vitest/browser/context' {
98
  interface CDPSession {
99
    /** Send Chrome DevTools Protocol command */
100
    send<T extends keyof Protocol.CommandParameters>(
101
      method: T,
102
      params?: Protocol.CommandParameters[T]
103
    ): Promise<Protocol.CommandReturnValues[T]>;
104
    
105
    /** Add CDP event listener */
106
    on<T extends keyof Protocol.Events>(
107
      event: T,
108
      listener: (payload: Protocol.Events[T]) => void
109
    ): this;
110
    
111
    /** Add one-time CDP event listener */
112
    once<T extends keyof Protocol.Events>(
113
      event: T,
114
      listener: (payload: Protocol.Events[T]) => void
115
    ): this;
116
    
117
    /** Remove CDP event listener */
118
    off<T extends keyof Protocol.Events>(
119
      event: T,
120
      listener: (payload: Protocol.Events[T]) => void
121
    ): this;
122
  }
123
  
124
  // User event options extend Playwright types
125
  interface UserEventHoverOptions extends PWHoverOptions {}
126
  interface UserEventClickOptions extends PWClickOptions {}
127
  interface UserEventDoubleClickOptions extends PWDoubleClickOptions {}
128
  interface UserEventTripleClickOptions extends PWClickOptions {}
129
  interface UserEventFillOptions extends PWFillOptions {}
130
  interface UserEventSelectOptions extends PWSelectOptions {}
131
  interface UserEventDragAndDropOptions extends PWDragAndDropOptions {}
132
  interface UserEventUploadOptions extends PWSetInputFiles {}
133
  interface ScreenshotOptions extends PWScreenshotOptions {}
134
}
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
import { cdp } from "@vitest/browser/context";
141

142
// Chrome DevTools Protocol usage (Playwright only)
143
const session = cdp();
144
await session.send('Runtime.enable');
145
await session.send('Runtime.evaluate', { expression: 'console.log("Hello CDP")' });
146

147
// Provider-specific command context
148
function myCommand({ page, context, iframe }: BrowserCommandContext) {
149
  // Access Playwright APIs directly
150
  await page.waitForLoadState('networkidle');
151
  await context.addCookies([{ name: 'test', value: 'value', url: 'https://example.com' }]);
152
  await iframe.locator('input').fill('text');
153
}
154
```
155

156
### WebdriverIO Provider
157

158
Cross-browser testing with Selenium WebDriver protocol support.
159

160
```typescript { .api }
161
import { webdriverio } from "@vitest/browser/providers";
162
```
163

164
**Configuration:**
165

166
```typescript
167
// vitest.config.ts
168
export default defineConfig({
169
  test: {
170
    browser: {
171
      enabled: true,
172
      provider: 'webdriverio',
173
      name: 'chrome', // or 'firefox', 'safari', 'edge'
174
      providerOptions: {
175
        // WebdriverIO remote options
176
        capabilities: {
177
          browserName: 'chrome',
178
          'goog:chromeOptions': {
179
            args: ['--no-sandbox', '--disable-dev-shm-usage']
180
          }
181
        },
182
        logLevel: 'warn',
183
        waitforTimeout: 10000,
184
        connectionRetryTimeout: 90000,
185
        connectionRetryCount: 3
186
      }
187
    }
188
  }
189
});
190
```
191

192
**Provider-Specific Type Augmentations:**
193

194
```typescript { .api }
195
// Module augmentation for vitest/node
196
declare module 'vitest/node' {
197
  interface BrowserProviderOptions extends Partial<Parameters<typeof remote>[0]> {
198
    // WebdriverIO remote options
199
    capabilities?: object;
200
    logLevel?: string;
201
    waitforTimeout?: number;
202
    connectionRetryTimeout?: number;
203
    connectionRetryCount?: number;
204
  }
205

206
  interface BrowserCommandContext {
207
    /** WebdriverIO browser instance */
208
    browser: WebdriverIO.Browser;
209
  }
210

211
  interface UserEventClickOptions extends ClickOptions {}
212

213
  interface UserEventDragOptions extends DragAndDropOptions {
214
    sourceX?: number;
215
    sourceY?: number;
216
    targetX?: number;
217
    targetY?: number;
218
  }
219
}
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
// Provider-specific command context
226
function myCommand({ browser }: BrowserCommandContext) {
227
  // Access WebdriverIO APIs directly
228
  await browser.maximizeWindow();
229
  await browser.execute('window.scrollTo(0, document.body.scrollHeight)');
230
  
231
  // Use WebdriverIO element methods
232
  const element = await browser.$('#my-element');
233
  await element.waitForDisplayed();
234
  await element.click();
235
}
236

237
// Provider-specific interaction options
238
await userEvent.click(page.getByRole("button"), {
239
  button: 'right', // Right click (WebdriverIO ClickOptions)
240
  x: 10,
241
  y: 10
242
});
243

244
// Drag and drop with coordinates
245
await userEvent.dragAndDrop(sourceElement, targetElement, {
246
  sourceX: 10,
247
  sourceY: 10,
248
  targetX: 50,
249
  targetY: 50
250
});
251
```
252

253
### Preview Provider
254

255
Development mode provider with simulated interactions using @testing-library/user-event.
256

257
```typescript { .api }
258
import { preview } from "@vitest/browser/providers";
259
```
260

261
**Configuration:**
262

263
```typescript
264
// vitest.config.ts
265
export default defineConfig({
266
  test: {
267
    browser: {
268
      enabled: true,
269
      provider: 'preview',
270
      name: 'chromium',
271
      providerOptions: {
272
        // Minimal configuration for preview mode
273
      }
274
    }
275
  }
276
});
277
```
278

279
**Characteristics:**
280

281
- **Fastest setup**: No external browser automation tools required
282
- **Simulated events**: Uses @testing-library/user-event for interactions
283
- **Development focused**: Ideal for rapid development and debugging
284
- **Limited features**: No real browser automation, no screenshots, no file uploads
285
- **No provider context**: Limited command context capabilities
286

287
**Usage Examples:**
288

289
```typescript
290
// Standard user interactions work the same
291
await userEvent.click(page.getByRole("button"));
292
await userEvent.type(page.getByLabelText("Input"), "text");
293

294
// Some features are not available in preview mode:
295
// - dragAndDrop() throws an error
296
// - CDP access is not available
297
// - File uploads are simulated
298
// - Screenshots return placeholder data
299
```
300

301
### Provider Selection Guide
302

303
Choose the right provider based on your testing needs:
304

305
**Use Playwright when:**
306
- Need CDP (Chrome DevTools Protocol) access
307
- Require advanced browser automation features
308
- Testing modern web applications with complex interactions
309
- Need reliable cross-browser testing
310
- Want comprehensive screenshot and video capabilities
311

312
**Use WebdriverIO when:**
313
- Existing Selenium WebDriver infrastructure
314
- Need to test older browsers
315
- Require specific WebDriver capabilities
316
- Integration with existing WebDriver-based tools
317
- Need mobile browser testing
318

319
**Use Preview when:**
320
- Rapid development and debugging
321
- Unit testing components in isolation
322
- CI/CD environments where speed is critical
323
- Don't need real browser automation
324
- Testing basic user interactions
325

326
### Provider-Specific Features
327

328
**Playwright Exclusive:**
329
- Chrome DevTools Protocol access via `cdp()`
330
- Advanced screenshot options (full page, element clipping)
331
- Network interception and mocking
332
- Browser context isolation
333
- Video recording capabilities
334

335
**WebdriverIO Exclusive:**
336
- Mobile browser testing
337
- Legacy browser support
338
- Selenium Grid integration
339
- Custom WebDriver capabilities
340
- Advanced wait strategies
341

342
**Preview Exclusive:**
343
- Fastest test execution
344
- No external dependencies
345
- Perfect for unit testing
346
- Debugging-friendly
347

348
### Error Handling
349

350
Different providers may throw different types of errors:
351

352
```typescript
353
import { server } from "@vitest/browser/context";
354

355
try {
356
  await userEvent.dragAndDrop(source, target);
357
} catch (error) {
358
  if (server.provider === 'preview') {
359
    // Preview provider doesn't support drag and drop
360
    console.log('Drag and drop not supported in preview mode');
361
  } else {
362
    // Real provider error
363
    throw error;
364
  }
365
}
366
```
367

368
## Types
369

370
Provider-related type definitions:
371

372
```typescript { .api }
373
interface BrowserProviderModule {
374
  // Provider implementation details (internal)
375
}
376

377
// Provider-specific option types are defined in their respective modules
378
// and extend base interfaces through module augmentation
379
```