Upload a single Python file (for example, locustfile.py) that contains your Locust test. This option works well when your script has no external dependencies beyond the Locust library and uses only the Python standard library.
The script must:
Import from Locust (for example, from locust import HttpUser, task, between).
Define at least one user class that subclasses HttpUser, FastHttpUser, User, or GrpcUser.
Sample locustfile.py
```python
from locust import HttpUser, task, between
class WebsiteUser(HttpUser):
wait_time = between(1, 5)
@task
def view_home(self):
self.client.get("/")
@task(3)
def view_products(self):
self.client.get("/products")
```
Upload a .zip archive that contains your main Locust script and any additional supporting files. Use this option when your test imports helper modules, reads from data files, or depends on third-party Python packages.
BrowserStack preserves the folder hierarchy inside the ZIP, so relative imports such as from utils.helpers import login continue to work at runtime.
The maximum supported ZIP size is 100 MB. If the archive exceeds this limit, the upload is rejected with a clear error message.
When you upload a .zip file, specify the main script path in the Main script field, relative to the root of the ZIP (for example, tests/locustfile.py). The platform uses this as the Locust entry point. If you leave this field empty or the file is not found, the test configuration shows an error and the run cannot start.
If your test uses third-party Python packages, include a requirements.txt file at the root of your ZIP. BrowserStack installs the listed packages before the run starts. Keep the install lightweight, since the install step has a 120-second timeout.
Choose a configuration file
If your ZIP contains a Locust configuration file, a Configuration File dropdown appears next to Select Main Locust script. To use the file:
Open the Configuration File dropdown.
Select your file, for example config/locust.conf.
You can select one of the following file types:
Any *.conf file, for example locust.conf or config/staging.conf
pyproject.toml
Selecting a configuration file is optional. If you don’t select one, Locust uses the locust.conf or pyproject.toml file in your upload, if it has one. The users, spawn-rate, and run-time settings in your configuration file apply only when you use your Locust script’s load configuration. If you set the load manually, these settings are ignored.
Filter tasks by tag
To run only the tasks you tagged with @tag, or to skip some of them, filter tasks by tag. You don’t need to change your script.
Turn on Filter Locust tasks by tag.
In Filter mode, select Include to run only the tasks with these tags, or Exclude to skip them.
In Tags, enter one or more tag names separated by spaces, for example checkout login.
Optional: To add another filter, for example, to exclude some tags while including others, click Add filter.
Include maps to the Locust --tags option, and Exclude maps to --exclude-tags.
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.
Configure the load
On the Load Configuration step, set how much load to generate. You can enter the load profile manually, or use the load your Locust project already defines.
Use your Locust script’s load configuration
Run the test with the load your Locust project already defines, instead of entering users and duration in BrowserStack. BrowserStack reads the load from the following sources, in this order:
A LoadTestShape class in your main script.
The users, spawn-rate, and run-time settings in your configuration file.
To use your script’s load configuration:
Go to the Load Definition tab.
Turn on Use Locust script load configuration.
The card shows the load that will run, for example, StepShape, 500 users, and 30m. The Load Profile fields are hidden while the toggle is on.
If your LoadTestShape class keeps returning users, or your configuration file doesn’t set run-time, the test runs until your plan’s maximum test duration. In this case, the card shows Runs until plan limit (N min).
An engine is one machine that generates load. Each engine runs up to 1,000 virtual users (VUs).
Go to the Advanced Settings tab.
In Engine Count, enter a number from 1 to 10. If you use more than one load zone, the engine count must be equal to or greater than the number of load zones. To let BrowserStack calculate it, leave the field empty. The field then shows Auto (recommended).
If your configuration file sets iterations, set it to a value equal to or greater than the engine count. Each engine runs at least one iteration. For example, iterations = 4 supports up to 4 engines.
To use the Locust configuration file, tag filter, script load configuration, and engine count options, download the latest version of the BrowserStack Load Testing CLI.
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:
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 maximum 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.
Single Locust file
For a test that lives in a single Python file, set testScripts to the path of that file:
If your test depends on helper modules, data files, or third-party Python packages, configure testDir along with testScripts:
testDir: Path to the directory that contains your Locust scripts, helper modules, data files, and requirements.txt. The CLI zips this directory as is and uploads it, so your folder structure is preserved.
testScripts: Path to the main Locust entry script. The path must point to a file inside testDir.
You can use absolute or relative paths. The CLI resolves a relative testDir from the folder that contains browserstack-load.yml, and a relative testScripts entry from testDir.
The CLI validates that the entry script defined in testScripts exists inside testDir. If it is missing, the run fails fast with an error.
BrowserStack includes every file and folder under testDir in the upload, so relative imports such as from utils.helpers import login continue to work at runtime.
To add third-party Python packages, place a requirements.txt file at the root of testDir. BrowserStack installs the listed packages before the run starts. Keep the install lightweight, since the install step has a 120-second timeout.
The maximum upload size is 100 MB.
If your test imports a file that is not present under testDir, the test run fails when Locust executes those imports.
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 to Z, a to z)
Digits (0 to 9)
Periods (.), colons (:), hyphens (-), square brackets ([]), forward slashes (/), at signs (@), ampersands (&), single quotes (‘), and underscores (_)
All other characters are ignored.
Use your Locust script’s load configuration
Set locustConfigSource to script. BrowserStack reads the load from your LoadTestShape class or configuration file, so you don’t need to set vus, duration, or loadProfile.
testType:locustlocustConfigSource:script
Specify a configuration file
Add one configuration file under files.testConfigs. The testConfigs path is always relative to testDir.
Set engineCount to a whole number from 1 to 10. If you use more than one load zone, the engine count must be equal to or greater than the number of load zones. To let BrowserStack calculate the engine count, leave out engineCount.
engineCount:2
If your configuration file sets iterations, set it to a value equal to or greater than the engine count. Each engine runs at least one iteration. For example, iterations = 4 supports up to 4 engines.
BrowserStack doesn’t support Locust distributed mode. The master, worker, and related settings are blocked. BrowserStack distributes the load across engines for you. To control how many engines run your test, set the engine count.
What’s next
View protocol test results: Review summary metrics, requests, assertions, and errors from your test run.
Join our Discord
