Load tests (Locust)

Performance and load testing using Locust.

Usage

splent locust
splent locust <feature>
splent locust:stop

splent locust (CLI 1.13.0 and later) runs Locust inside the product’s web container, which already has splent_framework and every installed feature importable, so no extra image is built. With no argument, the framework bootstrap discovers every feature’s locustfile; naming a feature narrows discovery to that feature through SPLENT_LOCUSTFILES. The web interface is served on port 8089, which products scaffolded by 1.13.0 publish; for an older product add "8089:8089" to the web service’s ports and recreate the container.

Two prerequisites, both reported with actionable errors when missing. The product must be up (splent product:up), and locust must be installed in the web image. New products declare it in the dev extras; for an older product add "locust" to [project.optional-dependencies].dev and rebuild, or install it once with docker exec <product>_web pip install locust.

Load tests live in tests/load/locustfile.py inside each feature and are not part of the default pytest run.

Description

Locust tests simulate concurrent users hitting the application to measure performance under load. Each feature can define its own user behavior.

from locust import HttpUser, TaskSet, task

class AuthBehavior(TaskSet):
    @task
    def login(self):
        self.client.post("/login", data={"email": "user@test.com", "password": "1234"})

class AuthUser(HttpUser):
    tasks = [AuthBehavior]
    min_wait = 5000
    max_wait = 9000

Locustfile discovery

To run every feature’s load tests in a single Locust session, the framework ships a bootstrap module, splent_framework.bootstraps.locustfile_bootstrap. Pointing Locust at that module’s file with -f makes it discover the locustfiles the product ships, import them, and re-export every HttpUser subclass so Locust offers them all.

Discovery covers the layouts SPLENT products actually use.

app/features/<feature>/tests/locustfile.py. A product that keeps its features inside the application package.
features/<namespace>/<feature>/. A product composed from installed feature packages, including tests/load/locustfile.py. These entries are symlinks into the workspace or the feature cache, and discovery follows them.

Paths are resolved relative to WORKING_DIR, deduplicated, and sorted. Each locustfile is imported under a module name derived from its feature, so user classes from two features cannot shadow each other.

A locustfile that fails to import is skipped with a logged exception instead of aborting the run. If no HttpUser class is found at all, the error message lists where the bootstrap searched and how to override it.

Overriding discovery

Set SPLENT_LOCUSTFILES to a comma-separated list of glob patterns to replace the default discovery entirely. Patterns are resolved relative to WORKING_DIR unless absolute. Use it when a product keeps its load tests somewhere else.

SPLENT_LOCUSTFILES="load_tests/*.py,extra/locustfile.py" locust -f <path-to>/locustfile_bootstrap.py

Requirements

The product must be running (splent product:up).
Locust must be installed in the product web image (dev extras in 1.13.0+ products).
Once running, the Locust web UI is available at http://localhost:8089. Stop it with splent locust:stop.