.. _developing-locust:

=================
Developing Locust
=================

You want to contribute to Locust? Great! Here is a list of `open bugs/feature requests <https://github.com/locustio/locust/>`_.

Install Locust for development
==============================

Fork Locust on `GitHub <https://github.com/locustio/locust/>`_ and then run

.. code-block:: console

    $ 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 <https://github.com/locustio/locust/compare>`_. 

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 <https://tox.readthedocs.io/en/stable/>`_ to automate tests across multiple Python versions:

.. code-block:: console

    $ pip3 install tox
    $ tox
    py37 create: /home/myuser/git/locust/.tox/py37
    py37 installdeps: codecov, 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 <https://docs.pytest.org/>`_ directly:

.. code-block:: console

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

Format code
===========

Locust follows the `black <https://github.com/psf/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:

.. code-block:: console

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

You can validate the whole project using tox:

.. code-block:: console

    $ 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 <https://flake8.pycqa.org/en/latest/flake8>`_:

.. code-block:: console

    $ 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/ <https://github.com/locustio/locust/tree/master/docs/>`_ directory. To build the documentation you first need to install the required Python packages:

.. code-block:: console

    $ pip3 install -r docs/requirements.txt

Then you can build the documentation locally using:

.. code-block:: console

    $ 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 <https://sass-lang.com/>`_. 
In order to make changes to the CSS rules, you need to have SASS `installed <https://sass-lang.com/install>`_ 
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:

.. code-block:: console

    $ make sass_build


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

.. code-block:: console

    $ make sass_watch

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