How to use the command 'locust' (with examples)
Locust is a load-testing tool designed to help developers and testers determine the maximum number of concurrent users a system can effectively handle before performance degradation occurs. It enables users to simulate traffic against a system, identify potential bottlenecks, and effectively plan for scaling of infrastructure. With Locust, testing can be executed through the command line or a convenient web interface, offering flexibility in how tests are performed and monitored.
Load-test “example.com” with web interface using locustfile.py
Code:
locust --host=http://example.com
Motivation:
This use case allows the user to initiate a load test on a target website using a default Locust script, locustfile.py, through a user-friendly web interface. The benefit here is the ability to visually monitor and control the test, making it easily accessible for users with less command-line experience or those who prefer a graphical representation of the test’s progress and results.
Explanation:
locust: This is the basic command to run the Locust tool.--host=http://example.com: This argument specifies the target system by its domain or IP address, indicating where the load testing will be directed.
Example output:
Upon execution, a message will display on the terminal indicating that a Locust web interface is available, typically at http://localhost:8089. Users can then open a web browser to this address, input desired parameters, such as number of users and spawn rate, and start the test.
Use a different test file
Code:
locust --locustfile=test_file.py --host=http://example.com
Motivation:
Organizing different test scenarios or workflows may require the use of different Locust test scripts, particularly when dealing with multiple services or application features. This use case shows users how to specify which pre-prepared test script to use, offering flexibility to test distinct behaviors or endpoints effectively.
Explanation:
--locustfile=test_file.py: This argument changes the default script to another specified script, allowing the user to define custom load scenarios and behaviors.--host=http://example.com: As previously mentioned, this specifies the test’s target system.
Example output:
The terminal will show that Locust is using test_file.py, and similar to the first use case, a web interface link will be provided. Users manage and start testing with specific tests defined in test_file.py.
Run test without web interface, spawning 1 user a second until there are 100 users
Code:
locust --no-web --clients=100 --hatch-rate=1 --host=http://example.com
Motivation:
For environments where a web interface is not preferable or feasible—such as automated CI/CD pipelines or restricted servers—a command-line based approach is essential. This example demonstrates how tests can be run in non-interactive, scriptable modes, giving testers the control to automate testing processes effectively.
Explanation:
--no-web: This flag disables the web interface, making the tool run purely from the command line.--clients=100: Specifies the target number of concurrent users for the test.--hatch-rate=1: Indicates the rate of increasing users, with one user being added every second until the total number of users reaches 100.--host=http://example.com: Directs the load test to the specified URL.
Example output:
The console will provide real-time status updates, detailing the number of active users, requests per second, and any errors encountered during the test’s execution.
Start Locust in master mode
Code:
locust --master --host=http://example.com
Motivation:
Master mode is essential when conducting distributed load testing. This setup is ideal for simulating a very large number of users across multiple machines, enabling realistic, large-scale load tests beyond what a single machine might handle effectively.
Explanation:
--master: This flag puts Locust into master mode, where it coordinates load distribution among connected slaves (worker nodes).--host=http://example.com: Targets the system to be tested.
Example output:
The terminal provides confirmation that the master node is ready, and it will wait for incoming slave connections before any load will commence.
Connect Locust slave to master
Code:
locust --slave --host=http://example.com
Motivation:
This use case illustrates how to connect a Locust slave to a master node, part of a distributed testing configuration. By connecting multiple slaves to a master, each handling a fraction of the total load, testers can simulate larger user bases and better understand system limitations.
Explanation:
--slave: This flag designates the instance as a slave worker that will send test traffic as directed by the master node.--host=http://example.com: Although the host is not strictly necessary for the slave since it’s directed by the master, it’s included for completeness.
Example output:
The console will show a connection acknowledgment to the master, with the slave actively waiting to be instructed on the specifics of the load to simulate.
Connect Locust slave to master on a different machine
Code:
locust --slave --master-host=master_hostname --host=http://example.com
Motivation:
When slave nodes are distributed across different machines, it’s necessary to specify the master’s hostname or IP address. This configuration is useful for load testing environments that mimic real-world distributed connections, providing a more accurate representation of a system’s capability to handle globally distributed traffic.
Explanation:
--slave: Again, this flag signifies the instance as a slave.--master-host=master_hostname: This argument tells the slave where the master node is located, using either a hostname or an IP address.--host=http://example.com: Specifies the target for load testing, though the master provides this specific direction during executions.
Example output:
Successful connection messages to the designated master will appear, confirming the slave’s participation in the distributed testing setup.
Conclusion
Locust is a versatile tool that can adapt to various testing scenarios, from simple web-based tests to complex distributed load simulations. Understanding how to leverage its different configurations allows users to conduct effective load tests, potentially catching performance issues before they become problematic in production environments. The examples provided showcase different use cases where ‘locust’ can be tailored to meet diverse testing requirements.
