Ask the Community
Protocol load testing using k6
Run a protocol load test on BrowserStack Load Testing
Prerequisites
- BrowserStack Username and Access key. You can find this under your account profile.
- An existing k6 script.
Run a test
You can start a new test either from the Quick Start page, or the Load Tests page on the Load testing dashboard.
On the dashboard, click Create Load Test.
Enter a Test Name for your load test, select API Only and click Upload scripts
Upload scripts
In this step, upload your k6 script.
Once you have verified the configuration, click Configure Load to move to the next step.
You can also run load tests using the sample scripts if you want to try out the feature before uploading your own files.
Use multi-file k6 scripts from the UI
You can upload a modular k6 test suite that uses multiple .js files and dependencies.
Upload scripts
- In the Script section of your load test configuration, choose one of the following:
- Upload a single
.jsfile. - Alternatively, you can also upload a
.zipfile that contains your main k6 script and any additional supporting files.
- Upload a single
- When you upload a
.zipfile:- Enter the main script path in the Main script field, relative to the root of the ZIP (for example,
tests/main.js). The platform uses this as the k6 entry point.
- Keep your folder hierarchy inside the ZIP. Relative imports such as
import { helper } from './utils/helper.js'continue to work because the directory structure is preserved during execution.
- Enter the main script path in the Main script field, relative to the root of the ZIP (for example,
Validation rules
- If you upload a ZIP and leave the Main script field empty, the test configuration shows an error and you cannot start the run until you specify an entry file.
- If the main script you specify does not exist inside the ZIP, the test configuration shows an error that the entry file cannot be found in the uploaded archive.
- The maximum supported ZIP size is 100 MB. If the archive exceeds this limit, the upload is rejected with a clear error message.
Use these checks to confirm the correct entry path before you run the test, so that all imports resolve successfully at runtime.
You can configure the following load parameters to customize your load test:
Run test
After you finish configuring load parameters, click RUN TEST .
Download the BrowserStack Load Testing CLI
Download the CLI based on your operating system:
Generate the YAML file
Run the given command to generate the browserstack-load.yml file which contains the configuration required to define and run your load test:
Configure your Load Test
Open the generated browserstack-load.yml file and update it with the relevant test details. Here’s a sample configuration:
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.jsfile.
Use multi-file k6 scripts with the CLI
You can run multi-file k6 tests from the CLI by configuring your test directory and entry script in browserstack-load.yml.
Update the files block
Add testDir and testScripts under the files section of your configuration.
-
testDir: Absolute path to the directory that contains all your k6 scripts and helper files. The directory is zipped and uploaded as-is, so your folder structure is preserved. -
testScripts: Absolute path to the main k6 entry script, relative totestDir.
Behavior and constraints
- The CLI validates that the entry script defined in
testScriptsexists insidetestDir. If it is missing, the run fails fast with an error. - All files and folders inside
testDirare included in the upload. Relative imports between files work as long as the referenced files live under this directory. - If your test imports a file that is not present under
testDir, the test run fails when k6 executes those imports. - Very large directories increase upload time. Keep the contents of
testDirlimited to only the scripts and dependencies required for the test run.
Set reporting structure
- Use
projectNameto group related tests under the same project on the dashboard. UsetestNameto group multiple runs of the same test. - Both
projectNameandtestNamemust remain consistent across different runs of the same test. - You can use the following characters in
projectNameandtestName:- 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.
You can configure the following load parameters to customize your load test:
- Load profiles
- Load zones
- Set thresholds
- Environment variables
- Configure multiple scenarios
- Capture response details
- Network throttling
Run the Load Test
Run the given command to start your test:
Check out the FAQs section to get answers to commonly asked questions.
View test results
Once the test starts running, you’ll get a link to the test report. You can also view your test results in the Load Testing dashboard.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!