Load testing with WebdriverIO

Enable multiple scenarios

In the Load Configuration section, enable the Multiple Scenarios toggle.

Add a new scenario

Click Add Scenario to create a new scenario.

Configure scenario details

For each scenario:

• Provide a unique name for easy identification.
• Select the desired test cases using the supported selector types.
• Provide load configuration details like number of VUs, load profile and regions.

For WebDriverIO tests, the following selector types are supported:

Add additional scenarios

Repeat the process to add more scenarios as needed, up to the maximum limit of 10 scenarios per test.

Review the configuration

Review the configuration to ensure all scenarios are set up correctly.

Specify the test type

testType defines the type of load test that you want to execute. Currently, Playwright, Selenium and WebdriverIO are supported. Set this to WebdriverIO for a load test using WebdriverIO test suite.

Specify the path

The files block specifies the key files required to install dependencies and define which tests should be executed.

• Under dependencies, add the path to files required to set up the environment. For Node.js projects, include the path to your package.json.
• Under testConfigs, add the path to your wdio.conf.jsconfiguration file.

Specify number of virtual users

Set vus to the maximum number of virtual users to simulate during the test. The max limit for this config is currently 100. Contact us if you want to increase this limit.

Set Regions

• Use the loadzone sub-config to specify each region. For each region, set the traffic percentage using the percent sub-config.
• Make sure that the total percentage equals 100.

Set duration

Each virtual user (VU) repeatedly executes the test(s) in a loop until the specified duration ends.

How to set duration values:

• If less than 1 minute: use seconds (_s), e.g., 45s
• If less than 1 hour: use minutes and seconds (_m_s), e.g., 12m30s , 10m
• If 1 hour or more: use hours, minutes, and seconds (_h_m_s), e.g., 1h5m20s, 1h17m, 1h

Default value: By default, the duration is set to the time required to complete a single iteration of your test(s).
The maximum limit is 20 minutes, which you can extend on request.

You can set a constant duration or configure ramping VUs to model various load scenarios.

Configure Ramping VUs

If you want to gradually increase or decrease VUs over time, use the loadprofile config instead of duration. This approach lets you model realistic traffic patterns such as ramp-ups, peak holds, and ramp-downs.

• Under the loadProfile block, set type to ramping to enable staged traffic changes.
• Under stages, add one or more steps:
  • type: ramp increases or decreases VUs from from to to over duration. Result: VUs change linearly until they reach the target.
  • type: hold keeps VUs constant for duration. Result: VUs stay at the specified level without change.
• Keep stage durations realistic. Very short ramps can cause bursty load that is hard to analyze.
• Ensure your total vus is high enough to cover the largest stage to value. If not, the test cannot reach the target VUs.

Validation rules:

• Each stage must include type, from, to, and duration.
• Use valid time units (Xs, Xm, Xh). Example: 45s, 10m, 1h5m.
• from and to must be non-negative integers and must not exceed the global vus limit.
• Avoid overlapping or contradictory stages (for example, alternating rapid up/down ramps) unless you are testing resilience to bursty traffic.

Set iterations

Use iterations to control how many times each virtual user (VU) executes your test script:

• Set iterations: positive integer per VU.
• Combine with duration if needed: when both are set, the test stops when either the max duration or the per‑VU iterations are reached, whichever comes first.

Headless mode

You can configure your WebdriverIO load tests to run in either headless or headful mode using the headless capability.

• Headless mode (default): The browser runs without a visible UI, which is faster and consumes fewer resources. Most CI/CD and automated load tests use headless mode.
• Headful mode: The browser UI remains visible during test execution.

If not specified, tests will run in headless mode by default.

Set environment variables

The env config lets you pass an array of name-value string pairs to set environment variables on the remote machines where tests are executed.
Currently, a maximum of 20 pairs is allowed.

Environment variables can be set using any one of the following two methods:

Inline variables

Declare each variable with a name and value. BrowserStack injects these pairs into the test environment.

File-based variables:

Use sources to reference one or more files containing environment variables (for example, .env files). Use variables to add or override specific pairs. Result: the system loads values from files first, then applies overrides.

Test data configuration

Use test data to inject external values so each virtual user (VU) runs with different inputs. This helps you simulate real-world traffic without hard-coding values into your scripts.

Add the filepath, delimiter and vuMappingStrategy values to the testData block. Ensure that the filepath value should use relative paths instead of absolute paths. You can add up to three files under the testData block.

const row = await readFirstRow('test-data-extra.csv');

export async function readFirstRow(csvFilePath) {
  return new Promise((resolve, reject) => {
    let firstRow = null;
    const fullPath = path.resolve(csvFilePath);
    
    const stream = fs.createReadStream(fullPath)
      .pipe(csv())
      .on('data', (data) => {
        if (!firstRow) {
          firstRow = data;
          stream.destroy(); // Stop reading after first row
        }
      })
      .on('end', () => {
        console.log(`Read first row from ${csvFilePath}`);
        resolve(firstRow);
      })
      .on('close', () => {
        if (firstRow) {
          console.log(`Read first row from ${csvFilePath}`);
          resolve(firstRow);
        }
      })
      .on('error', (error) => {
        console.error(`Error reading CSV file: ${error.message}`);
        reject(error);
      });
  });
}

Set reporting structure

Use projectName to group related tests under the same project on the dashboard. Use testName to group multiple runs of the same test.
Both projectName and testName must remain consistent across different runs of the same test.
You can use the following characters in projectName and testName:

• Letters (A–Z, a–z)
• Digits (0–9)
• Periods (.), colons (:), hyphens (-), square brackets ([]), forward slashes (/), at signs (@), ampersands (&), single quotes ('), and underscores (_)
  All other characters are ignored.

Capture response details

Set to captureErrorResponses to true to record full request–response data for failing HTTP calls during the test.

Network throttling

Network throttling enables you to run load tests under real-world network conditions. This helps you understand how your application behaves for users on different connection types.

Simulate common networks or define a custom network profile. Network throttling applies to all virtual users in the test.

Supported modes

The following two modes are supported for configuring network throttling:

Set thresholds

Use thresholds to determine test pass or fail based on metrics.

Available Metric list and corresponding keys for load testing:

• Avg. response time - avg-response-time
• p90 response time - p90-response-time
• Avg. request rate - avg-request-rate
• Total requests - total-requests
• Error % - error-percentage
• Error count - error-count
• p75 LCP- p75-lcp
• p75 FCP- p75-fcp
• p75 INP- p75-inp
• p75 CLS- p75-cls
• p75 TTFB - p75-ttfb

Available conditions:

• =
• !=
• >
• <
• >=
• <=

We assume the following units for the metrics:

• Avg. response time, p90 response time, INP, TTFB - ms
• Avg. request rate - reqs/s
• Error % - %
• FCP, LCP - s
• Total requests, Error count, CLS - no unit

Configure multiple scenarios

The Multiple Scenarios feature allows you to simulate diverse user behaviors by executing different test flows simultaneously within a single load test. You can configure up to 10 distinct scenarios per test using two different configuration modes.

Test selector types

For WebDriverIO tests, the following selector types are supported:

Individual config mode

Each scenario defines its own VUs, duration (or iterations), and regions independently. This mode provides complete control over each scenario’s load characteristics.

Load percent mode

Distribute global VUs, duration, and regions across scenarios by percentage. All scenarios must use loadPercent and percentages must sum to 100.