Protocol load testing using k6

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 1000. Contact us if you want to increase this limit.

Specify the test scripts

The files block defines the key files needed to identify which tests to execute.

• testScripts: Set the path to the .js file.

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
  • 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.

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.

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.

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

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