Open Source Load Tests in Just Two Lines of Python

Locust 2.40 introduces the ability to run pytest modules as load tests, providing more compact/simpler syntax and seamless reuse of functional tests as load tests.

Locust has previously only supported an ambitious and opinionated approach to structuring load tests. It is based around concepts such as User classes and TaskSets, that are powerful but don’t add any value for simpler tests. And even for more complex tests, they often often end up being more confusing than helpful. The truth is, you don’t really need them, because a single Locust test task already offers all the flexibility of Python.

That’s why we’re introducing a simpler way to express Locust tests:

def test_stuff(session): 
    session.get("https://locust.cloud/")

There. That’s all you need to write the simplest possible test in Locust now, and if you’ve ever used pytest before you should feel right at home. Save it as, for example, test_stuff.py and run it with locust -f test_stuff.py. If you haven’t already installed Locust, check out the documentation.

But testing is about more than just HTTP status codes

If you want to be a little more explicit and get better editor support, you should add type hints for the session fixture. And you can/should still validate responses, just like with Locust’s regular HttpUser. If you want to interrupt the flow on failure, use response.raise_for_status(). Here’s a more complete example:

from locust.clients import HttpSession

def test_stuff(session: HttpSession):
    with session.get("https://locust.cloud/", catch_response=True) as resp:
        if not resp.text or not "Load" in resp.text:
            resp.failure("important text was missing in response")
    resp.raise_for_status()
    session.get("/other_thing") # will not be run if previous request failed

What about pytest?

The locust file is still a valid pytest file and fits well as part of your functional test suite! Lets say we were missing that important piece of text, running pytest would give you this output:

❯ pytest test_stuff.py
=========================== test session starts ============================
platform darwin -- Python 3.12.2, pytest-8.3.4, pluggy-1.5.0
rootdir: /Users/lars/git/locust
configfile: pyproject.toml
plugins: console-scripts-1.4.1, locust-2.40.4, mock-3.14.0, anyio-4.6.2.post1
collected 1 item
         
test_stuff.py F                                                     [100%]

================================= FAILURES =================================
________________________________ test_stuff ________________________________

session = <locust.clients.HttpSession object at 0x103936f60>

    def test_stuff(session: HttpSession):
        with session.get("https://locust.cloud/", catch_response=True) as resp:
            if not resp.text or not "Load" in resp.text:
                resp.failure("important text was missing in response")
>       resp.raise_for_status()
E       locust.exception.CatchResponseError: important text was missing in response

test_stuff.py:8: CatchResponseError
========================= short test summary info ==========================
FAILED test_stuff.py::test_stuff - locust.exception.CatchResponseError: important text was missing in resp...
============================ 1 failed in 0.41s =============================

For more info on how to simulate wait times, set the target host name, use helper functions, define multiple test cases, etc, check the documentation.

Technical details:

• The session fixture is provided by Locust as a pytest plugin. Currently we support python-requests and geventhttpclient (fixture name fastsession), but we’ll expand this as we go. Under the hood the your test code still has a User instance (accessible as session.user)
• This feature is still experimental and may change over time. It is completely optional and the old way of defining tests continues to be supported. Combining this with advanced pytest features (or other fixtures) may or may not work. Do let us know if you encounter an issue!

Happy load testing!

If you need additional help, or want to use our hosted cloud offering to run your tests, don't hesitate to reach out!