locust --help
Enter the lockust help information from the console
$locust --help
Usage: locust [OPTIONS] [UserClass ...]
Common options:
-h, --help show this help message and exit
-f LOCUSTFILE, --locustfile LOCUSTFILE
Python module to import, e.g. '../other_test.py'. Either a .py file or a package directory. Defaults to 'locustfile'
--config CONFIG Config file path
-H HOST, --host HOST Host to load test in the following format: http://10.21.32.33
-u NUM_USERS, --users NUM_USERS
Peak number of concurrent Locust users. Primarily used together with --headless or --autostart. Can be changed during a test by keyboard inputs w, W (spawn 1, 10 users) and s, S (stop 1, 10 users)
-r SPAWN_RATE, --spawn-rate SPAWN_RATE
Rate to spawn users at (users per second). Primarily used together with --headless or --autostart
-t RUN_TIME, --run-time RUN_TIME
Stop after the specified amount of time, e.g. (300s, 20m, 3h, 1h30m, etc.). Only used together with --headless or --autostart. Defaults to run forever.
-l, --list Show list of possible User classes and exit
Web UI options:
--web-host WEB_HOST Host to bind the web interface to. Defaults to '*' (all interfaces)
--web-port WEB_PORT, -P WEB_PORT
Port on which to run web host
--headless Disable the web interface, and start the test immediately. Use -u and -t to control user count and run time
--autostart Starts the test immediately (without disabling the web UI). Use -u and -t to control user count and run time
--autoquit AUTOQUIT Quits Locust entirely, X seconds after the run is finished. Only used together with --autostart. The default is to keep Locust running until you shut it down using CTRL+C
--web-auth WEB_AUTH Turn on Basic Auth for the web interface. Should be supplied in the following format: username:password
--tls-cert TLS_CERT Optional path to TLS certificate to use to serve over HTTPS
--tls-key TLS_KEY Optional path to TLS private key to use to serve over HTTPS
Master options:
Options for running a Locust Master node when running Locust distributed. A Master node need Worker nodes that connect to it before it can run load tests.
--master Set locust to run in distributed mode with this process as master
--master-bind-host MASTER_BIND_HOST
Interfaces (hostname, ip) that locust master should bind to. Only used when running with --master. Defaults to * (all available interfaces).
--master-bind-port MASTER_BIND_PORT
Port that locust master should bind to. Only used when running with --master. Defaults to 5557.
--expect-workers EXPECT_WORKERS
How many workers master should expect to connect before starting the test (only when --headless/autostart is used).
--expect-workers-max-wait EXPECT_WORKERS_MAX_WAIT
How long should the master wait for workers to connect before giving up. Defaults to wait forever
Worker options:
Options for running a Locust Worker node when running Locust distributed.
Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, since other options such as -u, -r, -t are specified on the Master node.
--worker Set locust to run in distributed mode with this process as worker
--master-host MASTER_NODE_HOST
Host or IP address of locust master for distributed load testing. Only used when running with --worker. Defaults to 127.0.0.1.
--master-port MASTER_NODE_PORT
The port to connect to that is used by the locust master for distributed load testing. Only used when running with --worker. Defaults to 5557.
Tag options:
Locust tasks can be tagged using the @tag decorator. These options let specify which tasks to include or exclude during a test.
-T [TAG ...], --tags [TAG ...]
List of tags to include in the test, so only tasks with any matching tags will be executed
-E [TAG ...], --exclude-tags [TAG ...]
List of tags to exclude from the test, so only tasks with no matching tags will be executed
Request statistics options:
--csv CSV_PREFIX Store current request stats to files in CSV format. Setting this option will generate three files: [CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv and [CSV_PREFIX]_failures.csv
--csv-full-history Store each stats entry in CSV format to _stats_history.csv file. You must also specify the '--csv' argument to enable this.
--print-stats Print stats in the console
--only-summary Only print the summary stats
--reset-stats Reset statistics once spawning has been completed. Should be set on both master and workers when running in distributed mode
--html HTML_FILE Store HTML report to file path specified
Logging options:
--skip-log-setup Disable Locust's logging setup. Instead, the configuration is provided by the Locust test or Python defaults.
--loglevel LOGLEVEL, -L LOGLEVEL
Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL. Default is INFO.
--logfile LOGFILE Path to log file. If not set, log will go to stderr
Other options:
--show-task-ratio Print table of the User classes' task execution ratio. Use this with non-zero --user option if some classes define non-zero fixed_count property.
--show-task-ratio-json
Print json data of the User classes' task execution ratio. Use this with non-zero --user option if some classes define non-zero fixed_count property.
--version, -V Show program's version number and exit
--exit-code-on-error EXIT_CODE_ON_ERROR
Sets the process exit code to use when a test result contain any failure or error
-s STOP_TIMEOUT, --stop-timeout STOP_TIMEOUT
Number of seconds to wait for a simulated user to complete any executing task before exiting. Default is to terminate immediately. This parameter only needs to be specified for the master process when running Locust distributed.
--equal-weights Use equally distributed task weights, overriding the weights specified in the locustfile.
--enable-rebalancing Allow to automatically rebalance users if new workers are added or removed during a test run.
User classes:
UserClass Optionally specify which User classes that should be used (available User classes can be listed with -l or --list)
Description of corresponding configuration information:
| command line | environment | configuration file | describe |
| -f,--locustfile | LOCUST_LOCUSTFILE | locustfile | The Python module to import, such as ".. / other_test.py" py file or package directory. The default is "lockfile. py" |
| -H,--host | LOCUST_HOST | host | The host address of the host load is as follows: http: //10.21.32.33 |
| -u,--users | LOCUST_USERS | users | Peak number of concurrent Locust users. Mainly used with – headless or – autostart. You can enter W, w (generate 1, 10 users) and S, S (stop 1, 10 users) through the keyboard during the test |
| -r,--spawn-rate | LOCUST_SPAWN_RATE | spawn-rate | The rate at which users are generated in (users per second). Mainly used with – headless or – autostart |
| --hatch-rate | LOCUST_HATCH_RATE | hatch-rate | ==Suppress== |
| -t,--run-time | LOCUST_RUN_TIME | run-time | Stop after the specified time, for example (300s, 20m, 3h, 1h30m, etc.). Use only with – headless or – autostart. Always run by default. |
| --web-host | LOCUST_WEB_HOST | web-host | Bind the Web interface to the host. The default is "*" (all interfaces) |
| --web-port,-P | LOCUST_WEB_PORT | web-port | The port on which the Web host is running |
| --headless | LOCUST_HEADLESS | headless | Disable the Web interface and start testing now. Use -u and -t to control the number of users and running time |
| --autostart | LOCUST_AUTOSTART | autostart | Start testing now (do not disable Web UI). Use - u and - t to control the number of users and running time |
| --autoquit | LOCUST_AUTOQUIT | autoquit | Exit Locust completely X seconds after running. Use only with – autostart. The default setting is to keep Locust running until you turn it off using CTRL+C |
| --headful | LOCUST_HEADFUL | headful | ==Suppress== |
| --web-auth | LOCUST_WEB_AUTH | web-auth | Turn on basic authentication for the Web interface. It shall be provided in the following format: user name: password |
| --tls-cert | LOCUST_TLS_CERT | tls-cert | Optional path to the TLS certificate used to provide services over HTTPS |
| --tls-key | LOCUST_TLS_KEY | tls-key | Optional path to the TLS private key used to provide services over HTTPS |
| --master | LOCUST_MODE_MASTER | master | Set locust to run in distributed mode, with this process as the main process |
| --master-bind-host | LOCUST_MASTER_BIND_HOST | master-bind-host | The interface (host name, ip address) that the lock master should bind to. Used only when running with – master. The default is * (all available interfaces). |
| --master-bind-port | LOCUST_MASTER_BIND_PORT | master-bind-port | The port to which the lock master should be bound. Used only when running with – master. The default is 5557. |
| --expect-workers | LOCUST_EXPECT_WORKERS | expect-workers | How many worker s should the master expect to connect before starting the test (only if – headless/autostart is used). |
| --expect-workers-max-wait | LOCUST_EXPECT_WORKERS_MAX_WAIT | expect-workers-max-wait | How long should the owner wait for the worker to connect before giving up. The default is to wait forever |
| --worker | LOCUST_MODE_WORKER | worker | Set locust to run in distributed mode, and this process acts as a worker |
| --master-host | LOCUST_MASTER_NODE_HOST | master-host | The host or IP address of the locust master used for distributed load testing. Used only when – worker is running. The default is 127.0.0.1. |
| --master-port | LOCUST_MASTER_NODE_PORT | master-port | The lockust master uses the port to be connected for distributed load testing. Used only when – worker is running. The default is 5557. |
| -T,--tags | LOCUST_TAGS | tags | The list of tags to include in the test, so only tasks with any matching tags will be executed |
| -E,--exclude-tags | LOCUST_EXCLUDE_TAGS | exclude-tags | The list of tags to exclude from the test, so only tasks without matching tags will be performed |
| --csv | LOCUST_CSV | csv | Store current request statistics in CSV format in a file. Setting this option will generate three files: [CSV_PREFIX]_stats.csv,[CSV_PREFIX]_stats_history.csv and [CSV_PREFIX]_failures.csv |
| --csv-full-history | LOCUST_CSV_FULL_HISTORY | csv-full-history | Store each statistics entry in csv format into the_ stats_history.csv file. You must also specify the "– csv" parameter to enable this feature. |
| --print-stats | LOCUST_PRINT_STATS | print-stats | Print statistics in the console |
| --only-summary | LOCUST_ONLY_SUMMARY | only-summary | Print summary statistics only |
| --reset-stats | LOCUST_RESET_STATS | reset-stats | Reset statistics when spawning is complete. When running in distributed mode, it should be set on both master and worker |
| --html | LOCUST_HTML | html | Store the HTML report to the specified file path |
| --skip-log-setup | LOCUST_SKIP_LOG_SETUP | skip-log-setup | Disable the logging setting for Locust. The default value is provided by Python or Locust test. |
| --loglevel,-L | LOCUST_LOGLEVEL | loglevel | Choose between debugging / information / warning / error / critical. The default is information. |
| --logfile | LOCUST_LOGFILE | logfile | The path to the log file. If not set, the log will go to stderr |
| --exit-code-on-error | LOCUST_EXIT_CODE_ON_ERROR | exit-code-on-error | Set the process exit code to use when the test result contains any failures or errors |
| -s,--stop-timeout | LOCUST_STOP_TIMEOUT | stop-timeout | The number of seconds to wait for the simulated user to complete any ongoing tasks before exiting. The default is immediate termination. This parameter only needs to be specified for the master process when the Locust distributed is running. |
environment variable
Most options that can be set through command line parameters can also be set through environment variables. example:
$LOCUST_LOCUSTFILE=custom_locustfile.py locust
configuration file
The default configuration file is: locust conf
You can use -- config to specify additional configuration files
example:
locustfile = locust_files/my_locust_file.py headless = true master = true expect-workers = 5 host = http://target-system users = 100 spawn-rate = 10 run-time = 10m
$locust --config=master.conf
When there are configurations in multiple places, the configuration information is taken in the following order
~/locust.conf -> ./locust.conf -> (file specified using --conf) -> env vars -> cmd args