Developing Locust

You want to contribute to Locust? Great! Here is a list of open bugs/feature requests.

Install Locust for development

Fork Locust on GitHub and then run

$ git clone git://github.com/<YourName>/locust.git # clone the repo
$ pip3 install -e locust/                          # install in editable mode

Now the locust command will run your code with no need for reinstalling after making changes.

To contribute your changes, push to a branch in your repo and then open a PR on github.

Before you open a pull request, make sure all the checks work. And if you are adding a feature, make sure it is documented (in docs/*.rst).

Testing your changes

We use tox to automate tests across multiple Python versions:

$ pip3 install tox
$ tox
py37 create: /home/myuser/git/locust/.tox/py37
py37 installdeps: mock, retry, pyquery, cryptography
...
Successfully installed ConfigArgParse-1.5.3 Flask-BasicAuth-0.2.0 Flask-Cors-3.0.10 Jinja2-3.1.2 MarkupSafe-2.1.1 Six-1.16.0 Werkzeug-2.2.2 brotli-1.0.9 click-8.1.3 flask-2.2.2 gevent-22.10.1 geventhttpclient-2.0.8 greenlet-1.1.3.post0 itsdangerous-2.1.2 locust-2.12.2 msgpack-1.0.4 psutil-5.9.2 pyzmq-24.0.1 roundrobin-0.0.4 typing-extensions-4.4.0 zope.event-4.5.0 zope.interface-5.5.0
py37 run-test: commands[1] | python3 -m coverage run -m unittest discover
...

To only run a specific suite or specific test you can call pytest directly:

$ pytest locust/test/test_main.py::DistributedIntegrationTests::test_distributed_tags

Format code

Locust follows the black formatting standard, and the build will fail if code does not adhere to it. If you run vscode it will automatically run every time you save a file, but if your editor doesn’t support it you can run it manually:

$ pip3 install black
$ python -m black <file_to_be_formatted>

You can validate the whole project using tox:

$ tox -e black
black installed: black==22.8.0,click==8.1.3,mypy-extensions==0.4.3,pathspec==0.10.1,platformdirs==2.5.2,tomli==2.0.1,typing_extensions==4.4.0
black run-test-pre: PYTHONHASHSEED='3136620079'
black run-test: commands[0] | black --check .
All done! ✨ 🍰 ✨
99 files would be left unchanged.

Linting

Our code is checked using flake8:

$ tox -e flake8
flake8 installed: flake8==5.0.4,mccabe==0.7.0,pycodestyle==2.9.1,pyflakes==2.5.0
flake8 run-test-pre: PYTHONHASHSEED='1517754253'
flake8 run-test: commands[0] | flake8 . --count --show-source --statistics

Build documentation

The documentation source is in the docs/ directory. To build the documentation you first need to install the required Python packages:

$ pip3 install -r docs/requirements.txt

Then you can build the documentation locally using:

$ make build_docs

Then the documentation should be build and available at docs/_build/index.html.

Making changes to Locust’s Web UI

The CSS styling for Locust’s user interface is written in SASS. In order to make changes to the CSS rules, you need to have SASS installed and available on your PATH.

Once you have SASS installed you can have the command line sass program compile the Locust .sass files by running the following in the locust project’s root path:

$ make sass_build

Or you can make sass watch for changes to the .sass files and automatically generate new CSS files by running:

$ make sass_watch

The CSS files that are generated by SASS should be checked into version control.

Making changes to Locust’s Modern Web UI

The modern Web UI is built using React and Typescript

Setup

Node

Install node using nvm to easily switch between node version

  • Copy and run the install line from nvm (starts with curl/wget …)

  • Verify nvm was installed correctly

$ nvm --version

  • Install the proper Node version according to engines in the locust/webui/package.json

$ nvm install {version}
$ nvm alias default {version}

Yarn

  • Install Yarn from their official website (avoid installing through Node if possible)

  • Verify yarn was installed correctly

$ yarn --version

  • Next in web, install all dependencies

$ cd locust/webui
$ yarn

Developing

To develop the frontend, run yarn dev. This will start the Vite dev server and allow for viewing and editing the frontend, without needing to a run a locust web server

To develop while running a locust instance, run yarn dev:watch. This will output the static files to the dist directory. Then simply a locust instance using the --modern-ui flag. Vite will automatically detect any changed files and re-build as needed. Simply refresh the page to view the changes

To compile the webui, run yarn build

The frontend can additionally be built using make:

$ make frontend_build

Linting

Run yarn lint to detect lint failures in the frontend project. Running yarn lint --fix will resolve any issues that are automatically resolvable. Your IDE can aditionally be configured with ESLint to resolve these issues on save.

Formatting

Run yarn format to fix any formatting issues in the frontend project. Once again your IDE can be configured to automatically format on save.

Typechecking

We use Typescript in the frontend project. Run yarn type-check to find any issues.