@wdio/sauce-service

What is @wdio/sauce-service?

@wdio/sauce-service is a WebdriverIO service that provides integration with Sauce Labs, a cloud-based platform for testing web and mobile applications. It allows you to run your WebdriverIO tests on Sauce Labs' infrastructure, which includes a wide range of browsers and devices.

What are @wdio/sauce-service's main functionalities?

Sauce Labs Integration

This feature allows you to configure and run your WebdriverIO tests on Sauce Labs. The code sample demonstrates how to set up a test with Sauce Labs using WebdriverIO, specifying the browser, platform, and Sauce Labs options.

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

const options = {
  user: 'your-username',
  key: 'your-access-key',
  services: ['sauce'],
  capabilities: {
    browserName: 'chrome',
    platformName: 'Windows 10',
    browserVersion: 'latest',
    'sauce:options': {
      name: 'My Test',
      build: 'Build-1234'
    }
  }
};

async function main() {
  const browser = await remote(options);
  await browser.url('https://www.example.com');
  console.log(await browser.getTitle());
  await browser.deleteSession();
}

main();

Automatic Test Reporting

This feature provides automatic reporting of test results to Sauce Labs. The code sample shows how to handle test execution and ensure that results are reported back to Sauce Labs, even if the test fails.

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

const options = {
  user: 'your-username',
  key: 'your-access-key',
  services: ['sauce'],
  capabilities: {
    browserName: 'chrome',
    platformName: 'Windows 10',
    browserVersion: 'latest',
    'sauce:options': {
      name: 'My Test',
      build: 'Build-1234'
    }
  }
};

async function main() {
  const browser = await remote(options);
  try {
    await browser.url('https://www.example.com');
    console.log(await browser.getTitle());
  } catch (error) {
    console.error('Test failed', error);
  } finally {
    await browser.deleteSession();
  }
}

main();

Other packages similar to @wdio/sauce-service

webdriverio

WebdriverIO is a popular testing framework for Node.js that allows you to run tests on various browsers and devices. While it provides the core functionality for running tests, @wdio/sauce-service specifically integrates WebdriverIO with Sauce Labs, offering additional features like automatic test reporting and Sauce Labs-specific configurations.

saucelabs

The saucelabs package is a Node.js client for the Sauce Labs REST API. It allows you to interact with Sauce Labs directly, managing jobs, tunnels, and more. While it provides a broader API interaction capability, @wdio/sauce-service is specifically designed to work with WebdriverIO to streamline the process of running tests on Sauce Labs.

README

WebdriverIO Sauce Service

WebdriverIO service that provides a better integration into Sauce Labs. This service can be used for:

• the Sauce Labs Virtual Machine Cloud (Desktop Web/Emulator/Simulator)
• the Sauce Labs Real Device cloud (iOS and Android)

It can update the job metadata ('name'*, 'passed', 'tags', 'public', 'build', 'custom-data') and runs Sauce Connect if desired.

What else will this service do for you:

• By default the Sauce Service will update the 'name' of the job when the job starts. This will give you the option to update the name at any given point in time.
• You can define a setJobName parameter and customise the job name according to your capabilities, options and suite title
• The Sauce Service will also push the error stack of a failed test to the Sauce Labs commands tab
• It will allow you to automatically configure and spin up Sauce Connect
• And it will set context points in your command list to identify which commands were executed in what test

Installation

The easiest way is to keep @wdio/sauce-service as a devDependency in your package.json, via:

npm install @wdio/sauce-service --save-dev

Instructions on how to install WebdriverIO can be found here.

Configuration

To use the service for the Virtual Desktop/Emulator/Simulator Machine and Real Device cloud you need to set user and key in your wdio.conf.js file. It will automatically use Sauce Labs to run your integration tests. If you run your tests on Sauce Labs you can specify the region you want to run your tests in via the region property. Available short handles for regions are us (default) and eu. These regions are used for the Sauce Labs VM cloud and the Sauce Labs Real Device Cloud. If you don't provide the region, it defaults to us.

If you want WebdriverIO to automatically spin up a Sauce Connect tunnel, you need to set sauceConnect: true. If you would like to change the data center to EU add region:'eu' as US data center is set as default.

// wdio.conf.js
export const config = {
    // ...
    user: process.env.SAUCE_USERNAME,
    key: process.env.SAUCE_ACCESS_KEY,
    region: 'us', // or 'eu'
    services: [
        ['sauce', {
            sauceConnect: true,
            sauceConnectOpts: {
                // ...
            }
        }]
    ],
    // ...
};

If you want to use an existing Sauce Connect tunnel you only need to provide a tunnelIdentifier, or if you are using a parent tunnel, include the parentTunnel in the capabilities like this:

<Tabs defaultValue="tunnelidentifier" values={[ {label: 'Tunnel Identifier', value: 'tunnelidentifier'}, {label: 'Parent Tunnel', value: 'parenttunnel'} ] }>

export const config = {
    // ...
    {
        browserName: 'chrome',
        platformName: 'Windows 10',
        browserVersion: 'latest',
        // Sauce options can be found here https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options
        'sauce:options': {
            tunnelIdentifier: 'YourTunnelName',

            // Example options
            build: 'your-build-name',
            screenResolution: '1600x1200',
            // ...
        },
    },
    // ...
};

export const config = {
    // ...
    {
        browserName: 'chrome',
        platformName: 'Windows 10',
        browserVersion: 'latest',
        // Sauce options can be found here https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options
        'sauce:options': {
            tunnelIdentifier: 'ParentTunnelName',
            parentTunnel: '<username of parent>,

            // Example options
            build: 'your-build-name',
            screenResolution: '1600x1200',
            // ...
        },
    },
    // ...
};

```

Sauce Service Options

To authorize the Sauce Labs service your config needs to contain a user and key option.

maxErrorStackLength

This service will automatically push the error stack to Sauce Labs when a test fails. By default, it will only push the first 5 lines, but if needed this can be changed. Be aware that more lines will result in more WebDriver calls which might slow down the execution.

Type: number
Default: 5

sauceConnect

If true it runs Sauce Connect and opens a secure connection between a Sauce Labs virtual machine running your browser tests.

Type: Boolean
Default: false

sauceConnectOpts

Apply Sauce Connect options (e.g. to change port number or logFile settings). See this list for more information. Per default, the service disables SC proxy auto-detection via `noAutodetect`` as this can be unreliable for some machines.

NOTE: When specifying the options the -- should be omitted. It can also be turned into camelCase (e.g. shared-tunnel or sharedTunnel).

Type: Object
Default: { noAutodetect: true }

uploadLogs

If true this option uploads all WebdriverIO log files to the Sauce Labs platform for further inspection. Make sure you have outputDir set in your wdio config to write logs into files, otherwise data will be streamed to stdout and can't get uploaded.

Type: Boolean
Default: true

setJobName

Allows users to dynamically set the job name based on worker parameters such as WebdriverIO configuration, used capabilities and the original suite title.

Type: Function
Default: (config, capabilities, suiteTitle) => suiteTitle

---

Overriding generated name metadata

The service automatically generates a name for each test from the suite name, browser name and other information.

You can override this by providing a value for the name desired capability, but this will have the side effect of giving all tests the same name.

---

For more information on WebdriverIO see the homepage.

Changelog

v9.7.3 (2025-02-05)

:bug: Bug Fix

• webdriverio
  • #14153 fix(webdriverio): properly run and test switch to frame by function (@christian-bromann)
  • #14128 fix(webdriverio): reset context on navigation events (@christian-bromann)

:nail_care: Polish

• wdio-cli
  • #14132 Copy capability before onWorkerStart is called (@mato533)

Committers: 2

• Christian Bromann (@christian-bromann)
• @mato533