appian-locust 2.27.8

Tools and functions to make testing Appian with Locust easier

Appian Locust is a wrapper library around Locust for load testing Appian. This library is intended to be used as an alternative to tools such as Jmeter and Load Runner.

Appian Locust capabilities

• Logging in and logging out

• Form interactions (filling/submitting)

• Finding and interacting with basic components on a SAIL interface

• Navigating to records/reports/sites

For full documentation, visit the docs page.

Disclaimer: This library is continuously evolving. Currently the main focus is supporting essential use-cases. We are happy to accept contributions to further extend functionality, address bug fixes and improve usability. Please see the Contributing section and feel free to reach out.

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 [e-mail]: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 [e-mail]: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.

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

Troubleshooting

Installation Issues

• Permissions issue when cloning appian-locust

  • Ensure you have added your SSH key to your GitLab profile. See here for instructions.

  • Alternatively, download the ZIP bundle.

• “locust is not available” or “command not found”

  • Verify you ran pip install appian-locust

  • If using a virtual environment, ensure it’s activated: pipenv shell

  • Check your PATH includes the Python or Pyenv directory

  echo $PATH | grep -e "python" -e "pyenv"

• Python version compatibility errors

  • Appian Locust requires Python 3.13+. Check your version: python --version

  • Consider using pyenv to manage multiple Python versions

Connection & Authentication Issues

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

  • Verify host_address in your config.json is correct (without https://)

  • If behind a corporate firewall, check any network security tools like ZScaler or any outbound proxy settings.

• “Login unsuccessful, no multipart cookie found”

  • Verify username and password in auth are correct for your Appian site

  • Verify the user has appropriate permissions to access the site, try in a browser

• SSL/Certificate errors

  • For self-signed certificates you may need to disable SSL verification, but make sure you actually trust the host you are testing against.

  class UserActor(HttpUser):
      def on_start(self):
          self.client.verify = False

Runtime Issues

• Tests run but no interactions complete

  • Verify that your Appian site is accessible in a browser

  • Ensure your test users have access to the interfaces you’re testing

Need More Help?

• For detailed debugging techniques, request recording, and advanced troubleshooting, see the Debugging Guide