@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.0.8 (2024-09-05)

:rocket: New Feature

• wdio-protocols, webdriverio
  • #13481 feat(webdriverio): set cookies via Bidi if supported (@christian-bromann)

:bug: Bug Fix

• webdriverio
  • #13470 fix(webdriverio): fix script execution (@christian-bromann)
• Other
  • #13478 fix(webdriverio): better detect manually created shadow roots (@christian-bromann)
• eslint-plugin-wdio, wdio-allure-reporter, wdio-appium-service, wdio-browser-runner, wdio-browserstack-service, wdio-cli, wdio-concise-reporter, wdio-config, wdio-cucumber-framework, wdio-dot-reporter, wdio-firefox-profile-service, wdio-globals, wdio-jasmine-framework, wdio-junit-reporter, wdio-lighthouse-service, wdio-local-runner, wdio-logger, wdio-mocha-framework, wdio-repl, wdio-reporter, wdio-runner, wdio-sauce-service, wdio-shared-store-service, wdio-smoke-test-cjs-service, wdio-smoke-test-reporter, wdio-smoke-test-service, wdio-spec-reporter, wdio-static-server-service, wdio-sumologic-reporter, wdio-testingbot-service, wdio-types, wdio-utils, wdio-webdriver-mock-service, webdriver, webdriverio
  • #13482 fix(core): specify minimum node version to be 18.20.0 or higher (@christian-bromann)
• wdio-browser-runner
  • #13489 fix(@wdio/browser-runner): support Firefox using Bidi (@christian-bromann)

:nail_care: Polish

• wdio-browserstack-service
  • #13437 Browserstack Turboscale Observability Integration (@amaanbs)

:memo: Documentation

• wdio-shared-store-service
  • #13514 Added information on typescript types for wdio-shared-store-service (@sauterl)
• Other
  • #13486 Fix addInitScript example in v9 blog post (@Mr0grog)
  • #13483 docs: small typo in BestPractices.md (@alcpereira)
  • #13466 Argos visual testing page (@gregberge)

Committers: 8

• Amaan Hakim (@amaanbs)
• Boris Osipov (@BorisOsipov)
• Christian Bromann (@christian-bromann)
• Greg Bergé (@gregberge)
• Loris Sauter (@sauterl)
• Rob Brackett (@Mr0grog)
• Wim Selles (@wswebcreation)
• @alcpereira