Metadata-Version: 2.1
Name: appian-locust
Version: 1.28.0
Summary: Tools and functions to make testing Appian with Locust easier
Home-page: https://gitlab.com/appian-oss/appian-locust
Author: Appian Performance & Reliability Engineering Squad
License: Apache 2.0
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Description-Content-Type: text/x-rst
License-File: LICENSE

.. what_is_appian_locust-inclusion-begin-do-not-remove

#######################################
What is Appian Locust?
#######################################

Appian Locust is a wrapper library around `Locust <https://locust.io>`__ 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

.. what_is_appian_locust-inclusion-end-do-not-remove


For full documentation, visit the `docs page <https://appian-locust.readthedocs.io/en/latest/>`__

.. disclaimer-inclusion-begin-do-not-remove

**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 <contributing.html>`__ section and feel free to reach out.

.. disclaimer-inclusion-end-do-not-remove

.. quick_start-inclusion-begin-do-not-remove

********************
Quick Start Guide
********************

This is a quick guide to getting up and running with the appian-locust library. You will need Python 3.7+ installed on your machine before proceeding.

Setup
------------

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

.. code-block:: bash

      pip install appian-locust

2. Configure your test to point at the Appian instance you will be using.
You can use example file provided in this repository `example_config.json <https://gitlab.com/appian-oss/appian-locust/-/blob/master/examples/example_config.json>`_:

- Set ``host_address`` to the address of your Appian instance.
- In ``auth``, specify the username and password of the user account to use.

.. code-block:: json

    {
        "host_address": "site-name.appiancloud.com",
        "auth": [
            "user.name",
            "password"
        ]
    }

3. Run the sample test `example_locustfile.py <https://gitlab.com/appian-oss/appian-locust/-/blob/master/examples/example_locustfile.py>`_.

.. code-block:: bash

    locust -f example_locustfile.py -u 1 -t 60 --headless

If everything is set up correctly, you should start to see output from the load test reporting results. This should run for 60 seconds and end with a summary report of the results.

* For more examples of different site interactions, see the ``example_*.py`` files included in this repository.
* For more in-depth information about the test library, see the rest of this documentation.

Troubleshooting
----------------
* **"Failed to establish a new connection: [Errno 8] nodename nor servname provided, or not known"**

  * check that ``host_address`` is specified correctly in `example_config.json <https://gitlab.com/appian-oss/appian-locust/-/blob/master/examples/example_config.json>`_.

* **"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 `example_config.json <https://gitlab.com/appian-oss/appian-locust/-/blob/master/examples/example_config.json>`_.

.. quick_start-inclusion-end-do-not-remove

.. contrib-inclusion-begin-do-not-remove

********************
Contributing
********************

* Read and agree to our `Contributing Policy <https://gitlab.com/appian-oss/appian-locust/-/blob/master/CONTRIBUTING>`__
* Fork the `appian-locust <https://gitlab.com/appian-oss/appian-locust>`__ repository
* Make any desired changes to python files, etc.
* Commit changes and push to your fork
* Make a merge request to the upstream fork

To test changes
-----------------
In any test-implementation repo where you use appian-locust, change the following (assuming you're using a ``Pipfile``)

.. code-block:: python

    appian-locust = {path="../appian-locust", editable=true}

**NOTE** The path above assumes appian-locust is checked out locally, hence we can use a relative directory path.

And run ``pipenv install --skip-lock`` to allow you to use a local version of appian-locust
without recreating the lock file. However, remember to use a lock file in your test-implementation repo.

Now you can test your changes as you normally would.

.. contrib-inclusion-end-do-not-remove


