But if you're already using WebdriverIO for cross-platform testing, you know it handles both web and mobile in one framework. Why should your AI assistant need two separate MCP servers to do the same thing?

That's why we built @wdio/mcp. One server for browsers and mobile apps, built on the WebdriverIO you already know.

What It Does​

Hook up Claude (or any MCP-compatible assistant) and start automating:

• Desktop Browsers - Chrome, headed or headless
• Native Mobile Apps - iOS Simulators, Android Emulators, real devices via Appium
• Hybrid Apps - Switch between native and webview contexts

The nice part: you can say "test the login flow on iPhone 15" then "now try the same on Chrome desktop" without switching tools or reconfiguring. Same conversation, same context.

Quick Start​

Add this to your Claude Desktop or Claude Code MCP config:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

Restart Claude, and you're ready to go:

"Open Chrome and navigate to https://webdriver.io"
"Click the Get Started button"
"Take a screenshot"

For mobile:

"Launch my app on iPhone 15 simulator"
"Tap the login button"
"Swipe up to scroll"

Why Not Just Use Playwright MCP + Appium MCP?​

You could, and they're solid tools. But if your testing already spans web and mobile, managing two MCP servers adds friction - two configs, two mental models, and an assistant that needs to know which tool to reach for.

With @wdio/mcp, the assistant doesn't need to care whether it's talking to a browser or a phone. It sends commands and WebdriverIO handles the rest.

What's Next: Cloud Testing​

Local automation is useful for development and exploration, but real validation needs scale. We're working on cloud provider support, starting with BrowserStack.

The goal: point your AI assistant at a device farm and validate your app across dozens of browser and device combinations. Describe what you want to verify, and let the assistant handle execution across the matrix.

BrowserStack integration is first, with LambdaTest and Sauce Labs on the roadmap.

Learn More​

Full documentation at MCP docs - setup guides, tool reference, and selector syntax for web and mobile.

Questions or feedback? Find us on Discord.

Happy testing!

This marks the beginning of a new exciting era for all projects using WebdriverIO as their test automation tool. With the great work of browser teams that are working on e.g. Chrome and Firefox, we now enter a new era that offers much greater automation capabilities than ever before thanks to the new WebDriver Bidi protocol. With WebdriverIO v9 we have been working to be at the forefront of adopters of this new era and allow you to leverage from the power of the protocol first.

Let's explore the new features, updates, and optimizations in this release.

New Features​

The majority of the new features in v9 are enabled by the WebDriver Bidi capabilities now available in browsers. Upon upgrading to v9, all sessions will automatically use Bidi unless you explicitly disable it via the new wdio:enforceWebDriverClassic capability.

New url Command Parameters​

The url command has evolved from a simple navigation tool to a powerful feature-packed command.

Passing in Custom Headers​

You can now pass custom headers that will be applied when the browser makes a request. This is useful for setting session cookies to log in automatically.

await browser.url('https://webdriver.io', {
    headers: {
        Authorization: 'Bearer XXXXX'
    }
});

Note that while you can modify how the browser treats all requests through the mock command, changes applied to the url command only last for that particular page load and reset once navigation is complete.

Overcome Basic Authentification​

Automating user authentication via basic authentication has never been easier:

await browser.url('https://the-internet.herokuapp.com/basic_auth', {
    auth: {
        user: 'admin',
        pass: 'admin'
    }
});
await expect($('p=Congratulations! You must have the proper credentials.').toBeDisplayed();

Running an Initialization Script​

Inject JavaScript before anything loads on the website using the beforeLoad parameter. This is useful for manipulating Web APIs, e.g.:

// navigate to a URL and mock the battery API
await browser.url('https://pazguille.github.io/demo-battery-api/', {
    onBeforeLoad (win) {
        // mock "navigator.battery" property
        // returning mock charge object
        win.navigator.getBattery = () => Promise.resolve({
            level: 0.5,
            charging: false,
            chargingTime: Infinity,
            dischargingTime: 3600, // seconds
        })
    }
})
// now we can assert actual text - we are charged at 50%
await expect($('.battery-percentage')).toHaveText('50%')
// and has enough juice for 1 hour
await expect($('.battery-remaining')).toHaveText('01:00)

In this example, we overwrite the getBattery method of the Navigator interface.

New addInitScript Command​

The addInitScript command enables you to inject a script into the browser that is triggered every time a new browsing context is opened. This includes actions such as navigating to a URL or loading an iframe within an application. The script you pass to this command receives a callback as its last parameter, allowing you to send values from the browser back to your Node.js environment.

For instance, to get notified whenever an element is added or removed from a node in the application, you can use the following example:

const script = await browser.addInitScript((myParam, emit) => {
    const observer = new MutationObserver((mutations) => {
        for (const mutation of mutations) {
            emit(mutation.target.nodeName)
        }
    })
    observer.observe(document, { childList: true, subtree: true })
})

script.on('data', (data) => {
    console.log(data) // prints: BODY, DIV, P, ...
})

This initialization script can modify global variables and overwrite built-in Web API primitives, allowing you to configure the test environment to meet your specific requirements.

Cross Browser Request Mocking​

WebdriverIO introduced request mocking in v6.3.0, limited to Chromium browsers. With v9, we now use WebDriver Bidi, extending support to all browsers. This enhancement allows modifying requests before they go out to the network:

// mock all API requests
const mock = await browser.mock('**/api/**')
// apply auth token to each request
mock.request({
    headers: { 'Authorization': 'Bearer XXXXXX' }
})

Automatic Shadow Root Piercing​

Testing applications with Web Components is now seamless with automatic shadow root piercing. WebdriverIO now keeps track of all ShadowRoot nodes and searches across them.

For example, let's say we want to automate the following Date Picker component that contains multiple nested shadow roots, take a look with Right Click > Inspect on any of the elements in the application and observe how much they are nested within different shadow roots:

In order to change the date, you can now just call:

await browser.url('https://ionicframework.com/docs/usage/v8/datetime/basic/demo.html?ionic:mode=md')
await browser.$('aria/Sunday, August 4]').click()
await browser.$('.aux-input').getValue() // outputs "2024-08-04T09:00:00"

While WebdriverIO previously supported "deep selectors", this functionality was limited to CSS selectors. The new selector engine now supports all selector types, including accessibility labels.

With the enhanced locator engine, elements within multiple nested shadow roots can be easily found. WebdriverIO is the first framework to support this capability for shadow roots in both open and closed mode.

Improved Argument Serialization​

With WebDriver Classic the ability to move data objects from the Test to the browser environment was rather limited to DOM elements and serializable objects and types. With WebDriver Bidi we are now able to do a better job transforming non-serializable data objects to be used in the browser as the object that it is. Alongside known JavaScript primitives such as Map or Set, the protocol allows to serialize values such as Infinity, null, undefined and BigInt.

Here is an example where we compose a JavaScript Map object in Node.js and pass it over to the browser where it gets automatically deserialzed back into a Map and vise versa:

const data = new Map([
    ['username', 'Tony'],
    ['password', 'secret']
])
const output = await browser.execute(
    (data) => `${data.size} entrie(s), username: ${data.get('username')}, password: ${data.get('secret')}`,
    data
)

console.log(output)
// outputs: "1 entrie(s), username: Tony, password: secret"

This will make it easier pass data along and work with custom scripts that can now return rich data objects that will help better observe the state of your application. It will allow frameworks like WebdriverIO to integrate deeper with the browser environment and build more useful features in the future.

Setting Viewports​

While WebdriverIO allows you to test your application in both desktop and mobile browsers, it is often easier to emulate a mobile user by adjusting the browser viewport to check if the application renders properly in responsive mode. With WebDriver Classic, this can be challenging because browser windows cannot scale down to very small sizes and often maintain a minimum width of 500px. For example:

await browser.url('https://webdriver.io')
await browser.setWindowSize(393, 659)
console.log(await browser.execute(() => window.innerWidth)) // returns `500`

WebdriverIO v9 introduces the setViewport command, enabling you to adjust the application’s viewport to any size, including modifying the devicePixelRatio. Unlike setWindowSize, which changes the overall browser window size, setViewport specifically resizes the canvas where the application is rendered, leaving the browser window dimensions unchanged.

To simplify mobile device emulation, we’ve enhanced the emulate command. This new capability allows you to simultaneously adjust the viewport size, device pixel ratio, and user agent for a specific mobile device by simply specifying its name. For example:

await browser.url('https://webdriver.io')
await browser.emulate('device', 'iPhone 15')
console.log(await browser.execute(() => window.innerWidth)) // returns `393`
console.log(await browser.execute(() => navigator.userAgent)) // returns `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36`

While we recommend to run mobile testing on actual mobile devices, as mobile browser engines differ from the ones used for desktop browser, this can be an easy escape hatch if we just quickly want to verify how the application renders in mobile viewports.

Fake Timers Support​

Want to change the time in the browser? With WebdriverIO v9, it's now possible to fake the time within the browser for your tests. We've enhanced the emulate command with a new property: clock. This allows you to set the date and time to whatever you need and control when time should advance. Here's how it works:

const clock = await browser.emulate('clock', { now: new Date(2021, 3, 14) })
console.log(await browser.execute(() => new Date().getTime())) // returns 1618383600000

await clock.tick(1000)
console.log(await browser.execute(() => new Date().getTime())) // returns 1618383601000

The new clock emulation returns a Clock object with methods like tick, setSystemTime, and restore for precise control over the time in your tests.

Automatic Dialog Handling​

If your application works with native browser dialogs, e.g. alert or confirm, it sometime can be tricky when these prompts show up unexpectedly. In previous versions all commands would fail if you don't handle them properly. With WebdriverIO v9 we will start automatically suppressing dialogs, unless you explicitly register a listener to it, e.g.:

await browser.url('https://webdriver.io')
browser.on('dialog', async (dialog) => {
    console.log(dialog.message()) // outputs: "Hello Dialog"
    await dialog.dismiss()
})

await browser.execute(() => alert('Hello Dialog'))

The new dialog event gets a dialog object passed in that allows you to call accept or dismiss on it, get the type or message of the dialog as well as its default value. We hope this will break less tests in the future due to unexpected alerts by the browser.

Automatic waiting for elements to become interactable​

An element is considered not to be interactable when it is either not displayed, cannot be scrolled into the viewport or is disabled and previously WebdriverIO would would throw an error when this would happen. In v8 we already made an improvement of showing the html of the element but in v9 we now automatically wait for elements to become interactable when executing a direct action on the element, like a click or using setValue!

This means that you no longer need to write code like this:

const submitButton = await $('button[type="submit"]');
await submitButton.waitForEnabled(); // validation of the form takes time, during which the button is disabled
await submitButton.click();

Instead you can now slim this down to:

const submitButton = await $('button[type="submit"]');
await submitButton.click(); // automatically waits for the button to become enabled

Snapshot Testing of Web Components​

If your application uses a lot of web components, using the snapshot feature turned out to be not possible due to the fact that WebdriverIO struggled to look inside the Shadow Root. With v9 WebdriverIO has now total visibility into all elements an allows to snapshot open and closed web components by transforming them into a Declarative Shadow DOM, e.g.:

await browser.url('https://ionicframework.com/docs/usage/v8/button/basic/demo.html?ionic:mode=md')

// get snapshot of web component without its styles
const snapshot = await $('ion-button').getHTML({ excludeElements: ['style'] })

// assert snapshot
await expect(snapshot).toMatchInlineSnapshot(`
    <ion-button class="md button button-solid ion-activatable ion-focusable hydrated">Default
        <template shadowrootmode="open">
            <button type="button" class="button-native" part="native">
            <span class="button-inner">
                <slot name="icon-only"></slot>
                <slot name="start"></slot>
                <slot></slot>
                <slot name="end"></slot>
            </span>
            <ion-ripple-effect role="presentation" class="md hydrated">
                <template shadowrootmode="open"></template>
            </ion-ripple-effect>
            </button>
        </template>
    </ion-button>
`)

To enable this feature we enhanced the getHTML command and replaced its previous boolean parameter with an object that allows better control about the command behavior. Read more about the new GetHTMLOptions options in the getHTML command docs.

Notable Breaking Changes​

We strive to minimize breaking changes to avoid requiring significant time for upgrades to the latest version of WebdriverIO. However, major releases offer an opportunity to remove deprecated interfaces that we no longer recommend using.

Accessing Element Properties​

As you know, WebdriverIO allows you to fetch elements from the browser to interact with them in your tests. When you interact with an element, WebdriverIO holds a reference and additional metadata on the element to properly direct commands to the correct element and, for example, refetch an element if it becomes stale. You may have accessed some of these element properties, such as evaluating the selector via $('elem').selector or getting its reference via $('elem').elementId, among others.

These properties are no longer accessible in this manner. Instead, you need to call getElement to access properties of WebdriverIO.Element and getElements to access properties for a WebdriverIO.ElementArray. Here is an example:

// WebdriverIO v8 and older
const elem = await $('elem')
console.log(elem.selector) // ❌ returns a `Promise<string>` now

// WebdriverIO v9
const elem = await $('elem').getElement()
console.log(elem.selector) // ✅ returns "elem"

This change fixes a very annoying bug in IDEs that were misled into believing that $('elem') returns a promise, causing them to automatically wrap chained element calls in multiple await statements, e.g., await (await $('elem')).getText(). This improvement will make writing tests much easier.

Removal of XXXContaining Matcher​

In expect-webdriverio, we maintain custom matchers tailored for WebdriverIO elements and end-to-end testing scenarios. Previously, we provided XXXContaining versions of each matcher to allow partial value matching. However, the underlying expect package already supports this functionality via asymmetric matchers. To reduce the number of matchers we maintain, we have decided to remove our custom XXXContaining matchers in favor of using these asymmetric matchers.

Migrating to asymmetric matchers is straightforward. Here is an example:

- await expect($('elem')).toHaveTextContaining('Hello')
+ await expect($('elem')).toHaveText(expect.stringContaining('Hello'))

Removal of isDisplayedViewport​

We have removed the isDisplayedViewport command and merged the functionality with the isDisplayed command, e.g.:

- await $('element').isDisplayedViewport()
+ await $('element').isDisplayed({ withinViewport: true })

Removal of JSON Wire Protocol Commands​

The JSON Wire Protocol was the first automation protocol developed by Selenium, enabling remote browser automation using any language that supports HTTP. In 2012, the creators of Selenium began working on formally standardizing the protocol, which is now supported in all browsers. This effort culminated in the WebDriver protocol becoming a W3C Recommendation, leading browser drivers and cloud vendors to migrate to this official standard.

We believe it is time to say farewell to the old JSON Wire Protocol and embrace the WebDriver future. If you are still testing on older browsers and require these protocol commands for your automation scripts, you can install the @wdio/jsonwp-service to continue using the necessary commands.

Removal of devtools and @wdio/devtools-service Packages​

With WebdriverIO v8.15, we introduced an automatic setup for browser drivers as a core feature. This change rendered the original purpose of the devtools package obsolete. Initially, the devtools package was designed to implement the WebDriver specification through Puppeteer which handles the browser setup for you. This allowed using WebdriverIO without having to download any browser driver. As this functionality is no longer needed, we have decided to remove the devtools package along with the automationProtocol option.

Furthermore, with the adoption of WebDriver Bidi, we now have a standardized protocol for most of our automation needs. Despite this, using Chrome Devtools for more complex browser introspection has been a popular feature in WebdriverIO. Previously, we recommended the @wdio/devtools-service package for these use cases. However, we found that most users prefer to use Puppeteer directly rather than our custom DevTools interfaces. WebdriverIO users can automate the browser using WebdriverIO primitives as well as Puppeteer simultaneously. By calling the getPuppeteer command, you can obtain a Puppeteer instance for the browser you are automating, granting you access to all Devtools capabilities through a more robust and maintained interface. As a result, users primarily utilize the @wdio/devtools-service package for testing performance and other Google Lighthouse features. Moving on, these features will be available under a new service package called `@wdio/lighthouse-service.

Rest assured, we have already found a good use case for these packages and will not abandon them.

Project Updates​

While we have been diligently adding new features to make WebdriverIO more effective for testing web and mobile applications, we have also been focusing on several internal initiatives to ensure a bright future for the project.

pnpm Migration​

As our core packages have grown over time, we've faced increasing challenges with NPM, particularly with dependency resolution in our monorepo. Additionally, custom linking made our testing infrastructure more complex than necessary.

Given the evolving JavaScript tooling ecosystem, we evaluated and adopted new technologies to improve the developer experience within the project. By migrating to pnpm, we eliminated many custom scripts, simplified the overall project setup, and now enjoy faster, more reliable dependency resolution with fewer merge conflicts in our regular updates via Dependabot.

Esbuild Migration​

Since introducing TypeScript in v7, we've used the TypeScript compiler to convert files into JavaScript for publishing to NPM. However, as our codebase grew, we encountered challenges with this setup. For example, some files within the webdriverio or @wdio/browser-runner packages are exclusively used in browser environments, yet they were compiled as if for Node.js, causing compatibility issues.

With WebdriverIO v9, all project files are compiled with Esbuild. This versatile and ultra-fast bundler allows us to compile code specifically for the intended environment, ensuring the right polyfills are applied. Additionally, every package is now bundled into a single JavaScript file, slightly improving performance, especially for component testing.

Migration from ts-node to tsx​

WebdriverIO has transitioned from ts-node to tsx for compiling TypeScript tests into JavaScript at runtime. This change offers better ESM support, improved performance, and more accurate stack traces for errors in TypeScript tests.

Dropping Node.js v16 Support​

As with every release, we are discontinuing support for older, unmaintained Node.js versions. WebdriverIO v9 will no longer support Node.js v16 and below. We recommend users upgrade to Node.js v20.

What's Next?​

As WebdriverIO celebrates its 13th year of development, the need for new testing capabilities continues to grow alongside the evolving testing industry and web standards. With the adoption of the WebDriver Bidi protocol in modern browsers, tools like Selenium, Nightwatch, and WebdriverIO can match the power of Playwright and Cypress without relying on proprietary browser patches or specific execution environments.

WebdriverIO will continue to integrate more WebDriver Bidi features to build powerful new functionalities. We are excited about future developments, including a WebdriverIO devtools application that will significantly enhance the testing experience by providing a powerful UI for inspecting and debugging the application under test. More details on this initiative will be shared soon!

Acknowledgments​

We extend our gratitude to our Premium Sponsors, BrowserStack and Sauce Labs, and to everyone who contributes to the project. WebdriverIO remains community-driven and independent, relying on contributions from people like you. Join our Open Office Hours and consider giving back to the project.

Here's to many more years of innovation and collaboration! 🚀

Thank you for reading!

WebdriverIO is build to test various types of applications, from web or mobile applications towards native desktop apps or even VS Code extensions. But what about Chrome DevTools plugins? In this blog post we explore how one could interact with an extension build for Chrome Devtools.

One of WebDriverIO features is the ability to interact with Chrome DevTools, which can be extremely helpful for debugging and testing web applications and browser extensions. In this blog, we'll explore how to use WebDriverIO to interact with the Chrome DevTools, specifically focusing on interacting with the PixiJS extension. You can find a complete example in Github.

Devtools in WebdriverIO

Setting Up Extension​

You need to download the extension you want to test in a .crx format, in our case we have downloaded the PixiJS-Devtools-Chrome-Web-Store.crx extension file.

Setting Up WebDriverIO​

First, ensure you have WebDriverIO set up in your project. If not, you can install it by following the official installation guide here

WebDriverIO Configuration for Chrome DevTools​

Here is the configuration file (wdio.conf.js) tailored to our example:

import path from "path";
import fs from "fs";

export const config = {
  specs: ["./test/specs/**/*.js"],
  runner: "local",
  maxInstances: 1,
  capabilities: [
    {
      browserName: "chrome",
      browserVersion: "stable",
      "goog:chromeOptions": {
        args: [
          "ignore-certificate-errors-spki-list",
          "--ignore-certificate-errors",
          "window-size=1920,1080",
          "--auto-open-devtools-for-tabs",
        ],
        extensions: [
          fs.readFileSync(
            path.resolve("./PixiJS-Devtools-Chrome-Web-Store.crx"),
            "base64"
          ),
        ],
      },
    },
  ],
  logLevel: "debug",
  framework: "mocha",
  mochaOpts: {
    ui: "bdd",
    timeout: 1000 * 60 * 5, // 5 min
  },
};

In this configuration, we specify the Chrome browser with options to auto-open DevTools for tabs and load the PixiJS DevTools extension. The extensions option reads the extension file in base64 format. We need also the --auto-open-devtools-for-tabs flag to automatically open the DevTools (Developer Tools) panel.

Writing the Test Script​

Next, we write a test script to interact with the PixiJS extension through Chrome DevTools. Create a test file, for example, devtools.test.js, and add the following code:

import { $, browser } from "@wdio/globals";
import { Key } from "webdriverio";

describe("DevTools Test on latest chrome", function () {
it("Devtools Navigation", async function () {
// Open an example game.
await browser.url(
"https://pixijs.io/examples-v5/#/demos-basic/container.js"
);

    // Get window handles.
    const handles = await browser.getWindowHandles();

    // Switch to devtools window.
    await browser.switchToWindow(handles[1]);

    // Navigate through devtool tabs.
    // For linux machines use [Key.Control, '['] .
    await browser.keys([Key.Meta, "["]);

    // Switch to devtool extension iframe.
    await browser.switchToFrame(0);

    // Manipulate extension.
    await $(
      "body > div > div > div.status.svelte-iqeeoq > div.patch.svelte-iqeeoq > button"
    ).click();
    await $(
      "body > div > div > div.outliner.svelte-iqeeoq > div > div.body.svelte-1vjyr8f > div:nth-child(1) > button:nth-child(4)"
    ).click();
    await $(
      "body > div > div > div.outliner.svelte-iqeeoq > div > div.body.svelte-1vjyr8f > div:nth-child(1) > button:nth-child(4)"
    ).click();

    // Switch back to parent frame.
    await browser.switchToParentFrame();

    // Switch back to main window.
    await browser.switchToWindow(handles[0]);
});
});

import { browser } from "@wdio/globals";

describe("Devtools using Puppeteer", function() {
    it("Devtools Navigation", async function() {
        // Open an example game.
        await browser.url("https://pixijs.io/examples-v5/#/demos-basic/container.js");
        await browser.pause(2000);

        // Get puppeteer instance from browser
        const puppeteer = await browser.getPuppeteer();

        // Get all targets from the current window
        const targets = puppeteer.targets();

        // Filter all targets and select the one starts from 'devtools://'
        const devtoolsTarget = targets.find(t => t.url().includes('devtools://'));

        // Devtools target type is 'other' and we change (we actually hack it) the type to 'page'
        // in order to be able to interact with and expose it's DOM
        // NOTE: you can refer to this page https://pptr.dev/api/puppeteer.target.aspage/
        const devtoolsPage = await devtoolsTarget.asPage();
        await devtoolsPage.bringToFront();

        // Navigate through Devtools tabs.
        // For linux machines use ['Control', '['] .
        await devtoolsPage.keyboard.down('Meta');
        await devtoolsPage.keyboard.press('[');
        await devtoolsPage.keyboard.up('Meta');

        // Get all the iframes from Devtools window related with the current open tab
        const frames = devtoolsPage.frames();

        // Switch to devtool extension iframe.
        const iframe = await frames[1];

        await browser.pause(2000);

        // Use puppetter commands to execute some expressions directly in the Devtools extensions window
        // NOTE: https://pptr.dev/api/puppeteer.page.evaluate
        await iframe.evaluate(() => {
            var xpath = '/html/body/div/div/div[2]/div[1]/button';
            var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
            result.singleNodeValue.click();
        });

        await browser.pause(2000);

        await iframe.evaluate(() => {
            var xpath = '/html/body/div/div/div[1]/div/div[2]/div[1]/button[3]';
            var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
            result.singleNodeValue.click();
        });

        await browser.pause(2000);

        await iframe.evaluate(() => {
            var xpath = '/html/body/div/div/div[1]/div/div[2]/div[1]/button[3]';
            var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
            result.singleNodeValue.click();
        });

        await browser.pause(2000);
    });
});

Running the Test​

To run the test, execute the following command:

npx wdio run wdio.conf.js

This will launch Chrome, open the specified URL, interact with the DevTools, and manipulate the PixiJS extension as defined in the test script.

Demonstration​

Conclusion​

By leveraging WebDriverIO and Chrome DevTools, you can automate complex browser interactions and extension manipulations. This approach is beneficial for testing web applications and ensuring extensions like PixiJS work correctly across different scenarios.

Feel free to modify the script to fit your specific testing needs. Happy testing!

Making The Visual Testing Module a Pure JS module​

One of the major changes in this update is the replacement of the Canvas library with Jimp. This shift eliminates the need for system dependencies, which often cause issues on local machines due to missing dependencies and complicate CI/CD pipelines. By using Jimp, we have streamlined the installation and setup process, making it more straightforward, less prone to errors and more important, a pure JS module.

New CLI Argument for Baseline Updates​

In response to user feedback, we've introduced a new command-line argument that allows you to automatically update your baseline images. This feature simplifies the process of maintaining and updating your baseline images, ensuring your visual regression tests remain accurate and up-to-date with minimal manual intervention. By adding the argument --update-visual-baseline to your command your tests will be executed again and failed tests will automatically be updated.

Learn everything about WebdriverIO's visual testing capabilities in our Visual docs and join our 👁️-visual-testing channel on Discord.

Thank you for your continued support, and we look forward to your feedback on these new features.

Happy testing!

The WebdriverIO Team

Both, DOM and Visual Snapshot primitives will be available for you when running component and unit tests, end-to-end tests as well as mobile web tests. In addition to that the same visual snapshot primitives will be also available for native mobile application tests.

If you are more of a visual learner, we've also released a WebdriverIO tutorial on our YouTube channel:

Let's dive into each of these powerful capabilities.

DOM or Object Snapshots​

For evaluating the state of the DOM, a large object or the content of a UI element we often tend to copy the value into our test and manually update it if we change the behavior of our application or component.

With text-based snapshots, we can just have this handled by WebdriverIO. For example, let's say we want to verify the state of our React component in a browser, we can just do the following:

import { expect, $ } from '@wdio/globals'
import { render } from '@testing-library/react'

function App() {
    const [theme, setTheme] = useState('light')

    const toggleTheme = () => {
        const nextTheme = theme === 'light' ? 'dark' : 'light'
        setTheme(nextTheme)
    }

    return <button onClick={toggleTheme}>
        Current theme: {theme}
    </button>
}

describe('React Component Testing', () => {
    it('supports snapshot tests', async () => {
        const { container } = render(<App />)
        await expect(container).toMatchSnapshot()
        await $('button').click()
        await expect(container).toMatchSnapshot()
    })
})

WebdriverIO will automatically grab the DOM structure of the component and store a snapshot file called component.test.tsx.snap in /src/__snapshots__ directory next to your test with the following content:

// Snapshot v1

exports[`React Component Testing > supports snapshot tests 1`] = `"<div><button>Current theme: light</button></div>"`;

exports[`React Component Testing > supports snapshot tests 2`] = `"<div><button>Current theme: dark</button></div>"`;

If you prefer to keep the snapshots as part of your tests you can use toMatchInlineSnapshot instead:

await expect(container).toMatchInlineSnapshot()

After running the test for the first time, WebdriverIO will make a change to the test and fill in the snapshot inline:

await expect(container).toMatchInlineSnapshot(`"<div><button>Current theme: light</button></div>"`)

Now, if you make changes to your component that will impact all snapshots you can update them all in a single run by calling:

npx wdio run wdio.conf.ts --updateSnapshots
# or
npx wdio run wdio.conf.ts -s

This makes maintaining your tests so much easier. The same works for all other types of objects, e.g. CSS Properties, or the text content of an element. They all can be converted into a snapshot to simplify the assertion and keep your tests lean. This can also speed up your tests by merging many single assertions into one, e.g.:

const elem = $('#alertBar')
await expect(elem).toHaveAttribute('data-alert')
await expect(elem).toHaveClassName('success')
await expect(elem).toHaveText('You logged into a secure area!')

now becomes a single:

await expect($('#alertBar')).toMatchSnapshot()
/**
 * stores the following into a snapshot file:
 *
 * <div data-alert="" id="flash" class="flash success">
 *   You logged into a secure area!
 *   <a href="#" class="close">×</a>
 * </div>
 */

While taking a snapshot of the DOM might be the most prominent use case, you can take snapshots of all types of serializable data structures, e.g.:

// the visible content of an element
await expect($('elem').getText()).toMatchSnapshot()
// or of an serializable object
await expect($('elem').getCSSProperty('color')).toMatchSnapshot()

You can find more information about DOM and object-based snapshots in our Snapshot guide.

Visual Snapshots​

While taking snapshots of an element structure and its attributes might be great and powerful, it comes with an important caveat: even though we are testing that the element has a class name called success, this doesn't guarantee that the alert is green!

For these reasons, visual testing has become a very popular tool as it includes how elements are rendered, in which color and can ensure that e.g. it is not overlaid by any other element. Taking visual snapshots works very similarly, as you can:

• take a visual snapshot of the whole screen:

  await expect(browser).toMatchScreenSnapshot('partialPage')
  

• take a visual snapshot of an element:

  await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement')
  

• take a snapshot of the whole page:

  await expect(browser).toMatchFullPageSnapshot('fullPage')
  

• or take a page snapshot that includes page tab-ability:

  await expect(browser).toMatchTabbablePageSnapshot('check-tabbable')
  

WebdriverIO will store these visual snapshots conveniently next to your text-based snapshots within the __snapshots__ directory next to your test.

While text-based snapshot testing is built into WebdriverIO, you have to install a service to enable all visual snapshot capabilities via:

npm i --save-dev @wdio/visual-service

With the most recent release of the Visual Testing Module with have shipped further improvements for Mobile Native App Snapshot Testing.

Mobile Native App Snapshot Testing​

The module now supports the toMatchElementSnapshot and toMatchScreenSnapshot matchers for Mobile native apps. It automatically detects the testing context (web, webview, or native_app) to streamline your workflow.

Key Features of the Visual Service​

Some of the features that make visual testing with WebdriverIO unique are:

• save or compare screens/elements/full-page screens against a baseline
• automatically create a baseline when no baseline is there
• block out custom regions and even automatically exclude a status and or toolbars (mobile only) during a comparison
• increase the element dimensions screenshots
• hide text during website comparison to:
  • improve stability and prevent font rendering flakiness
  • only focus on the layout of a website
• use different comparison methods and a set of additional matchers for better readable tests
• verify how your website will support tabbing with your keyboard, see also Tabbing through a website
• and much more, see the service and method options

Learn everything about WebdriverIO's visual testing capabilities in our Visual docs and join our 👁️-visual-testing channel on Discord.

Special Thanks to @wswebcreation​

We owe a big thank you to our core maintainer Wim Selles for his work in wdio-native-app-compare, which inspired this enhancement. His contribution has been vital in advancing our module's capabilities.

Thank you for your continued support, and we look forward to your feedback on these new features.

Happy testing!

The WebdriverIO Team

Towards a Sustainable Open Source Model​

WebdriverIO's story began with its inception into the JS Foundation in 2017, which later evolved into the OpenJS Foundation. Since then, it has thrived as an open-governed, community-driven endeavor, witnessing continuous growth in NPM downloads, the introduction of innovative plugins and reporters, and the rollout of new functionalities. This expansion is a testament to the hard work and dedication of the global testing community, including project users and contributors from leading testing cloud providers.

WebdriverIO's core principle is its dedication to open governance, an aspect that has attracted the trust and confidence of its users, especially those in the enterprise world. The project's growth has been organic, independent of Venture Capital, corporate objectives and sales requirements, guaranteeing that its development aligns with the true needs of our user community and all features remain free of charge.

With the project's continuous expansion, marked by increasing NPM downloads, new functionalities, plugins, and reporters, the importance of nurturing a healthy and sustainable growth path has never been more critical. Our recent alliances with top cloud services for automated testing demonstrate our dedication to responsibly managing these resources, with the aim to widen our network of contributors and enrich the entire ecosystem.

Introducing the Stipend Program​

Central to our ethos is the belief that financial support of the WebdriverIO ecosystem is a worthy endeavor. Whether it's the occasional contributions from casual participants or the continuous dedication of our core team members, every contribution is a building block of our project's success. Currently, the project benefits from a monthly donation inflow of $3,879, sourced through various channels like Tidelift, Thanks.dev, GitHub Sponsors, and our Open Collective. These funds have empowered the Technical Steering Committee to finalize new governance policies, outlining our strategic approach to fund allocation.

Our monthly budget is allocated across four key areas:

• Project Development receives the largest share, with 60% of the funds dedicated to fostering growth and innovation.
• Travel and Event Expenses account for 20%, supporting our participation in and hosting of industry events and meetups.
• Support Systems are allocated 10% of the budget, ensuring our infrastructure and community support mechanisms remain robust.
• Lastly, Dependencies, crucial external projects and tools we rely on, also receive 10% of our financial resources.

Dedication to Project Development​

Our financial strategy gives top priority to project development, dedicating 60% of our resources to it. This funding aims to draw contributions from a wide range of people, increasing our base of dedicated contributors. By dividing the funds, allocating 35% to individuals not directly involved with the project and 65% to our project contributors and the Technical Steering Committee (TSC) members, we seek to foster a strong sense of community and shared ownership. This approach is vital for ensuring the long-term prosperity and stability of our project.

As part of this strategy, we have developed an automated expense process using a GitHub Action to help run this program. You can read more about how this process works on my personal blog.

Supporting Community Engagement and Events​

Recognizing the importance of community engagement, especially in the aftermath of Covid-19, we are allocating funds towards travel and event expenses. This decision emphasizes our commitment to creating user meetups and supporting the broader community in hosting WebdriverIO-related events. It reflects our desire to not only maintain but also to strengthen the community ties that form the backbone of our project.

Enhancing Support Systems​

A small fraction of our monthly budget is allocated to various essentials that support our project's community growth and upkeep. Our intention is to invest in translating our documentation and financially support those who contribute to this effort. Additionally, we aim to cover ongoing costs for infrastructure needed to host project-related materials, as well as provide our maintainers with the software tools necessary to enhance their contributions to the project.

Acknowledging Dependencies​

Finally, we're committed to giving back to the projects and communities that are crucial to WebdriverIO's success. We believe it's vital for open-source projects benefiting from generous donations to support their key dependencies. Thanks to Thanks.dev, we can identify and financially support our most critical dependencies based on their significance to our project and the funds we allocate monthly for this purpose. Noteworthy dependencies include:

• Individual open-source champions like Sindre Sorhus and isaacs, whose contributions to various dependencies are invaluable.
• The Vite ecosystem: we use Vitest across almost all our projects, and we couldn't provide such powerful component testing capabilities without Vite under the hood
• The Eslint project and its related ecosystem projects are fundamental to maintaining a high code quality of our projects and have significantly inspired our contributor stipend program.

Looking Ahead​

As we embrace this new chapter, we're excited about the prospects of accelerating growth through strategic investments in our community and project. The early feedback from our initiatives has been overwhelmingly positive, and we are committed to refining our processes for even greater efficiency and transparency.

We extend our heartfelt gratitude to our sponsors for their invaluable support, and we warmly welcome further sponsorship to join us in this journey. Together, we are setting the stage for an even brighter future for WebdriverIO and its thriving ecosystem.

Sauce Labs has earned a reputation as a leader in providing solutions that empower organizations worldwide to achieve excellence in software delivery. Their platform, trusted by thousands of development teams, ensures that digital products function seamlessly across every browser, operating system, and device. This commitment to quality guarantees a flawless user experience, showcasing Sauce Labs' dedication to software excellence.

The company has been technically sponsoring the project almost since day one. My early work on WebdriverIO has opened an opportunity to work at Sauce Labs and during my 7-year tenure there, I was allowed and encouraged to work on this framework. Even some of Sauce Labs products have been heavily inspired by the work in WebdriverIO, e.g. their performance testing and extended debugging capabilities.

It makes me personally very happy to see Sauce Labs staying invested in the Open-Source testing ecosystem. Being the originators of Selenium and creators of Appium Sauce Labs remains a strong supporter of open-governed tools like WebdriverIO.

Thank you 🙏

BrowserStack is the world’s leading software testing platform powering over two million tests every day across 15 global data centers. BrowserStack helps Tesco, Shell, NVIDIA, Discovery, Wells Fargo, and over 50,000 customers deliver quality software at speed by moving testing to their Cloud. BrowserStack’s platform provides instant access to 3,000+ real mobile devices and browsers on a highly reliable cloud infrastructure that effortlessly scales as testing needs grow. With BrowserStack, Dev and QA teams can move fast while delivering an amazing experience for every customer.

In an exciting turn, BrowserStack has become an exclusive Premium Sponsor for WebdriverIO, providing crucial funding that supplements our primarily user-generated donations. This generous support enables us to advance significant initiatives, including our upcoming major release. For the first time, we can offer financial recognition to our devoted community contributors, acknowledging their invaluable efforts toward the project's triumph. We will soon share more information on how we will use the project funds and how we plan to distribute them.

As a token of this collaboration, BrowserStack is extending a special free trial license to all WebdriverIO users. Discover more about this incredible offer at browserstack.com.

Since its inception, WebdriverIO has been propelled by a dedicated group of developers, united by a passion for crafting tools that enhance software quality. While other testing projects have benefited from substantial venture capital and corporate funding, WebdriverIO has predominantly relied on its vibrant community, without the means to provide significant financial compensation for contributions.

The core contributors of WebdriverIO are elated about this partnership. We are profoundly grateful to BrowserStack for their commitment to nurturing open-governed, open-source projects like ours.

Thank you 🙏

The book's rich content includes insights into the implementation of custom command wrappers and the integration of AI-powered self-healing object strategies, elevating the scope of test automation to unprecedented levels. Its target audience spans Software Developer Engineers in Test (SDETs) seeking to enhance their skill set. By addressing crucial aspects such as dynamic data handling, detailed reporting, and the seamless integration of automated tests into CI/CD pipelines, the book proves particularly beneficial for those striving to streamline test maintenance and automate complex test scenarios.

At the heart of this narrative is WebdriverIO, a leading automation testing framework. As readers navigate through the pages, they are introduced to the art of seamlessly integrating and balancing the strengths of various testing frameworks. The book strategically delves into the intricate realm of hybrid testing, demonstrating how the harmonious synergy of different frameworks can substantially enhance efficiency and reliability in the testing process.

Here's a glimpse into what readers will uncover:​

1. Efficient Page Object Model Maintenance: Discover techniques that empower you to efficiently maintain and enhance your Page Object Model, saving valuable time and effort in the long run.

2. Diagnosing and Resolving Script Instability: Gain insightful strategies for diagnosing and resolving script instability issues, ensuring a consistent and reliable test execution.

3. Building Resilient Test Objects: Learn how to build objects that exhibit adaptability to changing element locators, enhancing the overall resilience of your tests.

4. Enhancing Testing Productivity with TypeScript: Elevate your testing productivity by mastering the art of writing effective test cases with TypeScript, a powerful scripting language.

5. Comprehensive Result Analysis for Data-Driven Decision-Making: Explore strategies for conducting comprehensive result analysis, empowering data-driven decision-making processes within your testing framework.

6. Developing Adaptive Frameworks: Develop frameworks that seamlessly adapt to the evolving user journeys, ensuring the long-term sustainability of your tests.

Packed with practical examples, real-world scenarios, and expert insights, "Enhanced Test Automation with WebdriverIO" goes beyond traditional boundaries, equipping readers with the knowledge to revolutionize their test automation strategies. Whether you are a novice venturing into the automation journey or a seasoned professional looking to amplify your skills, this book serves as your gateway to unlocking the superpowers inherent in hybrid testing frameworks. Embrace the future of test automation and elevate your testing prowess with WebdriverIO.

You can get a copy of this book on Amazon today!

Simplified Browser Automation Setup​

To automate a browser, you need to set up a browser driver that translates WebDriver-based commands and executes them within the browser. While WebdriverIO has provided useful services like wdio-chromedriver-service to simplify test environment setup, there have been challenges, particularly when new Chrome versions are released 🙈.

But fear not! With the release of WebdriverIO version v8.14.0, and onwards, all driver management hassles are now a thing of the past 🙌. The WebdriverIO team has been hard at work, taking over the maintenance of geckodriver, edgedriver and safaridriver packages. This means smoother and more seamless browser automation experiences for you.

Say Goodbye to Driver Services​

One of the significant advantages of this update is that you can now get rid of any driver services you previously had to manage, such as wdio-chromedriver-service, wdio-geckodriver-service, wdio-edgedriver-service, wdio-safaridriver-service, and even @wdio/selenium-standalone-service.

Specifying Browser Versions Made Easy​

Testing Chrome locally is now more convenient than ever. You can define a browser channel, and WebdriverIO will take care of downloading the specified browser version for you. For example:

{
    browserName: 'chrome',
    browserVersion: '116.0.5793.0' // or 'stable', 'beta', 'dev' or 'canary'
}

This has been made possible through Google's effort on Chrome for Testing which offers reliable downloads for browser automation. It's now built into WebdriverIO and guarantees consistent, reproducible results across repeated test runs.

Effortless Testing on Microsoft Edge and Safari​

WebdriverIO will now automatically detect the installed version of Microsoft Edge and download the appropriate Edgedriver for you. Similarly, testing on Safari Technology Preview is a breeze; just install it on your Mac machine and use Safari Technology Preview as the browser name.

Customization and Flexibility​

For those who require custom driver options, fear not; WebdriverIO allows you to pass in driver options through custom WebdriverIO capabilities. If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebdriverIO will only start a driver when there are no other connection information settings like hostname or port specified.

In conclusion, WebdriverIO version v8.14.0 and beyond provides an incredibly smooth and seamless browser automation experience. With automated driver management, simplified browser version setup, and improved compatibility, your testing workflows are now more efficient and straightforward than ever before. Say goodbye to the bumpy automation rides and embrace the future of effortless browser testing with WebdriverIO! 🚀

With the release of WebdriverIO v8.11 we are adding new WebDriver Bidi interfaces and make them type safe 🎉

The interface of the WebDriver Bidi specification is defined through a Concise Data Definition Language (short CDDL). It describes which payloads can be send to the driver and which responses are expected. Over the last month I've been working on a CDDL parser to help the Browser Testing and Tools Working Group at W3C to validate the CDDL defined in the specification as well as help the WebDriver ecosystem to adopt the protocol.

I've created two NPM packages that hopefully can contribute to that:

• cddl: a package to read CDDL and parse it into an AST as well as validate the contents
• cddl2ts: a package that allows you to transform a CDDL file into a TypeScript interface that you can use for other TypeScript projects

With some recent changes in the WebdriverIO repository we now generate a perfectly typed WebDriver Bidi interface thanks to those packages, e.g.

We also updated the protocol docs to include new Bidi commands that help users to interact with the protocol using Promises. As browser start to support more Bidi features WebdriverIO will start running more automation on the new protocol, ensuring that your tests use the latest and greatest cross browser automation standards. Here are some features that are about to land in upcoming browser versions:

• Add Preload-Scripts: this will be an invaluable command to help WebdriverIO mock Web APIs and inject scripts for introspection
• Network Interception: this will make WebdriverIOs mock API for network requests compatible cross browser
• HTTP Authentication: enables the ability to load a web page that is protected behind user credentials

Note that even WebdriverIO will offer the latest WebDriver Bidi features, this doesn't mean that those are implemented and shipped in the browser. Every browser vendor has different priorities and resources available to get these new features added and while the teams make great progress it will take more time until everything specified in the protocol lands in a stable browser version. You can be ensured though that WebdriverIO will always provide a typed interface for you to use them once ready.

Furthermore I am working on a proposal to extend the WebdriverIO interface and include a page object next to the already known browser, element and mock objects to simplify accessing commands and events connected to a certain browsing context. For information about that soon!

I want to close up thanking the Mozilla and Google browser teams for their excellent collaboration and efforts to ship this new standard that will enable developers around the world ship high quality web applications in the future.

Within this article, I will guide you through a detailed step-by-step process on how to create a comprehensive end-to-end test pipeline at no cost, utilizing GitHub Actions for both the iOS and Android platforms. We will be using our beloved WebdriverIO framework throughout the tutorial.

Challenge​

Our challenge is to establish a unified pipeline workflow that enables testing of our native mobile application on both the iOS and Android platforms. In a previous article, we thoroughly explored the process of constructing a pipeline for testing an Android app using an emulator with GitHub Actions. To handle the E2E test for the Android component, we will reuse that workflow. However, we still need to address the remaining bigger challenge of creating a separate job for the iPhone/iPad simulator.

During my research, I came across an incredibly useful but often overlooked feature which is, the macOS GitHub runner comes pre-equipped with Xcode, the necessary SDKs for iPhone iOS simulators. This realization sparked an idea in my mind: why not replicate the process we followed for the Android emulator but this time for the iOS simulator? This is particularly exciting because GitHub Actions’ iOS runner supports virtualization, making it a viable option for our purposes.

This feature allows us to build our pipeline without any additional costs (up to a maximum of 2000 minutes).

Workflow structure​

Our GitHub actions workflow will be basically the same as Android in the core concept but with a little technical variation

• Create simulator
• Install dependencies
• Execute the test
• Generate the report

Looks pretty straightforward, but how? Let’s see

Step 1​

As previously mentioned, the GH Actions runner comes packed with a range of available simulators. While we could utilize one of these existing simulators, it would require using the deviceName and it's

randomly changing UUID for each execution. However, you can still extract the relevant UUID using shell commands.

To simplify the process and increase flexibility, we will create our own simulator. Since Xcode is already installed, we can make use of the “xcrun” CLI. To create a simulator from the installed iOS versions using the terminal, simply execute the following command:

xcrun simctl create "iPhone 14 Pro" "com.apple.CoreSimulator.SimDeviceType.iPhone-14-Pro" "com.apple.CoreSimulator.SimRuntime.iOS-16-0"

Executing this command will result in the immediate creation of a simulator and the subsequent retrieval of its UUID.

To enhance re-usability and optimize the process, we can encapsulate this command within a shell script. With a few modifications, we can ensure that the UUID is stored as an environment variable in GitHub Runner which we will eventually use for our test capabilities.

#!/bin/bash

# Set iPhone model and iOS version
iphone_model="${IPHONE_MODEL// /-}"
ios_version="${IOS_VERSION//./-}"
simulator_name="${iphone_model}"
simulator_udid=$(xcrun simctl create "$IPHONE_MODEL" "com.apple.CoreSimulator.SimDeviceType.$iphone_model" "com.apple.CoreSimulator.SimRuntime.iOS-$ios_version")

# Export the simulator UDID as an environment variable
export SIMULATOR_UDID="$simulator_udid"
echo "SIMULATOR_UDID=$SIMULATOR_UDID" >> $GITHUB_ENV

# Boot the simulator
xcrun simctl boot "$simulator_udid"

By using the script above, we can provide the device model and iOS version as environment variables which can be stored in the environment sections in our workflow, this will create the simulator and store its UUID in GITHUB_ENV. This UUID will be essential for configuring the desired capabilities in our tests.

Since we are using IPHONE_MODEL and IOS_VERSION as environment variable in our shell script then we will have to set them in the environment section as shown below.

Step 2​

After successfully creating and booting up the simulator in the previous step, it’s crucial to verify that the process was completed without any issues and that the device is fully prepared for use.

To ensure the successful starting of our test, it is crucial to confirm that the IOS has fully booted. For this purpose, I have created a code snippet that continuously monitors the device’s status until a specific output is obtained, signifying the completion of the simulator’s booting process.

#!/bin/zsh

function wait_for_boot() {
  printf "${G}==> ${BL}Waiting for the simulator to boot...${NC}\n"
  start_time=$(date +%s)
  spinner=( "⠹" "⠺" "⠼" "⠶" "⠦" "⠧" "⠇" "⠏" )
  i=0
  # Get the timeout value from the environment variable or use the default value of 60 seconds
  timeout=${BOOT_TIMEOUT:-60}

  while true; do
    output=$(xcrun simctl bootstatus "$SIMULATOR_UDID")
    echo "${output}"
    if [[ $output == *"Device already booted, nothing to do."* ]]; then
      printf "\e[K${G}==> \u2713 Simulator booted successfully${NC}\n"
      exit 0
    else
      printf "${YE}==> Please wait ${spinner[$i]} ${NC}\r"
      i=$(( (i+1) % 8 ))
    fi

    elapsed_time=$(( $(date +%s) - $start_time ))
    if [[ $elapsed_time -ge $timeout ]]; then
      printf "${RED}==> Timeout waiting for simulator to boot 🕛${NC}\n"
      exit 1
    fi

    sleep 1
  done
}

# Call the wait_for_boot function
wait_for_boot

Step 3​

Proceeding further, we will cover the necessary steps and dependencies required for executing your tests. This includes the installation of Appium, the XCUITest driver, and the essential Node.js libraries.

  "devDependencies": {
    "@wdio/allure-reporter": "^8.10.4",
    "@wdio/appium-service": "^8.10.5",
    "@wdio/cli": "^8.10.5",
    "@wdio/local-runner": "^8.10.5",
    "@wdio/mocha-framework": "8.10.4",
    "@wdio/spec-reporter": "8.8.7",
    "ts-node": "^10.9.1",
    "typescript": "^5.0.4"
  },
  "dependencies": {
    "allure-commandline": "^2.22.1",
    "appium": "2.0.0-beta.71",
    "appium-uiautomator2-driver": "*",
    "appium-xcuitest-driver": "*"
  }

Connecting the Puzzle Pieces​

Since now the key elements required to set up the environment for executing our mobile automation tests on the iOS simulator are ready, Let’s wrap them all into a single yaml file for GH actions

name: Wdio-x-native

on:
  workflow_dispatch:

env:
  IPHONE_MODEL: iPhone 8
  IOS_VERSION: 16.2
  BOOT_TIMEOUT: 700

jobs:
  ios:
    runs-on: macos-13

    steps:
      - uses: actions/checkout@v3

      - name: Export environment variables
        run: |
          export IPHONE_MODEL=$IPHONE_MODEL
          export IOS_VERSION=$IOS_VERSION

      - name: Start simulator
        run: |
          chmod a+x ./sscript/start_simu.sh
          ./sscript/start_simu.sh

      - name: Install dependencies
        run: |
          npm i

      - name: Check simulator booting status
        run: |
          chmod a+x ./check_simu.sh
          ./check_simu.sh

      - name: Execute the test
        run: |
          npm run ios

Combine the simulator status check and simulator start into a single shell script would have been possible. However, I intentionally separated them to execute them individually. This allows me to utilize the time taken for the simulator to boot up and install the remaining dependencies. Afterwards, I can then proceed to check the status of the simulator. Similarly we will apply same approach to Android emulator (check previous article).

Build cross-platform workflow​

The time now to combine our Android workflow from the previous article without Ios workflow into one single workflow, using the matrix strategy as follows:

name: Wdio-x-native

on:
  workflow_dispatch:

env:
  IPHONE_MODEL: iPhone 8
  IOS_VERSION: 16.2
  API_LEVEL: 32
  EMULATOR_NAME: Nexus
  EMULATOR_DEVICE: Nexus 5
  EMULATOR_VERSION: 12
  ANDROID_ARCH: x86_64
  ANDROID_TARGET: google_apis
  ANDROID_BUILD_TOOLS_VERSION: 34.0.0-rc4
  ANDROID_SDK_PACKAGES: system-images;android-32;google_apis;x86_64 platforms;android-32 build-tools;34.0.0-rc4 platform-tools emulator
  EMULATOR_TIMEOUT: 350
  BOOT_TIMEOUT: 700

jobs:
  ios:
    runs-on:
       - macos-13
    strategy:
      matrix:
        os: [IOS]
        device: [$IPHONE_MODEL]
        version: [$IOS_VERSION]
    steps:
      - uses: actions/checkout@v3

      - name: Export environment variables
        run: |
          export IPHONE_MODEL=$IPHONE_MODEL
          export IOS_VERSION=$IOS_VERSION
    # ...
    # find the full workflow at the end of the article
    # ...

  android:
    runs-on: macos-13
    strategy:
      matrix:
        os: [Android]
        emulator_name: [$EMULATOR_NAME]
    steps:
      - uses: actions/checkout@v3

      - name: Add avdmanager and sdkmanager to system PATH
        run: |
          echo "$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$ANDROID_HOME/build-tools/${{ env.ANDROID_BUILD_TOOLS_VERSION }}" >> $GITHUB_PATH

      - name: Install Sdk
        run: |
          yes Y | sdkmanager --licenses
          sdkmanager --install ${ANDROID_SDK_PACKAGES}

      - name: Build emulator

    # ...
    # find the full workflow at the end of the article
    # ...

In the above example, we have integrated the IOS workflow mentioned earlier with the Android emulator workflow described in our previous article.

These are the recommended configurations that you may require for both the Android emulator and iPhone simulator. It’s important to note that the deviceName, platformVersion, and UUID are not hardcoded in our object. This flexibility allows us to easily switch between different versions and device models as needed.

const emulator = [{
  platformName: 'android',
  'appium:options': {
    deviceName: process.env.CI ? process.env.EMULATOR_NAME : 'Nexus',
    platformVersion: process.env.CI ? process.env.EMULATOR_VERSION : '13',
    automationName: 'uiautomator2',
    appPackage: 'com.wdiodemoapp',
    appWaitPackage: 'com.wdiodemoapp',
    appActivity: 'com.wdiodemoapp.MainActivity',
    appWaitActivity: 'com.wdiodemoapp.MainActivity',
    uiautomator2ServerLaunchTimeout: 200000,
    uiautomator2ServerInstallTimeout: 200000,
    appWaitForLaunch: true,
    autoGrantPermissions: true,
    adbExecTimeout: 200000,
    androidInstallTimeout: 150000,
    ignoreHiddenApiPolicyError: true,
    noReset: true,
    fullReset: false
  }
}]

const simulator = [{
  platformName: 'iOS',
  'appium:options': {
    deviceName: process.env.CI ? process.env.IPHONE_MODEL : 'Iphone-13',
    platformVersion: process.env.CI ? process.env.IOS_VERSION : '15.5',
    automationName: 'XCUITest',
    bundleId: 'org.wdioNativeDemoApp',
    app: 'iOS-Simulator-NativeDemoApp-0.4.0.app.zip',
    udid: process.env.CI ? process.env.SIMULATOR_UDID : '15A098DB-B8A0-4D6A-9057-23FF1F0F0D9B',
    useNewWDA: true,
    usePrebuiltWDA: false,
    wdaConnectionTimeout: 180000,
    appWaitForLaunch: true,
    noReset: true,
    fullReset: false
  }
}]

Initial Execution​

The good news is that workflow is configured properly and the e2e test for the IOS app has been successfully executed

Though the end-to-end test for the iPhone simulator has passed, it was observed that the test for the Android emulator shows instability.

Debugging​

System UI Crush​

It appears that running Android for the first time in headless mode occasionally results in random system UI unresponsive issues. Unfortunately, this issue is preventing us from executing the tests as the UI system is unresponsive which consequently disrupts Appium from proper interaction with the app.

The issue was confirmed when reviewing the allure report screenshots

This explains why the terminal log displayed that Appium was unable to locate any element, despite the successful launch of the app.

This makes sense as Appium is trying to find the desired element but on the current running activity which is .systemui, even though our target app is launched in the background

Connection timeout​

It has been noted that on certain occasions, Appium encountered failures in initiating the test, with all connection retry attempts proving unsuccessful. However, after conducting a thorough investigation, it was discovered that the installation of the Apk file to the Android emulator through the app:“./test.apk” capability was taking an unusually long time, requiring a significantly extended connection timeout to ensure successful installation which is not the best solution.

Now that we have identified the issue and its root cause, it’s time to address and resolve them.

Resolving​

System UI Crush​

Fortunately, we can utilize the advantage of being able to grep the current running activity on an Android device. This privilege allows us to detect whether the system UI or any similar Android service will crash or function normally. We can achieve this by executing the following adb shell command:

adb shell dumpsys window 2>/dev/null | grep -i mCurrentFocus

In our ongoing implementation, we can mimic our natural behavior when encountering this issue on an Android device. Specifically, we will continuously click the home button until the issue is resolved. Once the problem is resolved and the Android system is functioning correctly, we anticipate observing the “.NexusLauncherActivity” as the current main activity running (where “Nexus” represents the Android device).

In order to achieve this, I have developed the following shell script:

#!/bin/bash

function check_current_focus() {
  printf "==> Checking emulator running activity \n"
  start_time=$(date +%s)
  i=0
  timeout=20
  target="com.google.android.apps.nexuslauncher.NexusLauncherActivity"

  while true; do
    result=$(adb shell dumpsys window 2>/dev/null | grep -i mCurrentFocus)

    if [[ $result == *"$target"* ]]; then
      printf "==>  Activity is okay: \n"
      printf "$result\n"
      break
    else
      adb shell input keyevent KEYCODE_HOME
      printf "==> Menu button is pressed \n"
      i=$(( (i+1) % 8 ))
    fi

    current_time=$(date +%s)
    elapsed_time=$((current_time - start_time))
    if [ $elapsed_time -gt $timeout ]; then
      printf "==> Timeout after ${timeout} seconds elapsed 🕛.. \n"
      return 1
    fi
    sleep 4
  done
}

check_current_focus

The shown function above will continuously loop, If the main activity is not found (NexusLauncherActivity), it will send a home button event and repeat the process until its found or timeout is reached.

Connection timeout​

Rather than significantly extending the Appium connection timeout, I will handle the APK installation in a separate step along with the main activity checking.

      - name: Install APK
        run: |
          adb install Android-NativeDemoApp-0.4.0.apk
          chmod a+x ./mainActivityCheck.sh
          ./mainActivityCheck.sh

Excellent! Our solution has been executed successfully with the proper installation of the APK. As expected, the system UI was not responsive, and the shell script effectively managed and handled the situation.

Optimizing and Enhancing workflow​

I have improved the workflow dispatch to provide better control over the platforms on which I can execute my tests, whether it be iOS, Android, or cross-platform.

name: Wdio-x-native

on:
  workflow_dispatch:
    inputs:
      e2e:
         type: choice
         description: Select a platform
         required: true
         options:
            - xplatform
            - ios
            - android
         default: xplatform

Consequently, our jobs should be adjusted

name: Wdio-x-native

on:
  workflow_dispatch:
    inputs:
      e2e:
         type: choice
         description: Select a platform
         required: true
         options:
            - xplatform
            - ios
            - android
         default: xplatform


permissions:
  contents: write
  pages: write
  id-token: write

env:
  IPHONE_MODEL: iPhone 8
  IOS_VERSION: 16.2
  API_LEVEL: 32
  EMULATOR_NAME: Nexus
  EMULATOR_DEVICE: Nexus 5
  EMULATOR_VERSION: 12
  ANDROID_ARCH: x86_64
  ANDROID_TARGET: google_apis
  ANDROID_BUILD_TOOLS_VERSION: 34.0.0-rc4
  ANDROID_SDK_PACKAGES: system-images;android-32;google_apis;x86_64 platforms;android-32 build-tools;34.0.0-rc4 platform-tools emulator
  EMULATOR_TIMEOUT: 350
  BOOT_TIMEOUT: 700

jobs:
  ios:
    runs-on:
       - macos-13
    if: ${{ contains(github.event.inputs.e2e, 'ios') || contains(github.event.inputs.e2e, 'xplatform') }}
    strategy:
      matrix:
        os: [IOS]
        device: [$IPHONE_MODEL]
        version: [$IOS_VERSION]
    steps:
      - uses: actions/checkout@v3
    # find the full workflow at the end of the article

  android:
    runs-on: macos-13
    if: ${{ contains(github.event.inputs.e2e, 'android') || contains(github.event.inputs.e2e, 'xplatform') }}
    strategy:
      matrix:
        os: [Android]
        emulator_name: [$EMULATOR_NAME]
    steps:
      - uses: actions/checkout@v3
    # find the full workflow at the end of the article

Finally, Generate our report and deploy it to the GitHub page out of the box

      - name: Generate report
        if: always()
        run: |
          npx allure generate report/allure-results

      - name: Setup Pages
        if: always()
        uses: actions/configure-pages@v3

      - name: Upload artifact
        if: always()
        uses: actions/upload-pages-artifact@v1
        with:
          path: './allure-report'

      - name: Deploy to GitHub Pages
        if: always()
        id: deployment
        uses: actions/deploy-pages@v2

Workflow Execution​

Fantastic news! Our workflow is now functioning flawlessly and exhibits complete stability. The workflow can be triggered against a single platform, such as Android or iOS, or simultaneously against both platforms in parallel.

loading...

Conclusion​

By leveraging the capabilities provided by GitHub Actions, which offer out-of-the-box SDKs for both Android and iOS, we gain a significant advantage. This allows us to construct an efficient end-to-end test pipeline without incurring any costs or relying on mobile device farm cloud services. Although conducting tests on real devices is preferable, particularly for Android, the cost-free nature of this approach presents a satisfactory compromise.

Throughout our discussion, we have provided a step-by-step demonstration of building a cross-platform end-to-end test using the GitHub Actions pipeline for native mobile Apps. We have addressed various challenges, obstacles, and issues, ensuring a thorough understanding of the process. Armed with this knowledge, you should find it easier to construct your own customized pipeline that caters to your specific requirements.

It is not a surprise that many projects out there have code examples embedded in their project documentation. Many of them are even interactive and allow users to fiddle around with the code in real time, e.g. the new React Docs, or provide "playgrounds" with live examples, like on svelte.dev.

When it comes to having code examples on a documentation page, a common problem that arises with them is that examples:

• are made up and often don't reflect reality
• contain errors because we are all just humans
• are getting outdated as interfaces change
• can be difficult to apply in your own project

As an attempt to improve our code examples on this project page we started to roll out some changes to the documentation that hopefully addresses these issues:

loading...

As you can see, some examples now have two buttons that allow you to run them or view them on GitHub. But what does that mean?

Extract Examples from Docs​

As a first step we started to remove all code examples from our documentation page and moved them into a dedicated repository. This allows us to treat these examples as code and set-up the necessary infrastructure, e.g. CI/CD or automated dependency updates, to ensure quality and correctness.

So say hello 👋 to this new repository in our organization that now contains a lot of examples that we re-use on this website.

You can see that every example is self contained in its own directory to keep everything very simple. A big list of NPM scripts allows you to run specific examples with just a single command.

In order to embed the examples back into the website, we are using a plugin for Docusaurus that downloads the code based on a simple GitHub reference link. So instead of having code within our markdown files, we just reference the location on Github, e.g.:

loading...

The plugin then downloads the code and only shows provided code lines of that file. Here is the final result of that:

loading...

If you are using a different tool for building your static docs, chances are that it has similar plugins available to just do that.

Testing Examples​

Now that we have everything nicely encapsulated into a dedicated repository, we can use CI/CD to test all examples on regular basis. A simple GitHub workflow can trigger the execution of these examples and have the pipeline fail if any of them have an error:

name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        exampleDir:
          - click
          # more example directories here
          # ...
          - api/webdriver
    steps:
        - name: Checkout
          uses: actions/checkout@v3
        - uses: actions/setup-node@v3
          with:
            node-version: 18
        - name: Install
          run: npm install
        - name: Test
          run: npm run ${{ matrix.exampleDir }}
          working-directory: ${{ matrix.exampleDir }}

Most of the examples are written as normal WebdriverIO test files and contain normal assertions like any other test would do, e.g. an example that shows how to fetch elements using command chaining would be written as following:

it('should get the text of a menu link', async () => {
    const menu$ = await $('#menu') // or `browser.$('#menu')`
    console.log(await menu$.$$('li')[2].$('a').getText()) // outputs: "API"

    await expect(menu$.$$('li')[2].$('a')).toHaveText('API')
})

With the ability to reference certain code lines we can just strip out the testing part of the example and focus on what's important:

loading...

Keep Examples up to Date​

Another advantage of having a CI/CD infrastructure is the ability to use workflows that ensure everything stays up to date. Since WebdriverIO code is hosted on GitHub, we setup Dependabot to update all dependencies on weekly basis. An additional GitHub workflow helps us to auto-merge these dependency updates so that we only need to deal with them in case they cause issues due to failing tests.

This process is very important and helps us to ensure that changes in WebdriverIO don't break any of our examples we use in our documentation. It is also a great additional feedback loop and creates more confidence when a new version is released that did not break any of our examples.

Make Examples Easy Accessible​

Lastly, to make every example very easy to access and run, we are using a feature of a very cool VS Code Extension called Runme that helps to check out code locally with a simple click on a button. If you haven't installed Runme yet, go check it out on the VS Code Marketplace or find it in your VS Code:

Many surveys have shown that VS Code is the dominant IDE for many developers around the world. With the Run Example button we allow all these users to access the repository with a single click. The button is a simple link with a custom vscode:// protocol that will prompt you for permission to open it in VS Code. There, the extension will pick up the link information containing which repository it needs to check out and which markdown file to open. If the extension is not installed, it will automatically do that for you, if you consent.

Once the repository is checked out, Runme will open a dedicated README.md for the example in an interactive notebook experience. It will explain the example and walks you through it. It allows to execute the code cells within the VS Code terminal securely so that setting up and running the example is done with a simple click and requires no additional application to be opened.

For folks that don't have VS Code installed can still access the repository, check it out manually and run the examples as well.

Get Involved​

WebdriverIO has many examples and a lot of commands and APIs to document. This is a great opportunity for you to get involved and contribute to the project by:

• adding more examples to webdriverio/example-recipes or
• reference existing examples in our documentation

Feel free to also raise an issue if you have any questions or feedback.

I think this is a very cool way to provide an interactive and simple way to provide code examples for a framework that requires a specific environment that is not a browser, e.g. Node.js. If you are a framework author and run your docs with Docusaurus, feel free to copy this approach if you like it. It's Open Source and free.

Thanks for reading!

As with almost all of the last major updates we again had to touch every single file of the project. This time our major goal for the new version was to finally transition from CommonJS to ESM which enables us to continue with important dependency updates and avoid security issues. Furthermore, we cleaned up some technical debt, e.g. removed all code related to synchronous command execution which was deprecated last year, as well as implemented a new Action API interface and streamlined the way WebdriverIO deals with global objects using the test runner.

In this blog post, we go through every important change and explain what you need to do to upgrade to v8. Spoiler alert: in most cases no updates to your tests are necessary 😉

Drop Node.js v12, v13 and v14 Support​

We've dropped support for Node v12 and v14, latter was moved into a maintenance LTS phase by the Node.js team in October 2021. While it is technically fine to continue using Node.js v14, we don't see a reason why you shouldn't update to Node.js v16 or ideally v18 directly.

To update Node.js, it is important to know how it was installed in the first place. If you are in a Docker environment, you can just upgrade the base image like:

- FROM mhart/alpine-node:14
+ FROM mhart/alpine-node:18

We recommend using NVM (Node Version Manager) to install and manage Node.js versions. You can find a detailed description of how to install NVM and update Node in their project readme.

CommonJS to ESM Transition​

The transition to the new module system has been the biggest chunk of work related to this release. It required us to update all module imports, transitioning from Jest to Vitest as a unit test framework and rewrite various parts within the code base. While this affected every single file it "should" be unrecognizable to you. If your project still uses CommonJS, WebdriverIO will work just fine as both module systems continue to be supported. This is also the case when using webdriver, devtools or webdriverio as a module.

If you have been using Babel only to use import statements in your tests, you can remove the integration as this is now supported by ESM natively. If you like to continue using CommonJS and require, that is fine too, no changes are needed to update to v8.

A new Runner for Unit and Component Testing in the Browser​

If it comes to one feature we are really excited about in this release it is the new browser runner 🙌 I've been writing and testing a lot of web components in this past year and was always frustrated about the fact that they would be tested against JSDOM rather than an actual browser. JSDOM is a re-implementation of many Web APIs in Node.js and is a great tool for simple testing but it doesn't replace an actual DOM implementation within a browser. Especially using JSDOM for component testing has various disadvantages compared to running tests in the browser.

Furthermore running component tests through WebdriverIO allows to use the WebdriverIO API seamlessly and enables real user interaction with your components through the WebDriver protocol. This makes those interactions more realistic compared to emitting them through JavaScript. It comes also with 1st class support for popular utility frameworks such as Testing Library and allows to use both APIs interchangeably. Check out how you can use Testing Library for rendering and fetching elements while using WebdriverIO for interacting with the component:

import { $, expect } from '@wdio/globals'
import { render } from '@testing-library/vue'
import Component from './components/Component.vue'

describe('Vue Component Testing', () => {
    it('increments value on click', async () => {
        // The render method returns a collection of utilities to query your component.
        const { getByText } = render(Component)

        // getByText returns the first matching node for the provided text, and
        // throws an error if no elements match or if more than one match is found.
        getByText('Times clicked: 0')

        const button = await $(getByText('increment'))

        // Dispatch a native click event to our button element.
        await button.click()
        await button.click()

        getByText('Times clicked: 2') // assert with Testing Library
        await expect($('p=Times clicked: 2')).toExist() // assert with WebdriverIO
    })
})

The new browser runner allows you to load and execute tests within the browser rather than in Node.js. This allows you to access all Web APIs to render web components or to run unit tests for your frontend modules. Under the hood it uses Vite to load all dependencies and make the integration seamless.

If you have been using Karma for running unit tests in the browser you can switch over to WebdriverIO which provides the same capabilities but offers better support and integration to other services and reporters. It also seems that the Karma project is not much maintained these days and has unresovled security vulnerabilities.

New Action Interface​

For many years users that liked to run more complex interactions on their applications using WebDriver's actions API had to know many details about the command to construct the correct payload. With v8 of WebdriverIO, we now ship a new interface that makes executing various actions much easier.

With two new browser commands: action and actions, it is now much simpler and type-safe to run the right action, e.g. sending key events to the browser:

await browser.action('key')
    .down('f').up('f')
    .down('o').up('o')
    .down('o').up('o')
    .perform()

Read more on the new action interface in the WebdriverIO API.

WebDriver BiDi Support​

A strong argument to use WebdriverIO as opposed to other tools is the fact that it is based on the WebDriver protocol, which is a web standard for automating browsers. It guarantees the ability to run tests in browsers that are used by your users as opposed to a browser engine, which can be very different from a feature and security aspect. The W3C Working Group has been working on a new version of the protocol that will enable better introspection capabilities and new automation primitives.

With this release, users can start accessing these new protocol features as they become available in browsers. Over time more commands will transition to the new protocol under the hood while the interface remains the same. We are all very excited about the new capabilities and opportunities this protocol will provide, e.g. listening to log events while running tests, e.g.:

await browser.send({
    method: 'session.subscribe',
    params: { events: ['log.entryAdded'] }
})

/**
 * returns:
 * {
 *    "method":"log.entryAdded",
 *    "params":{
 *       "type":"console",
 *       "method":"log",
 *       "realm":null,
 *       "args":[
 *          {
 *             "type":"string",
 *             "value":"Hello Bidi"
 *          }
 *       ],
 *       "level":"info",
 *       "text":"Hello Bidi",
 *       "timestamp":1657282076037
 *    }
 * }
 */
browser.on('message', (data) => console.log('received %s', data))

/**
 * trigger listener
 */
await browser.execute(() => console.log("Hello Bidi"))

We are following and supporting the development of all browser vendors to ensure new features are working as expected and can be used through a lean user interface. For more information on this topic check out my talk on The Evolution of Browser Automation.

Optional Globals​

When using the WebdriverIO test runner it would usually register the browser object or the $ and $$ command to the global scope as these are usually often used when writing tests. However, attaching objects to the global scope is not seen as best practice and can cause side effects when other modules decide to do the same. Therefore with v8, it is now up to the user whether they like to continue attaching these objects and methods to the global scope or prefer importing them directly, via:

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

A new configuration property called injectGlobals (defaults: true) handles whether the test runner modifies the global scope or not. If your setup works fine using global objects, no change is needed to update to v8. However, we recommend importing WebdriverIO-related interfaces directly to ensure no side effects can happen.

Note: If you are using TypeScript, updates to the tsconfig.json are necessary to reflect changes made to the location of the WebdriverIO types. These are now part of the @wdio/globals package:

{
    "compilerOptions": {
        "types": [
            "node",
-           "webdriverio/async"
+           "@wdio/globals/types"
        ]
    }
}

Miscellaneous​

Aside from these major updates, the team has spent time improving the documentation and introduced new API docs around WebdriverIO objects like browser, element and mock. Furthermore, we removed the config property from the browser object. If you have been using it to access data from the WDIO config, we suggest replacing it with options, e.g.:

- browser.config.hostname
+ browser.options.hostname

Furthermore did we fix the behavior of relative spec or exclude paths. Before v8 every path within specs, exclude or --spec was always seen relative from the users working directory. This behavior was confusing especially when the wdio.conf.js was not within the root of you project. This got fixed now so that specs and exclude path will be always seen as relative to the config file and --spec arguments, relative from the working directory.

Lastly, we had to remove support for tsconfig-paths as we haven't found a way to get it working within an ESM context. We believe this integration hasn't been used much anyway and a lot of it is nowadays natively supported in TypeScript. Let us know if this assumption is wrong and you would like to see it being supported again.

What's Next?​

The WebdriverIO team is very excited about this release as it frees up time to start working on some new cool features we put on the roadmap. For many months we have been working secretly on a VS Code Extension that makes authoring and debugging tests much easier. Aside from that, there is always plenty more work to do and opportunities to explore to make this project better. We are welcoming and supporting everyone who likes to join us.

Lastly, I would like to say thank you to everyone who supports the project. Not only the folks who contribute financially through Open Collective or Tidelift but also everyone who contributes code, ideas, reports issues or supports folks in our support chat, occasionally or on regular basis. Without contributions from the community, this project can't go anywhere. Aside from many alternative projects WebdriverIO is not funded, nor driven by any corporate interest and stays 100% community governed. No lack of funding or need for capital gains will have an impact on this project. It has been like this since its inception more than 10 years ago and will continue to be like this for many many more years. Therefore we are always looking for interested folks who like to help us hack on the project. If you haven't, join our Open Office Hours and consider giving back to the project.

I am looking forward to more years and great features ahead. Thanks for reading!

With the accessibility selector introduced in version v7.24.0 WebdriverIO now provides a powerful way to fetch various of elements containing a certain accessibility name. Rather than applying arbitrary data-testId properties to elements which won't be recognised by assistent devices, developers or QA engineers can now either apply a correct accessibility name to the element themselves or ask the development team to improve the accessibility so that writing tests becomes easier.

WebdriverIO internally uses a chain of xPath selector conditions to fetch the correct element. While the framework has no access to the accessibility tree of the browser, it can only guess the correct name here. As accessibility names are computed based on author supplied names and content names, WebdriverIO fetches an element based in a certain order:

1. First we try to find an element that has an aria-labelledBy or aria-describedBy property pointing to an element containing a valid id, e.g.:

   <h2 id="social">Social Media</h2>
   <nav aria-labelledBy="social">...</nav>
   

   So we can fetch a certain link within our navigation via:

   await $('aria/Social Media').$('a=API').click()
   

2. Then we look for elements with a certain aria-label, e.g.:

   <button aria-label="close button">X</button>
   

   Rather than using X to fetch the element or applying a test id property we can just do:

   await $('aria/close button').click()
   

3. Well defined HTML forms provide a label to every input element, e.g.:

   <label for="username">Username</label>
   <input id="username" type="text" />
   

   Setting the value of the input can now be done via:

   await $('aria/Username').setValue('foobar')
   

4. Less ideal but still working are placeholder or aria-placeholder properties:

   <input placeholder="Your Username" type="text" />
   

   Which can now be used to fetch elements as well:

   await $('aria/Your Username').setValue('foobar')
   

5. Furthermore if an image tag provides a certain alternative text, this can be used to query that element as well, e.g.:

   <img alt="A warm sommer night" src="..." />
   

   Such an image can be now fetched via:

   await $('aria/A warm sommer night').getTagName() // outputs "img"
   

6. Lastly, if no proper accessibility name can be derived, it is computed by its accumulated text, e.g.:

   <h1>Welcome!</h1>
   

   Such a heading tag can be now fetched via:

   await $('aria/Welcome!').getTagName() // outputs "h1"
   

As you can see, there are a variety of ways to define the accessibility name of an element. Many of the browser debugging tools provide handy accessibility features that help you to find the proper name of the element:

For more information check out the Chrome DevTools or Firefox Accessibility Inspector docs.

Accessibility is not only a powerful tool to create an inclusive web, it can also help you write stable and readable tests. While you should not go ahead and give every element an aria-label, this new selector can help you build web applications with accessibility in mind so that writing e2e tests for it later on will become much easier.

Thanks for reading!

In fact, it's one of my favourites ❤️

But, to write truly great acceptance tests you need more than that:

• You need business-friendly abstractions that capture the language of your domain and make even the most sophisticated, multi-actor, and cross-system workflows easy to design and adapt as the requirements change.
• You need in-depth reporting that tells you not only what tests were executed, but also what requirements and business capabilities have (and have not!) been tested.
• And on top of that, you need to be able to interact with all the interfaces of your system, so that the slower UI-based interactions are just one tool in your testing toolbox, rather than your only option.

Of course, all the above is way outside of the scope of what WebdriverIO is trying to accomplish.

Typically, you and your team would need to figure it out all by yourselves.

But, what if I told you that there was a better way? That there was another framework that's perfectly compatible with WebdriverIO and optimised to help you write world-class, full-stack acceptance tests following the Screenplay Pattern and SOLID design principles, even if not everyone on your team is an experienced test engineer?

What if I told you that this framework also covers business-friendly reporting and helps you write high-quality test code that's easy to understand, maintain, and reuse across projects and teams?

What if I told you that you could add it to your existing WebdriverIO test suites, today?

Please allow me to introduce, Serenity/JS!

About Serenity/JS​

Serenity/JS is an open-source acceptance testing and integration framework, designed to make writing truly great acceptance tests easier, more collaborative, and fun! 🚀

While you can use Serenity/JS to test systems of any complexity, it works particularly well in complex, workflow-based, multi-actor contexts.

At a high level, Serenity/JS is a modular framework that provides adapters that make it easy to integrate your tests with Web apps, REST APIs, Node.js servers, and pretty much anything a Node.js program can talk to.

Thanks to Serenity/JS Screenplay Pattern, you and your team will also have a simple, consistent, and async-friendly programming model across all those interfaces.

Apart from integrating with your system under test, Serenity/JS can also integrate with popular test runners such as Cucumber, Jasmine, Mocha, Protractor, and now also WebdriverIO!

Better yet, Serenity/JS provides a unique reporting system to help you generate consistent test execution and feature coverage reports across all the interfaces of your system and across all your test suites. Serenity/JS reporting services can work together with your existing WebdriverIO reporters too!

Thinking in Serenity/JS​

The best way to get started with Serenity/JS is to follow our brand-new series of tutorials, where you'll learn how to build full-stack test automation frameworks from scratch.

Check out "Thinking in Serenity/JS" 🤓

Examples and project templates​

If you prefer to kick the tires and jump straight into the code, you'll find over a dozen example projects in the Serenity/JS GitHub repository and plenty of code samples in our API docs.

We've also created WebdriverIO + Serenity/JS project templates to help you get started:

• WebdriverIO, Serenity/JS and Cucumber
• WebdriverIO, Serenity/JS and Mocha

All the above templates are configured to produce Serenity BDD HTML reports, automatically capture screenshots upon test failure, and run in a Continuous Integration environment.

Adding Serenity/JS to an existing project​

If you're using WebdriverIO with Mocha, run the following command in your computer terminal to add the relevant Serenity/JS modules to your project:

npm install --save-dev @serenity-js/{code,console-reporter,mocha,webdriverio}

If you're using Cucumber or Jasmine instead, replace mocha with the name of your preferred test runner, so cucumber or jasmine, respectively.

Next, tell WebdriverIO to use Serenity/JS instead of the default framework adapter:

import { ConsoleReporter } from '@serenity-js/console-reporter';
import { WebdriverIOConfig } from '@serenity-js/webdriverio';

export const config: WebdriverIOConfig = {

    // Enable Serenity/JS framework adapter
    // see: https://serenity-js.org/modules/webdriverio/
    framework: '@serenity-js/webdriverio',

    serenity: {
        // Use Serenity/JS test runner adapter for Mocha
        runner: 'mocha',        // see: https://serenity-js.org/modules/mocha/
        // runner: 'jasmine',   // see: https://serenity-js.org/modules/jasmine/
        // runner: 'cucumber',  // see: https://serenity-js.org/modules/cucumber/

        // Configure reporting services
        // see: https://serenity-js.org/handbook/reporting/
        crew: [
            ConsoleReporter.forDarkTerminals(),
        ],
    },

    // ... other WebdriverIO configuration
}

And that's it!

The above configuration enables Serenity/JS Console Reporter, which produces output similar to the below and plays nicely with any existing WebdriverIO reporters you might have already configured:

To enable Serenity BDD HTML Reporter, please follow the instructions.

To learn about Serenity/JS Screenplay Pattern, follow the tutorial.

Questions? Feedback? Ideas?​

If you have questions about Serenity/JS or need guidance in getting started, join our friendly Serenity/JS Community Chat channel.

For project news and updates, follow @SerenityJS on Twitter.

And if you like Serenity/JS and would like to see more articles on how to use it with WebdriverIO, remember to give us a ⭐ on Serenity/JS GitHub! 😊

Enjoy Serenity!

Jan

Running asynchronous commands in a synchronous way was possible with the help of the @wdio/sync package. If installed, WebdriverIO would automatically wrap the commands with utility methods that were using the fibers package to create a synchronous execution environment. It uses some internal V8 APIs to allow to jump between multiple call stacks from within a single thread. This approach also has been popular among other projects, e.g. Meteor, where most of the code is written using asynchronous APIs which causes developers to constantly start the line of code with await.

Last year the author of the Fibers package announced that he would no longer continue to maintain the project anymore. He built Fibers when JavaScript did not have any proper mechanism to handle asynchronous code other than using callbacks. With JavaScript evolving and adding APIs like Promises or Generators there is technically no reason anymore for Fibers to exist other than preference of code style. Now with the release of Node.js v16 and the update to V8 v9 Fibers stopped working due to a change in V8 that would remove some internal interfaces Fibers was using. Given that a fix for this is non trivial and the maintainer already stepped down from the project it is unlikely that we will see support for Fibers in Node.js v16 and on.

After the WebdriverIO team discovered this we immediately took action and evaluated our options. We opened an RFC to discuss with the community in which direction the project should go. I would like to thank everyone who chimed in and provided their opinion. We experimented with some alternative options, e.g. using Babel to transpile synchronous code into asynchronous but they all failed due to various reasons. The ultimate decision was made to accept the fact that synchronous command execution won't be possible moving on and rather embrace asynchronicity.

With the release of WebdriverIO v7.9 we are happy to announce that we improved our asynchronous API and matched it with the synchronous one. When chaining element command calls users had to write aweful code like this before:

await (await (await $('#foo')).$$('.bar'))[42].click()

now this got simiplified to this:

await $('#foo').$$('.bar')[42].click()

Thanks to the enormous power of the Proxy Object the API is now much more streamlined and less verbose. This will also help users migrating a project that uses the synchronous API to become asynchronous. The team will work on a codemod to help make this process as automated and easy as possible.

At this point the WebdriverIO team wants to thank Marcel Laverdet (@laverdet on GitHub) for building Fibers and maintaining it for so many years. It is time to move on and embrace all the great JavaScript language feature many people have worked hard on. While we have updated the code examples in our docs, @wdio/sync will continue to be supported until we drop support for Node.js v14 and earlier which won't happen before April 2023. You will have enough time to slowly migrate your tests using async/await.

If you have any questions on this or the migration from a framework writing with synchronous commands to asynchronous code, feel free to drop us a line in our discussion forum or on our community Discord support server.

Choosing WebdriverIO​

Before our migration to WebdriverIO, we had been using an open sourced Ruby framework on top of Cucumber. JW Player is officially supported on seven desktop and mobile web browsers, as well as iOS and Android versions dating back to 10 and 4.4, respectively. For coverage of these platforms, we run approximately 25,000 UI acceptance tests on a nightly basis. The legacy implementation created two problems. First, we encountered performance limitations in Ruby, as a single test run across all platforms could take up to 9 hours. Second, as the Player is implemented in JavaScript, product engineers were less likely to embrace and contribute to the Ruby-based framework. Moving to a JavaScript-native framework addressed both of these problems.

Selenium Webdriver has long been the go-to standard for web automation. Around 2018, our team began to explore several new emerging testing technologies. Cypress had limited browser support, Microsoft Playwright had not yet even been released, and Puppeteer would only execute on Chrome. A Webdriver-based solution, with its broad and dedicated support amongst browser vendors, was the clear winner.

What initially attracted us to WebdriverIO was its straightforward API and complete support for all browsers and devices we needed to test, compared to Cypress and Puppeteer which lack support for one or more of the necessary platforms. More importantly, though, was its rich plugin system and active, engaged developer community. Sponsorship from Sauce Labs, which had already made a name for itself within the testing space, gave us confidence that WebdriverIO would continue to grow and not become abandonware.

Out of the box, WebdriverIO had support for several of our existing and desired toolsets. Tools such as Allure reporting, which we use to quickly comb through product defects, as well as Report Portal, which we use to monitor test health and track trends over time, were easy for us to integrate. The granular pre and post execution hooks gave the test engineers an unprecedented ability to shape how and where tests executed.

Webdriver.IO Practical Approach​

As more features keep being added to WebdriverIO, we are continually able to simplify our codebase by removing open source dependencies and messy mixin code. We have even been able to decommission services that our old framework relied on altogether.

• The Network Primitives feature, released last year, allowed us to remove our dependency on Browsermob Proxy, a proxy tool commonly used in Selenium Webdriver applications to intercept and manipulate HTTP requests. We now call browser.mock(), specify a substring or regex of the request we want to capture and supply a simple mock object to replace the asset. The ability to delay a response allowed us to automate several complicated tests which had required manual execution. We were then able to validate the player’s behavior when particular requests, such as ads, are delayed due to network or other external conditions:

  // mock.js
  export function delayResponse3seconds() {
      return new Promise((resolve) => setTimeout(() => {
          return resolve('{ "foo": bar }');
      }, 3000));
  }
  
  // test.js
  import { delayResponse3seconds } from './mock';
  
  function rewritePattern(pattern, replacement) {
     console.log(`Attempting to rewrite: ${pattern} with: ${replacement}`);
     const toRewrite = browser.mock(`**/${pattern}`);
     toRewrite.respond(delayResponse3seconds);
     console.log(`Successfully rewrote ${pattern} to ${replacement}`);
  }
  

• The Chrome Devtools Protocol support that comes out of the box has also enabled us to automate some tests that were a manual chore. Being able to call browser.throttle(“Good3G”) after our initial page load has allowed us to more accurately verify how the video player behaves under more real world conditions for our mobile users.

• Thanks to WebdriverIO’s CDP mapping, we have been able to create and maintain a suite of performance tests. Calling browser.getMetrics() after a page load and interacting with the player has enabled us to verify that once a player is set up and embedded onto a customer’s website, it will not cause any undue Cumulative Layout Shifts for the end user, which create a disruptive page loading experience.

Summary​

Overall, JW Player’s migration to WebdriverIO was nothing short of a huge success. Between the performance and “quality of life” improvements over our old framework, WebdriverIO’s feature set has allowed us to automate a couple of hundred manual test cases. We've been able to greatly cut down the length of our regression cycles from approximately 1 week to just a couple of days. Most importantly, however, these improvements have allowed us to find a record number of defects, leading to a better quality product and delivering more customer value.

If your company uses WebdriverIO and benefits from it, please ask your manager or your marketing team to support the project by donating to the collective. Support will allow the maintainers to dedicate more time for maintenance and new features for everyone.

As part of this we also like to announce the official WebdriverIO Swag Store: shop.webdriver.io, which will be used as an income source for the collective. All purchases from that store will directly go into our fund and to you. We start our collection with a T-shirt, a sweatshirt and a couple of accessories but will soon extend to more. So stay tuned!

We want to be transparent in the way we accept expenses to the collective. Everyone should be eligible to participate and send in expenses for development on certain features. We also want to give back to the community by allowing us to expense event expenses. The following expense types may be eligible to be reimbursed from the collective:

Event Expenses​

If you host an event that has a speaker talking about using WebdriverIO and it's features you can expense up to $100. Reimbursement requirements for event expenses include:

• You or the event account must share the project on social media (Twitter, Facebook or LinkedIn) at least 3x
• The event page must have the WebdriverIO logo and a link to the project page in your meetup description
• You must use the funds for qualified event expenses such as food, beverage, room or equipment rental.
• You must submit receipts with your reimbursement request.