or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-wdio--globals

A helper utility for importing WebdriverIO global variables directly instead of relying on automatic global injection

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@wdio/globals@9.17.x

To install, run

npx @tessl/cli install tessl/npm-wdio--globals@9.17.0

index.mddocs/

WDIO Globals

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.

Package Information

  • Package Name: @wdio/globals
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm i @wdio/globals --save-dev

Core Imports

import { browser, driver, multiremotebrowser, $, $$, expect } from '@wdio/globals';

For CommonJS:

const { browser, driver, multiremotebrowser, $, $$, expect } = require('@wdio/globals');

For TypeScript projects, add global type support:

{
  "compilerOptions": {
    "types": ["@wdio/globals/types"]
  }
}

Basic Usage

import { browser, $, $$, expect } from '@wdio/globals';

describe('my test', () => {
  it('can interact with page elements', async () => {
    // Navigate to page
    await browser.url('https://example.com');
    
    // Find elements
    const titleElement = await $('h1');
    const allLinks = await $$('a');
    
    // Make assertions
    await expect(titleElement).toHaveText('Welcome');
    await expect(allLinks).toHaveLength(3);
  });
});

Configuration

To use explicit imports, configure your WDIO settings:

// wdio.conf.js
export const config = {
  // Disable automatic global injection
  injectGlobals: false,
  // ... other config
};

Capabilities

Browser Instance

WebdriverIO browser instance proxy that provides access to all WebDriver commands and browser automation capabilities.

export const browser: WebdriverIO.Browser;

Driver Instance

Alias to the browser instance, typically used in mobile testing scenarios.

export const driver: WebdriverIO.Browser;

Multi-Remote Browser

Browser instance for multi-remote sessions where you control multiple browsers simultaneously.

export const multiremotebrowser: WebdriverIO.MultiRemoteBrowser;

Element Selector ($)

Function for selecting a single element from the page using CSS selectors or other locator strategies.

export const $: WebdriverIO.Browser['$'];

Usage Example:

import { $ } from '@wdio/globals';

// Select by CSS selector
const button = await $('button.submit');
const input = await $('#username');

// Use with other locator strategies
const linkByText = await $('=Click here');
const linkByPartialText = await $('*=Click');

Element Selector ($$)

Function for selecting multiple elements from the page that match the given selector.

export const $$: WebdriverIO.Browser['$$'];

Usage Example:

import { $$ } from '@wdio/globals';

// Select multiple elements
const allButtons = await $$('button');
const listItems = await $$('ul li');

// Iterate over elements
for (const item of listItems) {
  const text = await item.getText();
  console.log(text);
}

Expect Assertion Framework

WebdriverIO's enhanced expect assertion framework with async matchers and WebDriver-specific assertions.

export const expect: ExpectWebdriverIO.Expect;

The expect function includes additional properties for asymmetric matchers:

expect.any: (constructor: any) => any;
expect.anything: () => any;
expect.arrayContaining: (sample: any[]) => any;
expect.objectContaining: (sample: Record<string, any>) => any;
expect.stringContaining: (sample: string) => any;
expect.stringMatching: (regexp: string | RegExp) => any;
expect.not: ExpectWebdriverIO.AsymmetricMatchers;
expect.extend: (...args: unknown[]) => any;

Usage Examples:

import { expect, $, browser } from '@wdio/globals';

// Element assertions
await expect($('#title')).toHaveText('Welcome');
await expect($('.error')).not.toBeDisplayed();

// Browser assertions
await expect(browser).toHaveUrl('https://example.com');
await expect(browser).toHaveTitle('Home Page');

// Asymmetric matchers
await expect({
  name: 'John',
  age: 30,
  hobbies: ['reading', 'gaming']
}).toEqual(expect.objectContaining({
  name: expect.stringContaining('Jo'),
  hobbies: expect.arrayContaining(['reading'])
}));

Internal Global Management

Internal utility function for setting global variables within the WDIO testrunner context.

export function _setGlobal(
  key: SupportedGlobals,
  value: any,
  setGlobal?: boolean
): void;

type SupportedGlobals = 'browser' | 'driver' | 'multiremotebrowser' | '$' | '$$' | 'expect';

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.

Types

The package includes comprehensive TypeScript type definitions:

// Global namespace extensions
declare global {
  var _wdioGlobals: Map<SupportedGlobals, any>;
  namespace WebdriverIO {
    interface Browser {}
    interface Element {}
    interface MultiRemoteBrowser {}
  }
}

// Global function declarations for type augmentation
declare function $(
  ...args: Parameters<WebdriverIO.Browser['$']>
): ReturnType<WebdriverIO.Browser['$']>;

declare function $$(
  ...args: Parameters<WebdriverIO.Browser['$$']>
): ReturnType<WebdriverIO.Browser['$$']>;

declare var multiremotebrowser: WebdriverIO.MultiRemoteBrowser;
declare var browser: WebdriverIO.Browser;
declare var driver: WebdriverIO.Browser;
declare var expect: import('expect-webdriverio').Expect;

For browser-runner specific functionality:

declare var wdio: {
  execute: <CommandName>(
    command: CommandName,
    ...args: any[]
  ) => ReturnType<WebdriverIO.Browser[CommandName]>;
  
  executeWithScope: <CommandName>(
    commandName: CommandName,
    scope: string,
    ...args: any[]
  ) => ReturnType<WebdriverIO.Browser[CommandName]>;
};

Error Handling

All exported globals will throw an error if accessed outside the WDIO testrunner context:

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.

This ensures that the globals are only used within the proper WebdriverIO testing environment where the actual browser instances are available.

Architecture

The package uses a proxy-based architecture to defer access to actual WebdriverIO instances:

  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
  2. Proxy Objects: Browser, driver, and multiremotebrowser are implemented as Proxy objects that dynamically access the stored instances
  3. Function Wrappers: The $ and $$ selectors are wrapped functions that access the global Map
  4. Method Binding: All methods are automatically bound to their original context when accessed through the proxies
  5. Cross-Module Compatibility: The architecture ensures compatibility when the same package is loaded as both ESM and CommonJS formats

Peer Dependencies

This package requires the following peer dependencies:

  • expect-webdriverio: ^5.3.4
  • webdriverio: ^9.0.0

Both dependencies are marked as non-optional and must be installed in your project.