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
```