Quick Installation Guide

This guide helps you get up and running with the appian-locust library quickly.

We strongly recommend using pipenv and pyenv to automatically manage Python versions and environments. This ensures a clean and reproducible setup for running and developing tests with Locust.

Note

💡 If you don’t want to manage environments manually, jump to the Automatic Setup section below.

Manual Setup

1. Install appian-locust using pip, for more comprehensive projects we recommend using pipenv.

pip install appian-locust

If using pipenv, simply start from the following Pipfile:

[packages]
appian-locust = {version = "*"}

[requires]
python_version = "3.13"

Build from source

1. Clone the repository:

git clone -o prod git@gitlab.com:appian-oss/appian-locust.git

2a. Install the library globally:

pip install -e appian-locust

2b. Or within a virtual environment:

pipenv install -e appian-locust

Note: It’s highly recommended that you use a virtual environment when installing python artifacts. You can follow the instructions here to install virtualenv and pip.

If you have issues installing, make sure you have the proper prerequisites installed for Locust and its dependencies. If you’re having trouble on Windows, check here

Automatic Setup

To simplify the setup process and avoid installing Python manually, use the provided setup.sh script. It will:

• Install pyenv and pipenv if they are missing.

• Install the correct Python version from the Pipfile.

• Create a virtual environment.

• Install all dependencies.

1. Clone the repository:

git clone -o prod git@gitlab.com:appian-oss/appian-locust.git

2. Navigate to appian-locust directory and make the script setup.sh executable:

cd appian-locust/
chmod +x setup.sh

3. Run the setup:

./setup.sh

4. After setup, activate the virtual environment:

pipenv shell

Test environment setup

Download the sample test example_locustfile.py from the Appian Locust repo and run it.

locust -f example_locustfile.py

If everything is set up correctly, you should see a link to the Locust web interface, which you can use to start test runs and view results.

• For more information about how to build the workflow for your locust test, see the How to Write a Locust Test section.

• For more information on running locust tests, see the How to Run Locust section.

appian-locust should now be ready to run your Locust performance tests!

Troubleshooting

• Do not have permissions to clone appian-locust

  • Ensure you have added you ssh key to your profile. See here for how to do this.

• “locust is not available”

  • Verify that you ran pip install -e appian-locust

• “Failed to establish a new connection: [Errno 8] nodename nor servname provided, or not known”

  • check that host_address is specified correctly in your locust test file.

• “Login unsuccessful, no multipart cookie found…make sure credentials are correct”

  • check that auth specifies a valid username and password combination for the site you’re testing on in your locust test file.

• “General request and response debugging”

  • Add self.client.record_mode = True to your HttpUser subclass. Files will be placed in /record_responses where the runner is executed.

  • Use run_single_user method of locust to run in debugger mode.