0
# Browser Automation
1

2
TestCafe provides comprehensive browser automation capabilities through the test controller (`t` object). All actions return promises and can be chained together for fluent test workflows.
3

4
## Capabilities
5

6
### Click Actions
7

8
Perform various click operations on DOM elements.
9

10
```javascript { .api }
11
/**
12
 * Clicks a DOM element
13
 * @param selector - Element selector (string or Selector object)
14
 * @param options - Click options including modifiers and position
15
 * @returns Promise resolving to test controller for chaining
16
 */
17
click(selector: string | Selector, options?: ClickOptions): Promise<TestController>;
18

19
/**
20
 * Right-clicks a DOM element
21
 * @param selector - Element selector
22
 * @param options - Click options
23
 * @returns Promise resolving to test controller for chaining
24
 */
25
rightClick(selector: string | Selector, options?: ClickOptions): Promise<TestController>;
26

27
/**
28
 * Double-clicks a DOM element
29
 * @param selector - Element selector
30
 * @param options - Click options
31
 * @returns Promise resolving to test controller for chaining
32
 */
33
doubleClick(selector: string | Selector, options?: ClickOptions): Promise<TestController>;
34

35
interface ClickOptions {
36
    modifiers?: {
37
        ctrl?: boolean;
38
        alt?: boolean;
39
        shift?: boolean;
40
        meta?: boolean;
41
    };
42
    offsetX?: number;
43
    offsetY?: number;
44
    caretPos?: number;
45
    speed?: number;
46
}
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
import { Selector } from 'testcafe';
53

54
fixture('Click Examples')
55
    .page('https://example.com');
56

57
test('Click operations', async t => {
58
    // Simple click
59
    await t.click('#submit-button');
60
    
61
    // Click with modifiers
62
    await t.click('.item', { 
63
        modifiers: { ctrl: true } 
64
    });
65
    
66
    // Right-click for context menu
67
    await t.rightClick('.file-item');
68
    
69
    // Double-click to edit
70
    await t.doubleClick('.editable-text');
71
});
72
```
73

74
### Text Input
75

76
Type text into form elements and editable content.
77

78
```javascript { .api }
79
/**
80
 * Types text into an input element
81
 * @param selector - Target input element
82
 * @param text - Text to type
83
 * @param options - Typing options including speed and replacement mode
84
 * @returns Promise resolving to test controller for chaining
85
 */
86
typeText(selector: string | Selector, text: string, options?: TypeOptions): Promise<TestController>;
87

88
/**
89
 * Selects text in an input element
90
 * @param selector - Target input element
91
 * @param startPos - Start position of selection
92
 * @param endPos - End position of selection
93
 * @param options - Selection options
94
 * @returns Promise resolving to test controller for chaining
95
 */
96
selectText(selector: string | Selector, startPos?: number, endPos?: number, options?: ActionOptions): Promise<TestController>;
97

98
/**
99
 * Selects all text content in a textarea
100
 * @param selector - Target textarea element
101
 * @param startLine - Start line for selection
102
 * @param startPos - Start position in start line
103
 * @param endLine - End line for selection
104
 * @param endPos - End position in end line
105
 * @param options - Selection options
106
 * @returns Promise resolving to test controller for chaining
107
 */
108
selectTextAreaContent(selector: string | Selector, startLine?: number, startPos?: number, endLine?: number, endPos?: number, options?: ActionOptions): Promise<TestController>;
109

110
/**
111
 * Selects editable content in contenteditable elements
112
 * @param selector - Target contenteditable element
113
 * @param startSelector - Start position selector
114
 * @param endSelector - End position selector
115
 * @param options - Selection options
116
 * @returns Promise resolving to test controller for chaining
117
 */
118
selectEditableContent(selector: string | Selector, startSelector?: string | Selector, endSelector?: string | Selector, options?: ActionOptions): Promise<TestController>;
119

120
interface TypeOptions extends ActionOptions {
121
    replace?: boolean;
122
    paste?: boolean;
123
}
124

125
interface ActionOptions {
126
    speed?: number;
127
}
128
```
129

130
**Usage Examples:**
131

132
```javascript
133
test('Text input operations', async t => {
134
    // Type into input field
135
    await t.typeText('#username', 'john.doe');
136
    
137
    // Replace existing text
138
    await t.typeText('#email', 'new@example.com', { replace: true });
139
    
140
    // Select text range
141
    await t.selectText('#username', 0, 4); // Select "john"
142
    
143
    // Select all content in textarea
144
    await t.selectTextAreaContent('#description');
145
});
146
```
147

148
### Keyboard Input
149

150
Send keyboard input including special keys and key combinations.
151

152
```javascript { .api }
153
/**
154
 * Presses keyboard keys
155
 * @param keys - Key sequence to press (supports special keys and combinations)
156
 * @param options - Key press options
157
 * @returns Promise resolving to test controller for chaining
158
 */
159
pressKey(keys: string, options?: ActionOptions): Promise<TestController>;
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
test('Keyboard input', async t => {
166
    // Press single key
167
    await t.pressKey('enter');
168
    
169
    // Press key combination
170
    await t.pressKey('ctrl+a');
171
    
172
    // Press sequence of keys
173
    await t.pressKey('tab tab enter');
174
    
175
    // Special keys
176
    await t.pressKey('left right up down');
177
    await t.pressKey('home end pageup pagedown');
178
    await t.pressKey('f1 f2 f3');
179
});
180
```
181

182
### Mouse Actions
183

184
Perform mouse hover and drag operations.
185

186
```javascript { .api }
187
/**
188
 * Hovers over an element
189
 * @param selector - Element to hover over
190
 * @param options - Hover options
191
 * @returns Promise resolving to test controller for chaining
192
 */
193
hover(selector: string | Selector, options?: HoverOptions): Promise<TestController>;
194

195
/**
196
 * Drags an element
197
 * @param selector - Element to drag
198
 * @param dragOffsetX - Horizontal drag distance
199
 * @param dragOffsetY - Vertical drag distance
200
 * @param options - Drag options
201
 * @returns Promise resolving to test controller for chaining
202
 */
203
drag(selector: string | Selector, dragOffsetX: number, dragOffsetY: number, options?: DragOptions): Promise<TestController>;
204

205
/**
206
 * Drags an element to another element
207
 * @param selector - Element to drag
208
 * @param destinationSelector - Drop target element
209
 * @param options - Drag options
210
 * @returns Promise resolving to test controller for chaining
211
 */
212
dragToElement(selector: string | Selector, destinationSelector: string | Selector, options?: DragOptions): Promise<TestController>;
213

214
interface HoverOptions extends ActionOptions {
215
    offsetX?: number;
216
    offsetY?: number;
217
}
218

219
interface DragOptions extends ActionOptions {
220
    offsetX?: number;
221
    offsetY?: number;
222
    destinationOffsetX?: number;
223
    destinationOffsetY?: number;
224
    modifiers?: {
225
        ctrl?: boolean;
226
        alt?: boolean;
227
        shift?: boolean;
228
        meta?: boolean;
229
    };
230
}
231
```
232

233
### File Upload
234

235
Handle file upload inputs.
236

237
```javascript { .api }
238
/**
239
 * Sets files to upload for file input elements
240
 * @param selector - File input element selector
241
 * @param filePath - Path to file(s) to upload
242
 * @param options - Upload options
243
 * @returns Promise resolving to test controller for chaining
244
 */
245
setFilesToUpload(selector: string | Selector, filePath: string | string[], options?: ActionOptions): Promise<TestController>;
246

247
/**
248
 * Clears file upload input
249
 * @param selector - File input element selector  
250
 * @param options - Clear options
251
 * @returns Promise resolving to test controller for chaining
252
 */
253
clearUpload(selector: string | Selector, options?: ActionOptions): Promise<TestController>;
254
```
255

256
**Usage Examples:**
257

258
```javascript
259
test('File upload', async t => {
260
    // Upload single file
261
    await t.setFilesToUpload('#file-input', './uploads/document.pdf');
262
    
263
    // Upload multiple files
264
    await t.setFilesToUpload('#multi-file-input', [
265
        './uploads/image1.jpg',
266
        './uploads/image2.png'
267
    ]);
268
    
269
    // Clear upload
270
    await t.clearUpload('#file-input');
271
});
272
```
273

274
### Navigation
275

276
Navigate between pages and control browser navigation.
277

278
```javascript { .api }
279
/**
280
 * Navigates to a URL
281
 * @param url - Target URL to navigate to
282
 * @param options - Navigation options
283
 * @returns Promise resolving to test controller for chaining
284
 */
285
navigateTo(url: string, options?: ActionOptions): Promise<TestController>;
286
```
287

288
**Usage Examples:**
289

290
```javascript
291
test('Navigation', async t => {
292
    // Navigate to specific URL
293
    await t.navigateTo('https://example.com/login');
294
    
295
    // Navigate to relative URL
296
    await t.navigateTo('/dashboard');
297
    
298
    // Navigate back and perform action
299
    await t
300
        .navigateTo('https://example.com/page1')
301
        .click('#next-button')
302
        .navigateTo('https://example.com/page2');
303
});
304
```
305

306
### Scrolling
307

308
Control page and element scrolling.
309

310
```javascript { .api }
311
/**
312
 * Scrolls the page or element
313
 * @param selector - Element to scroll (or page if not specified)
314
 * @param scrollLeft - Horizontal scroll position
315
 * @param scrollTop - Vertical scroll position
316
 * @param options - Scroll options
317
 * @returns Promise resolving to test controller for chaining
318
 */
319
scroll(selector: string | Selector, scrollLeft: number, scrollTop: number, options?: ActionOptions): Promise<TestController>;
320

321
/**
322
 * Scrolls by offset
323
 * @param selector - Element to scroll
324
 * @param x - Horizontal scroll offset
325
 * @param y - Vertical scroll offset
326
 * @param options - Scroll options
327
 * @returns Promise resolving to test controller for chaining
328
 */
329
scrollBy(selector: string | Selector, x: number, y: number, options?: ActionOptions): Promise<TestController>;
330

331
/**
332
 * Scrolls element into view
333
 * @param selector - Element to scroll into view
334
 * @param options - Scroll options
335
 * @returns Promise resolving to test controller for chaining
336
 */
337
scrollIntoView(selector: string | Selector, options?: ActionOptions): Promise<TestController>;
338
```
339

340
### Window Management
341

342
Manage browser windows and switch between them.
343

344
```javascript { .api }
345
/**
346
 * Opens a new browser window
347
 * @param url - URL to open in new window
348
 * @returns Promise resolving to test controller for chaining
349
 */
350
openWindow(url: string): Promise<TestController>;
351

352
/**
353
 * Closes the current browser window
354
 * @returns Promise resolving to test controller for chaining
355
 */
356
closeWindow(): Promise<TestController>;
357

358
/**
359
 * Switches to a specific browser window
360
 * @param windowDescriptor - Window to switch to
361
 * @returns Promise resolving to test controller for chaining
362
 */
363
switchToWindow(windowDescriptor: string | WindowDescriptor): Promise<TestController>;
364

365
/**
366
 * Switches to window matching predicate function
367
 * @param predicate - Function to identify target window
368
 * @returns Promise resolving to test controller for chaining
369
 */
370
switchToWindowByPredicate(predicate: (window: WindowDescriptor) => boolean): Promise<TestController>;
371

372
/**
373
 * Switches to parent window
374
 * @returns Promise resolving to test controller for chaining
375
 */
376
switchToParentWindow(): Promise<TestController>;
377

378
/**
379
 * Switches to previously active window
380
 * @returns Promise resolving to test controller for chaining
381
 */
382
switchToPreviousWindow(): Promise<TestController>;
383

384
/**
385
 * Gets current window descriptor
386
 * @returns Promise resolving to current window information
387
 */
388
getCurrentWindow(): Promise<WindowDescriptor>;
389

390
interface WindowDescriptor {
391
    id: string;
392
    title: string;
393
    url: string;
394
}
395
```
396

397
### Frame Management
398

399
Switch between iframe contexts.
400

401
```javascript { .api }
402
/**
403
 * Switches to iframe context
404
 * @param selector - Iframe element selector
405
 * @returns Promise resolving to test controller for chaining
406
 */
407
switchToIframe(selector: string | Selector): Promise<TestController>;
408

409
/**
410
 * Switches back to main window context
411
 * @returns Promise resolving to test controller for chaining
412
 */
413
switchToMainWindow(): Promise<TestController>;
414
```
415

416
### Dialog Handling
417

418
Handle native browser dialogs (alert, confirm, prompt).
419

420
```javascript { .api }
421
/**
422
 * Sets handler for native browser dialogs
423
 * @param fn - Function to handle dialog interactions
424
 * @param options - Dialog handling options
425
 * @returns Promise resolving to test controller for chaining
426
 */
427
setNativeDialogHandler(fn: (type: string, text: string, url: string) => boolean | string, options?: object): Promise<TestController>;
428

429
/**
430
 * Gets history of native dialog interactions
431
 * @returns Promise resolving to array of dialog interactions
432
 */
433
getNativeDialogHistory(): Promise<DialogHistoryItem[]>;
434

435
interface DialogHistoryItem {
436
    type: 'alert' | 'confirm' | 'prompt' | 'beforeunload';
437
    text: string;
438
    url: string;
439
}
440
```
441

442
### Browser Information
443

444
Access browser console messages and debugging information.
445

446
```javascript { .api }
447
/**
448
 * Gets browser console messages
449
 * @returns Promise resolving to array of console messages
450
 */
451
getBrowserConsoleMessages(): Promise<BrowserConsoleMessage[]>;
452

453
/**
454
 * Gets current Chrome DevTools Protocol session
455
 * @returns Promise resolving to CDP session object
456
 */
457
getCurrentCDPSession(): Promise<CDPSession>;
458

459
interface BrowserConsoleMessage {
460
    type: 'log' | 'info' | 'error' | 'warn';
461
    text: string;
462
    source: string;
463
}
464
```
465

466
### Test Speed Control
467

468
Control the speed of test execution.
469

470
```javascript { .api }
471
/**
472
 * Sets the test execution speed
473
 * @param speed - Speed factor (0.01 to 1, where 1 is maximum speed)
474
 * @returns Promise resolving to test controller for chaining
475
 */
476
setTestSpeed(speed: number): Promise<TestController>;
477

478
/**
479
 * Sets page load timeout
480
 * @param duration - Timeout duration in milliseconds
481
 * @returns Promise resolving to test controller for chaining
482
 */
483
setPageLoadTimeout(duration: number): Promise<TestController>;
484
```
485

486
### Cookie Management
487

488
Manage browser cookies for authentication and state management.
489

490
```javascript { .api }
491
/**
492
 * Gets browser cookies
493
 * @param cookies - Cookie names to retrieve (optional, gets all if omitted)
494
 * @param urls - URLs to get cookies for (optional)
495
 * @returns Promise resolving to array of cookie objects
496
 */
497
getCookies(cookies?: string | string[] | object, urls?: string | string[]): Promise<Cookie[]>;
498

499
/**
500
 * Sets browser cookies
501
 * @param cookies - Cookie objects or key-value pairs to set
502
 * @param url - URL to set cookies for (optional)
503
 * @returns Promise resolving to test controller for chaining
504
 */
505
setCookies(cookies: Cookie | Cookie[] | object, url?: string): Promise<TestController>;
506

507
/**
508
 * Deletes browser cookies
509
 * @param cookies - Cookie names to delete
510
 * @param urls - URLs to delete cookies from (optional)
511
 * @returns Promise resolving to test controller for chaining
512
 */
513
deleteCookies(cookies: string | string[] | Cookie[], urls?: string | string[]): Promise<TestController>;
514

515
interface Cookie {
516
    name: string;
517
    value: string;
518
    domain?: string;
519
    path?: string;
520
    expires?: Date;
521
    httpOnly?: boolean;
522
    secure?: boolean;
523
    sameSite?: 'Strict' | 'Lax' | 'None';
524
}
525
```
526

527
### Screenshots and Visual Testing
528

529
Capture screenshots for visual testing and debugging.
530

531
```javascript { .api }
532
/**
533
 * Takes a screenshot of the entire page or specific element
534
 * @param options - Screenshot options including path and element selector
535
 * @returns Promise resolving to test controller for chaining
536
 */
537
takeScreenshot(options?: ScreenshotOptions): Promise<TestController>;
538

539
/**
540
 * Takes a screenshot of a specific element
541
 * @param selector - Element to screenshot
542
 * @param options - Screenshot options
543
 * @returns Promise resolving to test controller for chaining
544
 */
545
takeElementScreenshot(selector: string | Selector, options?: ScreenshotOptions): Promise<TestController>;
546

547
interface ScreenshotOptions {
548
    path?: string;
549
    pathPattern?: string;
550
    fullPage?: boolean;
551
    thumbnails?: boolean;
552
}
553
```
554

555
### Test Utilities
556

557
Utility functions for debugging and test flow control.
558

559
```javascript { .api }
560
/**
561
 * Pauses test execution for specified duration
562
 * @param timeout - Wait duration in milliseconds
563
 * @returns Promise resolving to test controller for chaining
564
 */
565
wait(timeout: number): Promise<TestController>;
566

567
/**
568
 * Pauses test execution and enters debug mode
569
 * @param selector - Optional selector to inspect
570
 * @returns Promise resolving to test controller for chaining
571
 */
572
debug(selector?: string | Selector): Promise<TestController>;
573
```