0
# WebdriverIO
1
2
WebdriverIO is a comprehensive browser and mobile automation test framework for Node.js that supports e2e, unit, and component testing. It provides WebDriver, WebDriver BiDi, and Appium automation technology integration with support for popular BDD/TDD frameworks like Mocha, Jasmine, and Cucumber.
3
4
## Package Information
5
6
- **Package Name**: webdriverio
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install webdriverio`
10
11
## Core Imports
12
13
```typescript
14
import { remote, attach, multiremote, Key, SevereServiceError } from "webdriverio";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { remote, attach, multiremote, Key, SevereServiceError } = require("webdriverio");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { remote } from "webdriverio";
27
28
// Create a new browser session
29
const browser = await remote({
30
capabilities: {
31
browserName: 'chrome'
32
}
33
});
34
35
// Navigate to a page
36
await browser.url('https://example.com');
37
38
// Find and interact with elements
39
const element = await browser.$('#my-element');
40
await element.click();
41
await element.setValue('Hello World');
42
43
// Get element text
44
const text = await element.getText();
45
console.log(text);
46
47
// Take a screenshot
48
await browser.saveScreenshot('./screenshot.png');
49
50
// Close the session
51
await browser.deleteSession();
52
```
53
54
## Architecture
55
56
WebdriverIO is built around several key components:
57
58
- **Session Management**: Core functions for creating and managing WebDriver sessions
59
- **Element Selection**: Powerful selector engine supporting CSS, XPath, React components, and custom strategies
60
- **Browser Control**: Comprehensive browser automation including navigation, window management, and JavaScript execution
61
- **Element Interaction**: Full spectrum of element manipulation from clicks to complex gestures
62
- **Testing Utilities**: Built-in mocking, debugging, and performance testing capabilities
63
- **Mobile Support**: Complete mobile automation support through Appium integration
64
- **Command Extension**: Plugin system for adding custom commands and functionality
65
66
## Capabilities
67
68
### Session Management
69
70
Core session creation and management functionality for initializing WebDriver connections and managing browser instances.
71
72
```typescript { .api }
73
function remote(params: Capabilities.WebdriverIOConfig, remoteModifier?: Function): Promise<WebdriverIO.Browser>;
74
function attach(attachOptions: AttachOptions): Promise<WebdriverIO.Browser>;
75
function multiremote(params: Capabilities.RequestedMultiremoteCapabilities, options?: {automationProtocol?: string}): Promise<WebdriverIO.MultiRemoteBrowser>;
76
```
77
78
[Session Management](./session-management.md)
79
80
### Element Selection
81
82
Comprehensive element finding and selection methods supporting CSS selectors, XPath, React components, Shadow DOM, and custom selector strategies.
83
84
```typescript { .api }
85
// Browser-level selectors
86
$(selector: Selector): Promise<WebdriverIO.Element>;
87
$$(selector: Selector): Promise<WebdriverIO.Element[]>;
88
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;
89
react$(selector: string): Promise<WebdriverIO.Element>;
90
91
// Element-level selectors (chaining)
92
element.$(selector: Selector): Promise<WebdriverIO.Element>;
93
element.shadow$(selector: string): Promise<WebdriverIO.Element>;
94
```
95
96
[Element Selection](./element-selection.md)
97
98
### Element Interaction
99
100
Complete element interaction capabilities including clicks, input, drag-and-drop, touch gestures, and state checking.
101
102
```typescript { .api }
103
// Interaction methods
104
click(options?: ClickOptions): Promise<void>;
105
setValue(value: string | number): Promise<void>;
106
dragAndDrop(target: WebdriverIO.Element | {x: number, y: number}): Promise<void>;
107
108
// State checking
109
isDisplayed(): Promise<boolean>;
110
isEnabled(): Promise<boolean>;
111
waitForClickable(options?: object): Promise<boolean>;
112
```
113
114
[Element Interaction](./element-interaction.md)
115
116
### Browser Control
117
118
Browser-level automation including navigation, window management, JavaScript execution, cookie handling, and file operations.
119
120
```typescript { .api }
121
// Navigation
122
url(path: string, options?: UrlCommandOptions): Promise<WebdriverIO.Request | void>;
123
newWindow(url: string, options?: object): Promise<void>;
124
125
// JavaScript execution
126
execute(script: string | Function, ...args: any[]): Promise<any>;
127
128
// File operations
129
saveScreenshot(filename: string): Promise<void>;
130
uploadFile(localPath: string): Promise<string>;
131
```
132
133
[Browser Control](./browser-control.md)
134
135
### Testing Utilities
136
137
Built-in testing, debugging, and performance utilities including network mocking, CPU/network throttling, and interactive debugging.
138
139
```typescript { .api }
140
// Mocking
141
mock(url: string, options?: object): Promise<WebdriverIO.Mock>;
142
143
// Performance testing
144
throttleCPU(rate: number): Promise<void>;
145
throttleNetwork(conditions: object): Promise<void>;
146
147
// Debugging
148
debug(): Promise<void>;
149
pause(milliseconds: number): Promise<void>;
150
```
151
152
[Testing Utilities](./testing-utilities.md)
153
154
### Mobile Automation
155
156
Complete mobile automation support through Appium integration, including touch gestures, app management, and context switching.
157
158
```typescript { .api }
159
// Touch gestures
160
touchAction(action: object): Promise<void>;
161
swipe(xStart: number, yStart: number, xEnd: number, yEnd: number): Promise<void>;
162
163
// App management
164
getContext(): Promise<string>;
165
switchContext(context: string): Promise<void>;
166
```
167
168
[Mobile Automation](./mobile-automation.md)
169
170
### Dialog Handling
171
172
Complete JavaScript alert, confirmation, and prompt dialog handling for managing browser dialogs during test automation.
173
174
```typescript { .api }
175
// Alert management
176
acceptAlert(): Promise<void>;
177
dismissAlert(): Promise<void>;
178
getAlertText(): Promise<string>;
179
sendAlertText(text: string): Promise<void>;
180
181
// Dialog state detection
182
isAlertOpen(): Promise<boolean>;
183
waitForAlert(options?: object): Promise<void>;
184
```
185
186
[Dialog Handling](./dialog-handling.md)
187
188
## Core Types
189
190
```typescript { .api }
191
interface WebdriverIO.Browser {
192
// Browser instance with all browser commands
193
sessionId: string;
194
capabilities: object;
195
config: object;
196
}
197
198
interface WebdriverIO.Element {
199
// Element instance with all element commands
200
selector: string;
201
elementId: string;
202
parent: WebdriverIO.Browser | WebdriverIO.Element;
203
}
204
205
interface WebdriverIO.MultiRemoteBrowser {
206
// Multi-browser instance for parallel testing
207
[instanceName: string]: WebdriverIO.Browser;
208
}
209
210
type Selector = string | Function | object;
211
212
interface ClickOptions {
213
button: 'left' | 'middle' | 'right' | number;
214
x: number;
215
y: number;
216
duration: number;
217
skipRelease: boolean;
218
}
219
220
interface AttachOptions {
221
sessionId: string;
222
isW3C?: boolean;
223
commandTimeout?: number;
224
}
225
226
class SevereServiceError extends Error {
227
name: 'SevereServiceError';
228
}
229
230
const Key: {
231
Ctrl: string;
232
NULL: string;
233
Cancel: string;
234
Help: string;
235
Backspace: string;
236
Tab: string;
237
Clear: string;
238
Return: string;
239
Enter: string;
240
Shift: string;
241
Control: string;
242
Alt: string;
243
Pause: string;
244
Escape: string;
245
Space: string;
246
PageUp: string;
247
PageDown: string;
248
End: string;
249
Home: string;
250
ArrowLeft: string;
251
ArrowUp: string;
252
ArrowRight: string;
253
ArrowDown: string;
254
Insert: string;
255
Delete: string;
256
Semicolon: string;
257
Equals: string;
258
Numpad0: string;
259
Numpad1: string;
260
Numpad2: string;
261
Numpad3: string;
262
Numpad4: string;
263
Numpad5: string;
264
Numpad6: string;
265
Numpad7: string;
266
Numpad8: string;
267
Numpad9: string;
268
Multiply: string;
269
Add: string;
270
Separator: string;
271
Subtract: string;
272
Decimal: string;
273
Divide: string;
274
F1: string;
275
F2: string;
276
F3: string;
277
F4: string;
278
F5: string;
279
F6: string;
280
F7: string;
281
F8: string;
282
F9: string;
283
F10: string;
284
F11: string;
285
F12: string;
286
Command: string;
287
ZenkakuHankaku: string;
288
};
289
```