@wdio/local-runner

What is @wdio/local-runner?

@wdio/local-runner is a part of the WebdriverIO test automation framework. It allows you to run WebdriverIO tests locally on your machine. This package is particularly useful for running end-to-end tests in a local environment, providing a streamlined way to execute and manage test suites.

What are @wdio/local-runner's main functionalities?

Running Tests Locally

This feature allows you to run WebdriverIO tests locally. The code sample demonstrates how to set up a local WebdriverIO session, navigate to a URL, retrieve the page title, and then close the session.

const { remote } = require('webdriverio');

(async () => {
    const browser = await remote({
        capabilities: { browserName: 'chrome' }
    });

    await browser.url('https://webdriver.io');
    const title = await browser.getTitle();
    console.log('Title was: ' + title);

    await browser.deleteSession();
})();

Parallel Test Execution

This feature allows you to run multiple test instances in parallel, which can significantly speed up the test execution time. The code sample shows a configuration file where the `maxInstances` property is set to 5, allowing up to 5 parallel test executions.

exports.config = {
    runner: 'local',
    specs: [
        './test/specs/**/*.js'
    ],
    maxInstances: 5,
    capabilities: [{
        maxInstances: 5,
        browserName: 'chrome'
    }],
    ...
};

Custom Services

This feature allows you to integrate custom services like Selenium Standalone, Appium, etc., into your test runner. The code sample shows how to add the `selenium-standalone` service to the WebdriverIO configuration.

exports.config = {
    runner: 'local',
    services: ['selenium-standalone'],
    ...
};

Other packages similar to @wdio/local-runner

selenium-webdriver

Selenium WebDriver is a popular tool for automating web applications for testing purposes. It provides a more low-level API compared to WebdriverIO, which can be both an advantage and a disadvantage depending on the use case. Selenium WebDriver requires more boilerplate code to set up and run tests.

cypress

Cypress is a modern end-to-end testing framework that is known for its developer-friendly features and fast test execution. Unlike WebdriverIO, Cypress runs in the same run-loop as the application being tested, which can lead to more reliable tests. However, it currently only supports testing in Chrome-family browsers.

nightwatch

Nightwatch.js is an integrated, easy-to-use end-to-end testing solution for web applications and websites, written in Node.js. It uses the W3C WebDriver API to perform commands and assertions on DOM elements. Nightwatch provides a simpler syntax compared to WebdriverIO but may lack some advanced features.

README

WebdriverIO Local Runner

A WebdriverIO runner to run tests locally within worker processes

The Local Runner initiates your framework (e.g. Mocha, Jasmine or Cucumber) within worker a process and runs all your test files within your Node.js environment. Every test file is being run in a separate worker process per capability allowing for maximum concurrency. Every worker process uses a single browser instance and therefore runs its own browser session allowing for maximum isolation.

Given every test is run in its own isolated process, it is not possible to share data across test files. There are two ways to work around this:

• use the @wdio/shared-store-service to share data across all workers
• group spec files (read more in Organizing Test Suite)

If nothing else is defined in the wdio.conf.js the Local Runner is the default runner in WebdriverIO.

Install

To use the Local Runner you can install it via:

npm install --save-dev @wdio/local-runner

Setup

The Local Runner is the default runner in WebdriverIO so there is no need to define it within your wdio.conf.js. If you want to explicitly set it, you can define it as follows:

// wdio.conf.js
export const {
    // ...
    runner: 'local',
    // ...
}

---

For more information on WebdriverIO runner, check out the documentation.

Changelog

v9.4.2 (2024-12-12)

:bug: Bug Fix

• wdio-cli
  • #13963 Remove unused cli-spinners dependency (@alexparish)
  • #13944 fix(@wdio/cli): use require to import json file (@christian-bromann)
  • #13932 fix(@wdio/cli): ensure onComplete hooks is executed (@christian-bromann)
• wdio-utils, webdriverio
  • #13960 fix(webdriverio): support opening file urls (@christian-bromann)
• wdio-utils
  • #13949 fix(@wdio/utils): properly detect Appium browser sessions (@christian-bromann)
• wdio-runner
  • #13958 fix(@wdio/runner): Continue emitting event on the runner even when a reporter throws an error (@dprevost-LMI)
• webdriverio
  • #13941 fix(webdriverio): add 'appium:options' when checking for native context (@ricardorlg)
• wdio-allure-reporter, webdriver
  • #13922 fix: Catch requests failure to trigger the result and onAfterCommand event (@dprevost-LMI)

:nail_care: Polish

• wdio-cli
  • #13970 fix(@wdio/cli): Serenity/JS supports WebdriverIO 9 (@jan-molak)
• wdio-utils, webdriverio
  • #13950 fix(webdriverio): don't fail if getContext is not supported (@christian-bromann)
• wdio-browserstack-service, wdio-types
  • #13951 Changes to send SDK instrumentation in capabilities v9 (@jainam-bs)

:memo: Documentation

• #13965 Update Emulation.md - device emulation (@jochen-testingbot)

Committers: 7

• Alex Parish (@alexparish)
• Christian Bromann (@christian-bromann)
• David Prevost (@dprevost-LMI)
• Jainam Shah (@jainam-bs)
• Jan Molak (@jan-molak)
• Jochen (@jochen-testingbot)
• ricardo larrahondo (@ricardorlg)