or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-control.mddialog-handling.mdelement-interaction.mdelement-selection.mdindex.mdmobile-automation.mdsession-management.mdtesting-utilities.md
tile.json

tessl/npm-webdriverio

Next-gen browser and mobile automation test framework for Node.js

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/webdriverio@9.19.x

To install, run

npx @tessl/cli install tessl/npm-webdriverio@9.19.0

index.mddocs/

WebdriverIO

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.

Package Information

  • Package Name: webdriverio
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install webdriverio

Core Imports

import { remote, attach, multiremote, Key, SevereServiceError } from "webdriverio";

For CommonJS:

const { remote, attach, multiremote, Key, SevereServiceError } = require("webdriverio");

Basic Usage

import { remote } from "webdriverio";

// Create a new browser session
const browser = await remote({
  capabilities: {
    browserName: 'chrome'
  }
});

// Navigate to a page
await browser.url('https://example.com');

// Find and interact with elements
const element = await browser.$('#my-element');
await element.click();
await element.setValue('Hello World');

// Get element text
const text = await element.getText();
console.log(text);

// Take a screenshot
await browser.saveScreenshot('./screenshot.png');

// Close the session
await browser.deleteSession();

Architecture

WebdriverIO is built around several key components:

  • Session Management: Core functions for creating and managing WebDriver sessions
  • Element Selection: Powerful selector engine supporting CSS, XPath, React components, and custom strategies
  • Browser Control: Comprehensive browser automation including navigation, window management, and JavaScript execution
  • Element Interaction: Full spectrum of element manipulation from clicks to complex gestures
  • Testing Utilities: Built-in mocking, debugging, and performance testing capabilities
  • Mobile Support: Complete mobile automation support through Appium integration
  • Command Extension: Plugin system for adding custom commands and functionality

Capabilities

Session Management

Core session creation and management functionality for initializing WebDriver connections and managing browser instances.

function remote(params: Capabilities.WebdriverIOConfig, remoteModifier?: Function): Promise<WebdriverIO.Browser>;
function attach(attachOptions: AttachOptions): Promise<WebdriverIO.Browser>;
function multiremote(params: Capabilities.RequestedMultiremoteCapabilities, options?: {automationProtocol?: string}): Promise<WebdriverIO.MultiRemoteBrowser>;

Session Management

Element Selection

Comprehensive element finding and selection methods supporting CSS selectors, XPath, React components, Shadow DOM, and custom selector strategies.

// Browser-level selectors
$(selector: Selector): Promise<WebdriverIO.Element>;
$$(selector: Selector): Promise<WebdriverIO.Element[]>;
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;
react$(selector: string): Promise<WebdriverIO.Element>;

// Element-level selectors (chaining)
element.$(selector: Selector): Promise<WebdriverIO.Element>;
element.shadow$(selector: string): Promise<WebdriverIO.Element>;

Element Selection

Element Interaction

Complete element interaction capabilities including clicks, input, drag-and-drop, touch gestures, and state checking.

// Interaction methods
click(options?: ClickOptions): Promise<void>;
setValue(value: string | number): Promise<void>;
dragAndDrop(target: WebdriverIO.Element | {x: number, y: number}): Promise<void>;

// State checking
isDisplayed(): Promise<boolean>;
isEnabled(): Promise<boolean>;
waitForClickable(options?: object): Promise<boolean>;

Element Interaction

Browser Control

Browser-level automation including navigation, window management, JavaScript execution, cookie handling, and file operations.

// Navigation
url(path: string, options?: UrlCommandOptions): Promise<WebdriverIO.Request | void>;
newWindow(url: string, options?: object): Promise<void>;

// JavaScript execution
execute(script: string | Function, ...args: any[]): Promise<any>;

// File operations
saveScreenshot(filename: string): Promise<void>;
uploadFile(localPath: string): Promise<string>;

Browser Control

Testing Utilities

Built-in testing, debugging, and performance utilities including network mocking, CPU/network throttling, and interactive debugging.

// Mocking
mock(url: string, options?: object): Promise<WebdriverIO.Mock>;

// Performance testing
throttleCPU(rate: number): Promise<void>;
throttleNetwork(conditions: object): Promise<void>;

// Debugging
debug(): Promise<void>;
pause(milliseconds: number): Promise<void>;

Testing Utilities

Mobile Automation

Complete mobile automation support through Appium integration, including touch gestures, app management, and context switching.

// Touch gestures
touchAction(action: object): Promise<void>;
swipe(xStart: number, yStart: number, xEnd: number, yEnd: number): Promise<void>;

// App management
getContext(): Promise<string>;
switchContext(context: string): Promise<void>;

Mobile Automation

Dialog Handling

Complete JavaScript alert, confirmation, and prompt dialog handling for managing browser dialogs during test automation.

// Alert management
acceptAlert(): Promise<void>;
dismissAlert(): Promise<void>;
getAlertText(): Promise<string>;
sendAlertText(text: string): Promise<void>;

// Dialog state detection
isAlertOpen(): Promise<boolean>;
waitForAlert(options?: object): Promise<void>;

Dialog Handling

Core Types

interface WebdriverIO.Browser {
  // Browser instance with all browser commands
  sessionId: string;
  capabilities: object;
  config: object;
}

interface WebdriverIO.Element {
  // Element instance with all element commands
  selector: string;
  elementId: string;
  parent: WebdriverIO.Browser | WebdriverIO.Element;
}

interface WebdriverIO.MultiRemoteBrowser {
  // Multi-browser instance for parallel testing
  [instanceName: string]: WebdriverIO.Browser;
}

type Selector = string | Function | object;

interface ClickOptions {
  button: 'left' | 'middle' | 'right' | number;
  x: number;
  y: number;
  duration: number;
  skipRelease: boolean;
}

interface AttachOptions {
  sessionId: string;
  isW3C?: boolean;
  commandTimeout?: number;
}

class SevereServiceError extends Error {
  name: 'SevereServiceError';
}

const Key: {
  Ctrl: string;
  NULL: string;
  Cancel: string;
  Help: string;
  Backspace: string;
  Tab: string;
  Clear: string;
  Return: string;
  Enter: string;
  Shift: string;
  Control: string;
  Alt: string;
  Pause: string;
  Escape: string;
  Space: string;
  PageUp: string;
  PageDown: string;
  End: string;
  Home: string;
  ArrowLeft: string;
  ArrowUp: string;
  ArrowRight: string;
  ArrowDown: string;
  Insert: string;
  Delete: string;
  Semicolon: string;
  Equals: string;
  Numpad0: string;
  Numpad1: string;
  Numpad2: string;
  Numpad3: string;
  Numpad4: string;
  Numpad5: string;
  Numpad6: string;
  Numpad7: string;
  Numpad8: string;
  Numpad9: string;
  Multiply: string;
  Add: string;
  Separator: string;
  Subtract: string;
  Decimal: string;
  Divide: string;
  F1: string;
  F2: string;
  F3: string;
  F4: string;
  F5: string;
  F6: string;
  F7: string;
  F8: string;
  F9: string;
  F10: string;
  F11: string;
  F12: string;
  Command: string;
  ZenkakuHankaku: string;
};