@wdio/protocols

What is @wdio/protocols?

@wdio/protocols is a package that provides WebDriver and Appium protocol bindings for the WebdriverIO framework. It allows you to interact with browser and mobile automation protocols, enabling you to perform a wide range of automation tasks.

What are @wdio/protocols's main functionalities?

WebDriver Protocol

This feature allows you to interact with the WebDriver protocol to automate browser actions. The code sample demonstrates how to initialize a WebDriver session, navigate to a URL, get the page title, and then close the session.

const { WebDriverProtocol } = require('@wdio/protocols');

const session = new WebDriverProtocol({
  hostname: 'localhost',
  port: 4444,
  path: '/wd/hub'
});

session.init({
  capabilities: {
    browserName: 'chrome'
  }
}).then(() => {
  return session.url('https://example.com');
}).then(() => {
  return session.getTitle();
}).then(title => {
  console.log('Page title is:', title);
  return session.deleteSession();
}).catch(err => {
  console.error('Error:', err);
});

Appium Protocol

This feature allows you to interact with the Appium protocol to automate mobile app actions. The code sample demonstrates how to initialize an Appium session, navigate to a URL within the app, get the app title, and then close the session.

const { AppiumProtocol } = require('@wdio/protocols');

const session = new AppiumProtocol({
  hostname: 'localhost',
  port: 4723,
  path: '/wd/hub'
});

session.init({
  capabilities: {
    platformName: 'Android',
    deviceName: 'emulator-5554',
    app: '/path/to/app.apk'
  }
}).then(() => {
  return session.url('https://example.com');
}).then(() => {
  return session.getTitle();
}).then(title => {
  console.log('App title is:', title);
  return session.deleteSession();
}).catch(err => {
  console.error('Error:', err);
});

Other packages similar to @wdio/protocols

selenium-webdriver

selenium-webdriver is a popular package for browser automation using the WebDriver protocol. It provides a high-level API for controlling web browsers. Compared to @wdio/protocols, selenium-webdriver is more widely used and has a larger community, but it does not support Appium protocol out of the box.

appium

appium is a package that provides bindings for the Appium protocol, allowing you to automate mobile applications. It is similar to @wdio/protocols in terms of mobile automation capabilities but does not include WebDriver protocol bindings.

README

WebdriverIO Protocol Helper

This package stores the definition for various automation protocols such as WebDriver or vendor specific protocol extensions like for SauceLabs. Unless you are interested in generating a WebDriver client there should be no reason why you should need this package. This package holds the definition of the following protocols:

• WebDriver
• JSON Wire Protocol
• Appium
• Mobile JSON Wire Protocol
• Sauce Labs
• Chrome (WebDriver extension when running Chromedriver)
• Selenium (when running Selenium Standalone Server)

Install

To install the package, run:

npm install @wdio/protocols

Usage

You can get data by importing the package as follows:

import { WebDriverProtocol, MJsonWProtocol, AppiumProtocol, ChromiumProtocol, SauceLabsProtocol, SeleniumProtocol } from '@wdio/protocols'

/**
 * get description of session command
 */
console.log(WebDriverProtocol['/session'].POST.description)

TypeScript Interfaces

The package exposes TypeScript interfaces for all protocols. You can use them for your own project as follows:

import type { WebDriverCommands } from '@wdio/protocol'

import { WebDriverCommands, WebDriverCommandsAsync } from './src'

const browser = {} as WebDriverCommands
browser.sendAlertText(true)
// fails with "Argument of type 'boolean' is not assignable to parameter of type 'string'.ts(2345)"

const asyncBrowser = {} as WebDriverCommandsAsync
const a = await asyncBrowser.getTitle()
type foo = typeof a // string

For more information on WebdriverIO see the homepage.

Changelog

v9.12.5 (2025-04-11)

:eyeglasses: Spec Compliancy

• wdio-protocols
  • #14379 feat(@wdio/protocols): Add "options" parameter to "terminateApp" command (@Nyaran)

:bug: Bug Fix

• webdriverio
  • #14406 fix(interception): Return raw non-binary responses without metadata wrapper (@Norva-bugged)
  • #14401 fix(#14368): desync puppeteer-core peer-dep version (@Badisi)
  • #14402 fix: unexpected token '?' on older browsers (@will-stone)
  • #14403 fix(element): improve checkVisibility fallback handling in element.isDisplayed (@paymand)
• webdriver
  • #14391 fix(webdriver): undici fetch() failure with HTTPS_PROXY=<proxy_url> setup (@mitya555)
• wdio-browserstack-service
  • #14393 fix: Failed hook reporting on observability (@sauravdas1997)

:nail_care: Polish

• wdio-utils
  • #14392 fix(utils): fix not to judged as screenshot the arg of switch* (@mato533)
• wdio-browserstack-service
  • #14383 chore: ignore error handling for command wrapping (@sauravdas1997)

:memo: Documentation

• webdriverio
  • #14387 docs: fixing deprecated tag display and returns (@Rondleysg)

Committers: 10

• Avron Souto (@Norva-bugged)
• Christian Bromann (@christian-bromann)
• Dmitriy Mukhin (@mitya555)
• Luis (@Nyaran)
• Payman Delshad (@paymand)
• Rondley Gregório (@Rondleysg)
• Will Stone (@will-stone)
• @Badisi
• @mato533
• @sauravdas1997