WebdriverIO

https://webdriver.io/docs/
Admin
WebdriverIO is a Node.js automation framework that provides a JavaScript API for controlling...
Tokens:1,158,549
Snippets:9,504
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Quickstart: Setup interceptor and assert requests

Source: https://webdriver.io/docs/wdio-intercept-service

Example usage of the wdio-intercept-service. It captures AJAX calls, sets expectations for GET and POST requests with status codes, and validates them after clicking a button.

```javascript
browser.url('http://foo.bar');
browser.setupInterceptor(); // capture ajax calls
browser.expectRequest('GET', '/api/foo', 200); // expect GET request to /api/foo with 200 statusCode
browser.expectRequest('POST', '/api/foo', 400); // expect POST request to /api/foo with 400 statusCode
browser.expectRequest('GET', /\/api\/foo/, 200); // can validate a URL with regex, too
browser.click('#button'); // button that initiates ajax request
browser.pause(1000); // maybe wait a bit until request is finished
browser.assertRequests(); // validate the requests
```

--------------------------------

### Run Python web_form example

Source: https://webdriver.io/docs/devtools/selenium

Runs the Python plain-script example that demonstrates the three-line setup. Requires installing the adapter and building the workspace first.

```bash
pnpm demo:python
```

--------------------------------

### Run appium-installer

Source: https://webdriver.io/docs/appium

Use this command to start the interactive setup process for Appium environments. It launches the appium-installer toolkit which guides you through the configuration.

```sh
$ npx appium-installer
```

--------------------------------

### installAddOn example

Source: https://webdriver.io/docs/api/gecko

Example showing how to read an extension file and install it as a base64 string, with the temporary flag set to false.

```javascript
// Create a buffer of the add on .zip file
const extension = await fs.promises.readFile('/path/to/extension.zip')
// Load extension in Firefox
const id = await browser.installAddOn(extension.toString('base64'), false);
```

--------------------------------

### Set up the project with pnpm

Source: https://webdriver.io/docs/contribute

Installs dependencies and runs the setup script. The setup script cleans build artifacts and compiles all sub-packages.

```sh
$ pnpm install
$ pnpm run setup
```

--------------------------------

### Install the skill to a project with --install flag

Source: https://webdriver.io/docs/session-commands

Use the `--install <value>` flag to write the skill to `.agents/skills/wdio-session/SKILL.md` or the specified directory. The example shows installing to the current directory with `--install .`.

```sh
# Print the skill
npx wdio session skill

# Add it to this project
npx wdio session skill --install .
```

--------------------------------

### get command examples

Source: https://webdriver.io/docs/session-commands

Examples of using the get command to read text, URL, value for shell variable, attribute, and count.

```sh
# Text of a ref
npx wdio session get text e1

# Current URL
npx wdio session get url

# Only the value, for a shell variable
url=$(npx wdio session get url -q)

# href of a link
npx wdio session get attr e3 href

# How many elements match
npx wdio session get count "aria/Remove"
```

--------------------------------

### Install extension with browser.installExtension()

Source: https://webdriver.io/docs/api/browser/installExtension

Use this command to install a browser extension. The example shows the basic usage without arguments.

```javascript
await browser.installExtension()
```

--------------------------------

### uninstallAddOn Example

Source: https://webdriver.io/docs/api/gecko

Shows a complete workflow: reading an extension file, installing it, and then uninstalling it by ID.

```javascript
// Create a buffer of the add on .zip file
const extension = await fs.promises.readFile('/path/to/extension.zip')
// Load extension in Firefox
const id = await browser.installAddOn(extension.toString('base64'), false);
// ...
await browser.uninstallAddOn(id)
```

--------------------------------

### Example: uninstallExtension.js

Source: https://webdriver.io/docs/api/browser/uninstallExtension

Demonstrates installing an extension from './dist' and then uninstalling it using the returned ID.

```javascript
const id = await browser.installExtension('./dist')
await browser.uninstallExtension(id)
```

--------------------------------

### Run Python login example

Source: https://webdriver.io/docs/devtools/selenium

Runs a longer Python script showing navigation, form fill, and assertions. Requires the same setup as the web_form example.

```bash
pnpm demo:python:login
```

--------------------------------

### Check Screen Example

Source: https://webdriver.io/docs/visual-testing/test-output

Checks the entire visible screen area with a tag name. The example shows a change in button text from 'Get Started' to 'Getting Started!' being detected.

```javascript
await browser.checkScreen("example-page-tag")
```

--------------------------------

### Initialize WebdriverIO with bun for new project

Source: https://webdriver.io/docs/gettingstarted

Run to create a new project at the specified path and start the WebdriverIO configuration wizard using bun.

```sh
bun create wdio@latest ./path/to/new/project
```

--------------------------------

### Check Element Example

Source: https://webdriver.io/docs/visual-testing/test-output

Checks a specific element on the page using a CSS selector and a tag name. The example shows a change in button text from 'Get Started' to 'Getting Started!' being detected.

```javascript
await browser.checkElement("#__docusaurus_skipToContent_fallback > header > div > div.buttons_pzbO > a:nth-child(1)", "example-element-tag")
```

--------------------------------

### Check Full Page Screen Example

Source: https://webdriver.io/docs/visual-testing/test-output

Checks the entire page, including content below the fold, with a tag name. The example shows a change in button text from 'Get Started' to 'Getting Started!' being detected.

```javascript
await browser.checkFullPageScreen("full-page-tag")
```

--------------------------------

### Install @wdio/devtools-service for WebdriverIO

Source: https://webdriver.io/docs/wdio-devtools-service

Install the DevTools service adapter for WebdriverIO as a dev dependency. This is the first step in the quick start setup.

```bash
npm install @wdio/devtools-service --save-dev   # WebdriverIO (Nightwatch / Selenium below)
```

--------------------------------

### Examples for `npx wdio session helpers`

Source: https://webdriver.io/docs/session-commands

Shows how to list helpers and their commands, and how to pick up edits to a helper using the `--reload` flag.

```sh
# List helpers and the commands they add
npx wdio session helpers
```

```sh
# Pick up edits to a helper
npx wdio session helpers --reload
```

--------------------------------

### start_session examples for various platforms and providers

Source: https://webdriver.io/docs/mcp/tools

These examples show how to start sessions for local browsers, iOS simulators, Android devices, and cloud providers like BrowserStack, Sauce Labs, TestMu, and TestingBot. They also include configurations for tunnels and attaching to an existing Chrome instance.

```javascript
// Local Chrome browser
start_session({ platform: "browser", browser: "chrome" })
```

```javascript
// iOS simulator
start_session({ platform: "ios", deviceName: "iPhone 16", platformVersion: "18.0", appPath: "/path/to/app.app" })
```

```javascript
// BrowserStack Android
start_session({ platform: "android", provider: "browserstack", deviceName: "Samsung Galaxy S24", app: "bs://abc123" })
```

```javascript
// Sauce Labs iOS
start_session({ platform: "ios", provider: "saucelabs", deviceName: "iPhone 15", platformVersion: "17.0", app: "storage:filename=MyApp.ipa" })
```

```javascript
// TestMu browser
start_session({ platform: "browser", provider: "testmu", browser: "chrome", os: "Windows", osVersion: "11" })
```

```javascript
// TestingBot browser
start_session({ platform: "browser", provider: "testingbot", browser: "chrome", os: "Windows", osVersion: "11" })
```

```javascript
// Cloud provider with tunnel
start_session({ platform: "browser", provider: "browserstack", browser: "chrome", tunnel: true })
```

```javascript
// Attach to existing Chrome (after launch_chrome)
start_session({ platform: "browser", browser: "chrome", attach: true })
```

--------------------------------

### Start the OCR CLI Wizard with npx ocr-service

Source: https://webdriver.io/docs/ocr-testing/cli-wizard

Run this command in a terminal to launch the interactive OCR CLI wizard. Requires the @wdio/ocr-service package to be installed as a dependency. The wizard starts from the current folder and guides through file selection, haystack, and advanced mode.

```sh
npx ocr-service
```

--------------------------------

### Example output with preface

Source: https://webdriver.io/docs/spec-reporter

Example output when showPreface is true (default), with each line prefixed by the preface.

```text
[loremipsum 50 Windows 10 #0-0] Running: loremipsum (v50) on Windows 10
[loremipsum 50 Windows 10 #0-0] Session ID: foobar
[loremipsum 50 Windows 10 #0-0]
[loremipsum 50 Windows 10 #0-0] » foo/bar/loo.e2e.js
[loremipsum 50 Windows 10 #0-0] Foo test
[loremipsum 50 Windows 10 #0-0]    green ✓ foo
[loremipsum 50 Windows 10 #0-0]    green ✓ bar
[loremipsum 50 Windows 10 #0-0]
[loremipsum 50 Windows 10 #0-0] » bar/foo/loo.e2e.js
[loremipsum 50 Windows 10 #0-0] Bar test
[loremipsum 50 Windows 10 #0-0]    green ✓ some test
[loremipsum 50 Windows 10 #0-0]    red ✖ a failed test
[loremipsum 50 Windows 10 #0-0]    red ✖ a failed test with no stack
[loremipsum 50 Windows 10 #0-0]
```

--------------------------------

### Examples for `npx wdio session logs`

Source: https://webdriver.io/docs/session-commands

Two examples: get errors caused by a click, and get recent entries without advancing the read cursor using --peek.

```sh
# Errors caused by a click
npx wdio session click e4 && npx wdio session logs --errors
```

```sh
# Recent entries, keep them for the next call
npx wdio session logs --since 30s --peek
```

--------------------------------

### open command examples

Source: https://webdriver.io/docs/session-commands

Multiple examples of using the `open` command for different targets: local Chrome, Firefox with a visible window, Android app, iOS app, Electron app, config file, and cloud provider. Each example shows the exact command to run.

```sh
# Open headless Chrome on a local app
npx wdio session open chrome http://localhost:3000
```

```sh
# Open Firefox with a visible window
npx wdio session open firefox http://localhost:3000 --headed
```

```sh
# Open an Android app through Appium
npx wdio session open android --app ./app.apk
```

```sh
# Open an installed iOS app
npx wdio session open ios --bundle-id com.example.shop
```

```sh
# Open an Electron app
npx wdio session open electron ./main.js
```

```sh
# Open the first capability of a config
npx wdio session open ./wdio.conf.ts 0
```

```sh
# Open Chrome in a cloud grid
npx wdio session open chrome https://example.com --provider browserstack
```

--------------------------------

### windows command examples

Source: https://webdriver.io/docs/session-commands

Examples of listing windows and switching to the second window.

```sh
# List windows
npx wdio session windows

# Switch to the second window
npx wdio session windows switch 1
```

--------------------------------

### launchChromeApp example with Chrome extension installation

Source: https://webdriver.io/docs/api/chromium

Example showing how to launch a Chrome app after installing it via goog:chromeOptions. The extension must be a base64-encoded packed Chrome app (.crx). Note: the example contains a syntax error with an extra closing parenthesis.

```javascript
import fs from 'fs'
const browser = remote({
    capabilities: {
        browserName: 'chrome',
        'goog:chromeOptions': {
            // Install upon starting browser in order to launch it
            extensions: [
              // Entry should be a base64-encoded packed Chrome app (.crx)
              fs.readFileSync('/absolute/path/app.crx').toString('base64')
            ]
        }
    }
});
browser.launchChromeApp('aohghmighlieiainnegkcijnfilokake')); // Google Docs (https://chrome.google.com/webstore/detail/docs/aohghmighlieiainnegkcijnfilokake)
```

--------------------------------

### Contributor Quick Start Commands

Source: https://webdriver.io/docs/wdio-tauri-service

Commands to clone the repository, install dependencies with pnpm, run tests, and submit a pull request. Used for setting up the development environment for contributors.

```bash
# Clone and install
git clone https://github.com/webdriverio/desktop-mobile.git
cd desktop-mobile
pnpm install

# Make your changes
# ...

# Run tests
pnpm test

# Submit a pull request
```

--------------------------------

### Install Chromedriver via npm

Source: https://webdriver.io/docs/driverbinaries

Installs Chromedriver globally using npm. After installation, start it with 'chromedriver --port=4444 --verbose'.

```bash
npm install -g chromedriver
```

--------------------------------

### Install wdio-nuxt-service as dev dependency

Source: https://webdriver.io/docs/wdio-nuxt-service

Install the service on an existing WebdriverIO setup using npm.

```bash
npm install wdio-nuxt-service --save-dev
```

--------------------------------

### webExtensionInstall usage

Source: https://webdriver.io/docs/api/webdriverBidi

Usage example for the webExtensionInstall command, which sends the 'webExtension.install' command method.

```javascript
await browser.webExtensionInstall(params)
```

--------------------------------

### Clone and test the desktop-mobile repository

Source: https://webdriver.io/docs/wdio-dioxus-service

Quick start commands for contributors: clone the repository, install dependencies with pnpm, run tests, and submit a pull request.

```bash
# Clone and install
git clone https://github.com/webdriverio/desktop-mobile.git
cd desktop-mobile
pnpm install

# Make your changes
# ...

# Run tests
pnpm test

# Submit a pull request

```

--------------------------------

### Example: Get plugin wrapper buttons with custom$$

Source: https://webdriver.io/docs/api/element/custom$$

Example from example.js that adds a custom locator strategy 'myStrat' and uses custom$$ to get all plugin wrapper buttons. Logs the length of the resulting array (4).

```javascript
it('should get all the plugin wrapper buttons', async () => {
    await browser.url('https://webdriver.io')
    await browser.addLocatorStrategy('myStrat', (selector) => {
        return document.querySelectorAll(selector)
    })

    const pluginRowBlock = await browser.custom$('myStrat', '.pluginRowBlock')
    const pluginWrapper = await pluginRowBlock.custom$$('myStrat', '.pluginWrapper')

    console.log(pluginWrapper.length) // 4
})
```

--------------------------------

### Get Performance Logs Example

Source: https://webdriver.io/docs/api/saucelabs

Example of retrieving performance logs with getPageLogs, requiring the capturePerformance capability.

```javascript
// Get Performance Logs (needs capturePerformance capability see: https://docs.saucelabs.com/performance/transitions/#setting-performance-capabilities
console.log(browser.getPageLogs('sauce:performance'));
/**
 * outputs:
 * {
 *   "speedIndex": 1472.023,
 *   "timeToFirstInteractive": 1243.214,
 *   "firstMeaningfulPaint": 892.643,
 *   ...
 * }
 */
```

--------------------------------

### Examples for `npx wdio session is`

Source: https://webdriver.io/docs/session-commands

Two examples: check visibility of element `e1` and check if a button labeled 'Place order' is enabled using an aria selector.

```sh
# Print true or false
npx wdio session is visible e1
```

```sh
# Check a button by its label
npx wdio session is enabled "aria/Place order"
```

--------------------------------

### Get Network Logs Example

Source: https://webdriver.io/docs/api/saucelabs

Example of retrieving network logs with getPageLogs, showing the output structure.

```javascript
// Get Network Logs
console.log(browser.getPageLogs('sauce:network'));
/**
 * outputs:
 * [{
 *   "url": "https://app.saucelabs.com/dashboard",
 *   "statusCode": 200,
 *   "method": "GET",
 *   "requestHeaders": {
 *     ...
 *   },
 *   "responseHeaders": {
 *     ...
 *   },
 *   "timing": {
 *     ...
 *   }
 * }, {,
 *   ...
 * }]
 */
```

--------------------------------

### Install @wdio/ai-service and dependencies

Source: https://webdriver.io/docs/ai-steps

Install the service and the LangChain package for your model provider. This example uses @langchain/anthropic and zod.

```sh
npm install --save-dev @wdio/ai-service @langchain/anthropic zod
```

--------------------------------

### Initialize WebdriverIO with npm for new project

Source: https://webdriver.io/docs/gettingstarted

Run to create a new project at the specified path and start the WebdriverIO configuration wizard.

```sh
npm init wdio@latest ./path/to/new/project
```

--------------------------------

### Record command examples

Source: https://webdriver.io/docs/session-commands

Examples for starting and stopping a recording. The stop command saves the video to the specified path.

```sh
# Start recording
npx wdio session record start

# Stop and save the video
npx wdio session record stop --path checkout.mp4
```

--------------------------------

### Example: examples.js

Source: https://webdriver.io/docs/api/webdriver

An example file that demonstrates the forward command. The code is not displayed on the page.

```javascript
loading...
```

--------------------------------

### Measure startup performance with performancetotal

Source: https://webdriver.io/docs/wdio-performancetotal-service

Test example using performancetotal.sampleStart and sampleEnd to measure the startup performance of GitHub and SourceForge. Note that the second browser.url call uses await, while the first does not.

```typescript
// This test case measures the startup performance of Github and SourceForge using the performancetotal object.

import { performancetotal } from "wdio-performancetotal-service";

it("should test github and sourceforge startup performance", () => {
    // Start a new performance measurement for Github
    performancetotal.sampleStart("GH-Startup");

    // Navigate to Github
    browser.url("https://github.com/");

    // End the Github measurement and save the results
    performancetotal.sampleEnd("GH-Startup");

    // ...

    // Start a new performance measurement for SourceForge
    performancetotal.sampleStart("SF-Startup");

    // Navigate to SourceForge
    await browser.url("https://sourceforge.net/");

    // End the SourceForge measurement and save the results
    performancetotal.sampleEnd("SF-Startup");
});
```

--------------------------------

### Install @wdio/electron-service

Source: https://webdriver.io/docs/desktop-testing/electron

Install the Electron service package as a dev dependency for manual setup in an existing WebdriverIO project.

```sh
npm install --save-dev @wdio/electron-service
```

--------------------------------

### Initialize WebdriverIO with npm and --yes flag

Source: https://webdriver.io/docs/gettingstarted

Use --yes to pick a default setup with Mocha and Chrome using the Page Object pattern.

```sh
npm init wdio@latest . -- --yes
```

--------------------------------

### Initialize WebdriverIO Configuration

Source: https://webdriver.io/docs/desktop-testing/tauri/quick-start

Run the WebdriverIO CLI setup wizard to generate a configuration file.

```bash
npx wdio config
```

--------------------------------

### Verify npm/npx installation

Source: https://webdriver.io/docs/mcp/configuration

Run this command to check if npm and npx are installed, which is the first step when the MCP server is not starting.

```bash
npm --version
```

--------------------------------

### Initialize WebdriverIO with bun and --yes flag

Source: https://webdriver.io/docs/gettingstarted

Use --yes to pick a default setup with Mocha and Chrome using the Page Object pattern.

```sh
bun create wdio@latest . --yes
```

--------------------------------

### startActivity usage example

Source: https://webdriver.io/docs/api/mobile/startActivity

Calls the startActivity method on the browser object to start an activity. This is a basic usage example with no arguments.

```javascript
await browser.startActivity()
```

--------------------------------

### cookies command examples

Source: https://webdriver.io/docs/session-commands

Examples of listing cookies, getting a single cookie, setting a cookie and reloading, and clearing all cookies.

```sh
# List cookies
npx wdio session cookies
```

```sh
# Value of one cookie
npx wdio session cookies get session
```

```sh
# Set a cookie and reload
npx wdio session cookies set session abc && npx wdio session reload
```

```sh
# Delete all cookies
npx wdio session cookies clear
```

--------------------------------

### contexts command examples

Source: https://webdriver.io/docs/session-commands

Two examples: listing contexts and switching to a specific webview context.

```sh
# List NATIVE_APP and WEBVIEW contexts
npx wdio session contexts
```

```sh
# Drive the webview
npx wdio session contexts switch WEBVIEW_com.example.shop
```

--------------------------------

### Launch pre-installed channel using launchChannel and exitChannel

Source: https://webdriver.io/docs/wdio-roku-service

Launches a channel that is already installed. The example closes the channel if it's open (backgrounding it if instant resume is supported) and then launches the sideloaded app using the channel ID 'dev'.

```javascript
import { launchChannel, exitChannel } from 'wdio-roku-service/channel';

async before() {
    // Close the channel if it's already open. If the channel supports instant resume, this will merely background it
    await exitChannel();
    // Using the channel ID of 'dev' will launch the sideloaded application.
    await launchChannel('dev');
}
```

--------------------------------

### autoInstallTauriDriver option example

Source: https://webdriver.io/docs/desktop-testing/tauri/configuration

Automatically installs tauri-driver if not found in PATH. Requires Rust toolchain (cargo) and first installation takes a few minutes. Disable if tauri-driver is installed manually or globally.

```typescript
autoInstallTauriDriver: true
```

--------------------------------

### Install service, reporter, and framework with npx wdio install

Source: https://webdriver.io/docs/testrunner

Shows how to install a service, reporter, or framework using `npx wdio install`. The package manager used is the one that runs the command (npm for npx, pnpm for pnpm, yarn for Yarn).

```sh
npx wdio install service sauce        # installs @wdio/sauce-service
npx wdio install reporter dot         # installs @wdio/dot-reporter
npx wdio install framework mocha      # installs @wdio/mocha-framework
```

--------------------------------

### Start local Chrome REPL

Source: https://webdriver.io/docs/testrunner

Starts a WebDriver session and opens an interactive prompt for trying out selectors and commands without writing a spec. This example starts a local Chrome browser.

```sh
npx wdio repl chrome
```

--------------------------------

### browser.dioxus.execute examples

Source: https://webdriver.io/docs/desktop-testing/dioxus/api

Examples of using browser.dioxus.execute with destructured DioxusAPIs, full object, arguments, and string code. Requires wdio-dioxus-bridge to be installed.

```typescript
// Execute with destructured DioxusAPIs
const result = await browser.dioxus.execute(({ invoke }) => {
  return invoke('get_platform_info');
});

// Execute with full DioxusAPIs object
const greeting = await browser.dioxus.execute(async (dx) => {
  return dx.invoke('greet', { name: 'World' });
});

// Execute with arguments
const result = await browser.dioxus.execute(
  (dx, name) => dx.invoke('greet', { name }),
  'World'
);

// Execute string of code
const href = await browser.dioxus.execute('window.location.href');
```

--------------------------------

### Install @testplanit/wdio-reporter with npm, pnpm, or yarn

Source: https://webdriver.io/docs/testplanit-wdio-reporter

Install the package using your preferred package manager. The commands are alternatives; choose one.

```bash
npm install @testplanit/wdio-reporter
# or
pnpm add @testplanit/wdio-reporter
# or
yarn add @testplanit/wdio-reporter
```

--------------------------------

### navigate command examples

Source: https://webdriver.io/docs/session-commands

Two examples: navigate to a relative path and take a snapshot, and navigate to an external site.

```sh
# Go to a page and look at it
npx wdio session navigate /cart && npx wdio session snapshot -i
```

```sh
# Open another site
npx wdio session navigate example.com
```

--------------------------------

### Example: saveRecordingScreen.js

Source: https://webdriver.io/docs/api/browser/saveRecordingScreen

Example test that starts recording, clicks a button, and saves the video to a file. This command is only supported for mobile sessions on Appium.

```javascript
it('should save a video', async () => {
    await browser.startRecordingScreen()
    await $('~BUTTON').click()
    await browser.saveRecordingScreen('./some/path/video.mp4')
})
```

--------------------------------

### background command example

Source: https://webdriver.io/docs/session-commands

Example that backgrounds the app for 3 seconds.

```sh
# Background the app for 3 seconds
npx wdio session background 3
```

--------------------------------

### Initialize WebdriverIO with bun in existing project

Source: https://webdriver.io/docs/gettingstarted

Run in the root directory of an existing project to start the WebdriverIO configuration wizard using bun.

```sh
bun create wdio@latest .
```

--------------------------------

### Async Vue component with async setup

Source: https://webdriver.io/docs/component-testing/vue

Example of a Vue 3 async component that fetches data in setup. Used as the component under test.

```vue
<script setup>
const res = await fetch(...)
const posts = await res.json()
</script>

<template>
  {{ posts }}
</template>
```
Tokens:
Raw