0
# WDIO Globals
1
2
WDIO Globals provides explicit imports for WebdriverIO global variables, allowing developers to use typed imports instead of relying on automatic global injection. This enables better IDE support, explicit dependency management, and compatibility with modern JavaScript/TypeScript development patterns.
3
4
## Package Information
5
6
- **Package Name**: @wdio/globals
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm i @wdio/globals --save-dev`
10
11
## Core Imports
12
13
```typescript
14
import { browser, driver, multiremotebrowser, $, $$, expect } from '@wdio/globals';
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { browser, driver, multiremotebrowser, $, $$, expect } = require('@wdio/globals');
21
```
22
23
For TypeScript projects, add global type support:
24
25
```json
26
{
27
"compilerOptions": {
28
"types": ["@wdio/globals/types"]
29
}
30
}
31
```
32
33
## Basic Usage
34
35
```typescript
36
import { browser, $, $$, expect } from '@wdio/globals';
37
38
describe('my test', () => {
39
it('can interact with page elements', async () => {
40
// Navigate to page
41
await browser.url('https://example.com');
42
43
// Find elements
44
const titleElement = await $('h1');
45
const allLinks = await $$('a');
46
47
// Make assertions
48
await expect(titleElement).toHaveText('Welcome');
49
await expect(allLinks).toHaveLength(3);
50
});
51
});
52
```
53
54
## Configuration
55
56
To use explicit imports, configure your WDIO settings:
57
58
```javascript
59
// wdio.conf.js
60
export const config = {
61
// Disable automatic global injection
62
injectGlobals: false,
63
// ... other config
64
};
65
```
66
67
## Capabilities
68
69
### Browser Instance
70
71
WebdriverIO browser instance proxy that provides access to all WebDriver commands and browser automation capabilities.
72
73
```typescript { .api }
74
export const browser: WebdriverIO.Browser;
75
```
76
77
### Driver Instance
78
79
Alias to the browser instance, typically used in mobile testing scenarios.
80
81
```typescript { .api }
82
export const driver: WebdriverIO.Browser;
83
```
84
85
### Multi-Remote Browser
86
87
Browser instance for multi-remote sessions where you control multiple browsers simultaneously.
88
89
```typescript { .api }
90
export const multiremotebrowser: WebdriverIO.MultiRemoteBrowser;
91
```
92
93
### Element Selector ($)
94
95
Function for selecting a single element from the page using CSS selectors or other locator strategies.
96
97
```typescript { .api }
98
export const $: WebdriverIO.Browser['$'];
99
```
100
101
**Usage Example:**
102
103
```typescript
104
import { $ } from '@wdio/globals';
105
106
// Select by CSS selector
107
const button = await $('button.submit');
108
const input = await $('#username');
109
110
// Use with other locator strategies
111
const linkByText = await $('=Click here');
112
const linkByPartialText = await $('*=Click');
113
```
114
115
### Element Selector ($$)
116
117
Function for selecting multiple elements from the page that match the given selector.
118
119
```typescript { .api }
120
export const $$: WebdriverIO.Browser['$$'];
121
```
122
123
**Usage Example:**
124
125
```typescript
126
import { $$ } from '@wdio/globals';
127
128
// Select multiple elements
129
const allButtons = await $$('button');
130
const listItems = await $$('ul li');
131
132
// Iterate over elements
133
for (const item of listItems) {
134
const text = await item.getText();
135
console.log(text);
136
}
137
```
138
139
### Expect Assertion Framework
140
141
WebdriverIO's enhanced expect assertion framework with async matchers and WebDriver-specific assertions.
142
143
```typescript { .api }
144
export const expect: ExpectWebdriverIO.Expect;
145
```
146
147
The expect function includes additional properties for asymmetric matchers:
148
149
```typescript { .api }
150
expect.any: (constructor: any) => any;
151
expect.anything: () => any;
152
expect.arrayContaining: (sample: any[]) => any;
153
expect.objectContaining: (sample: Record<string, any>) => any;
154
expect.stringContaining: (sample: string) => any;
155
expect.stringMatching: (regexp: string | RegExp) => any;
156
expect.not: ExpectWebdriverIO.AsymmetricMatchers;
157
expect.extend: (...args: unknown[]) => any;
158
```
159
160
**Usage Examples:**
161
162
```typescript
163
import { expect, $, browser } from '@wdio/globals';
164
165
// Element assertions
166
await expect($('#title')).toHaveText('Welcome');
167
await expect($('.error')).not.toBeDisplayed();
168
169
// Browser assertions
170
await expect(browser).toHaveUrl('https://example.com');
171
await expect(browser).toHaveTitle('Home Page');
172
173
// Asymmetric matchers
174
await expect({
175
name: 'John',
176
age: 30,
177
hobbies: ['reading', 'gaming']
178
}).toEqual(expect.objectContaining({
179
name: expect.stringContaining('Jo'),
180
hobbies: expect.arrayContaining(['reading'])
181
}));
182
```
183
184
### Internal Global Management
185
186
Internal utility function for setting global variables within the WDIO testrunner context.
187
188
```typescript { .api }
189
export function _setGlobal(
190
key: SupportedGlobals,
191
value: any,
192
setGlobal?: boolean
193
): void;
194
195
type SupportedGlobals = 'browser' | 'driver' | 'multiremotebrowser' | '$' | '$$' | 'expect';
196
```
197
198
**Note:** This function is marked as private (prefixed with underscore) and is intended for internal use by the WDIO testrunner. It should not be used directly in test code.
199
200
## Types
201
202
The package includes comprehensive TypeScript type definitions:
203
204
```typescript { .api }
205
// Global namespace extensions
206
declare global {
207
var _wdioGlobals: Map<SupportedGlobals, any>;
208
namespace WebdriverIO {
209
interface Browser {}
210
interface Element {}
211
interface MultiRemoteBrowser {}
212
}
213
}
214
215
// Global function declarations for type augmentation
216
declare function $(
217
...args: Parameters<WebdriverIO.Browser['$']>
218
): ReturnType<WebdriverIO.Browser['$']>;
219
220
declare function $$(
221
...args: Parameters<WebdriverIO.Browser['$$']>
222
): ReturnType<WebdriverIO.Browser['$$']>;
223
224
declare var multiremotebrowser: WebdriverIO.MultiRemoteBrowser;
225
declare var browser: WebdriverIO.Browser;
226
declare var driver: WebdriverIO.Browser;
227
declare var expect: import('expect-webdriverio').Expect;
228
```
229
230
For browser-runner specific functionality:
231
232
```typescript { .api }
233
declare var wdio: {
234
execute: <CommandName>(
235
command: CommandName,
236
...args: any[]
237
) => ReturnType<WebdriverIO.Browser[CommandName]>;
238
239
executeWithScope: <CommandName>(
240
commandName: CommandName,
241
scope: string,
242
...args: any[]
243
) => ReturnType<WebdriverIO.Browser[CommandName]>;
244
};
245
```
246
247
## Error Handling
248
249
All exported globals will throw an error if accessed outside the WDIO testrunner context:
250
251
```
252
Error: No browser instance registered. Don't import @wdio/globals outside of the WDIO testrunner context. Or you have two different "@wdio/globals" packages installed.
253
```
254
255
This ensures that the globals are only used within the proper WebdriverIO testing environment where the actual browser instances are available.
256
257
## Architecture
258
259
The package uses a proxy-based architecture to defer access to actual WebdriverIO instances:
260
261
1. **Shared Global Map**: All instances are stored in a global Map (`globalThis._wdioGlobals`) that can be accessed across both ESM and CommonJS module systems
262
2. **Proxy Objects**: Browser, driver, and multiremotebrowser are implemented as Proxy objects that dynamically access the stored instances
263
3. **Function Wrappers**: The $ and $$ selectors are wrapped functions that access the global Map
264
4. **Method Binding**: All methods are automatically bound to their original context when accessed through the proxies
265
5. **Cross-Module Compatibility**: The architecture ensures compatibility when the same package is loaded as both ESM and CommonJS formats
266
267
## Peer Dependencies
268
269
This package requires the following peer dependencies:
270
271
- `expect-webdriverio`: ^5.3.4
272
- `webdriverio`: ^9.0.0
273
274
Both dependencies are marked as non-optional and must be installed in your project.