# Add a Locust Load Test to CI

Yes. An agent reuses the repository's Locust file, runs it headless against the staging deployment from the PR workflow, fails on set thresholds and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-load-test-to-ci/locust/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads what already generates load. In a Kubernetes app laid out like GoogleCloudPlatform/microservices-demo, `src/loadgenerator/locustfile.py` defines a `WebsiteUser` of type `FastHttpUser` with `wait_time = between(1, 10)` and a `UserBehavior` task set that weights `browseProduct` at 10, `viewCart` at 3, `setCurrency` and `addToCart` at 2, and `index` and `checkout` at 1, with `checkout` posting a Faker-generated address and card to `/cart/checkout`. `src/loadgenerator/Dockerfile` runs `locust --host=http://${FRONTEND_ADDR} --headless -u ${USERS:-10} -r ${RATE:-1}` forever, and `kubernetes-manifests/loadgenerator.yaml` deploys it with `USERS` of 10 and `RATE` of 1 next to the app. `.github/workflows/deploy-pr.yaml` already leans on it: after `skaffold run` and the `kubectl wait` loop, its `Smoke Test` step deletes the load generator pod, polls `kubectl logs -l app=loadgenerator | grep Aggregated` until the request count reaches 50 and fails if the error count is not zero, then comments the frontend's `EXTERNAL_IP` on the pull request. That is a liveness check, not a load test: no run time, no latency, and a target that shares the cluster with the generator.

The load test runs from the runner against the address the workflow already found. The agent adds a `Load Test` step after `Query EXTERNAL_IP for staging`, which installs the pinned requirements from `src/loadgenerator/requirements.txt` with `pip`, since `requirements.in` pins `locust==2.43.0` and `faker==40.1.0` and the file is compiled by `uv pip compile`, and runs `locust -f src/loadgenerator/locustfile.py --headless --host http://$EXTERNAL_IP` with `-u`, `-r`, `--run-time`, `--csv` and `--html` set from workflow variables, so the user count and duration live in one place and the CSV and HTML reports are uploaded with `actions/upload-artifact`. The in-cluster generator keeps running as it does today; the step does not touch the manifest.

Failing on numbers is done in the Locust file, where Locust documents it. The agent adds an `@events.quitting.add_listener` function that reads `environment.stats.total.fail_ratio` and `environment.stats.total.get_response_time_percentile(0.95)` and sets `environment.process_exit_code` to 1 when either passes a threshold read from `LOAD_MAX_FAIL_RATIO` and `LOAD_MAX_P95_MS`. Both are unset in the Kubernetes manifest, and the listener does nothing when they are, so the generator that runs forever in the cluster is unchanged, while the CI step sets both from workflow variables the team chooses. The step also writes the aggregated line to `GITHUB_STEP_SUMMARY`, so the numbers appear on the workflow run without opening an artifact.

The agent proves the file before touching the workflow. It installs the requirements in the sandbox, starts the Go `frontend` from `src/frontend` with stub addresses, or, where that is too much, a small HTTP server that answers the paths the task set uses, and runs the same `locust` command against it with a short `--run-time`, once with thresholds that pass and once with a fail ratio of zero to show the exit code become 1. The workflow change is checked with `actionlint`, and because `deploy-pr.yaml` runs on `workflow_run` after the pull request workflow, the agent says in the pull request that the step will first run on the merge rather than on the branch.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a Locust load test to the pull request deployment workflow. Read src/loadgenerator/locustfile.py, src/loadgenerator/Dockerfile, src/loadgenerator/requirements.in, src/loadgenerator/requirements.txt, kubernetes-manifests/loadgenerator.yaml and .github/workflows/deploy-pr.yaml first. Add a quitting listener to the locustfile that sets the process exit code when the fail ratio or the p95 response time passes thresholds read from LOAD_MAX_FAIL_RATIO and LOAD_MAX_P95_MS, doing nothing when they are unset. Add a Load Test step to deploy-pr.yaml after the EXTERNAL_IP query that installs the pinned requirements, runs locust headless against the staging address with users, rate, run time and the thresholds taken from workflow variables, writes the aggregated line to the step summary and uploads the CSV and HTML reports. Prove the listener locally against a small server with a passing and a failing run, lint the workflow with actionlint, quote the results and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `src/loadgenerator/locustfile.py` and `.github/workflows/deploy-pr.yaml`, and adds a section to `.github/workflows/README.md`, which describes each workflow and today lists the smoke test under the deploy tests. The load generator's Dockerfile and manifest are unchanged, so the image Skaffold builds behaves as before.

The description holds the two local Locust runs, one ending with exit code 0 and one with 1, each with its aggregated stats line, the `actionlint` output, and the names of the workflow variables a maintainer has to set, with no values filled in because the thresholds are the team's call. The repository's `kustomize-build-ci` and pull request workflows run on the branch as they do for any change.

Before merging, a reviewer sets the user count, run time and the two thresholds as repository variables, and decides whether the load test should run on every pull request or only on those that touch `src/`, which the workflow's `paths-ignore` list already partly decides. The agent leaves the trigger as it is and names the choice.

## Run it on every nightly

In the Project that holds the repository, create an automation with this page's prompt and a `schedule` trigger with `every` set to `1d` in the team's `timezone`. Each night the run checks the workflow and the Locust file as they are that day: a task set that gained a path, a changed user count, or a threshold variable that was removed gets a pull request, and a run that finds nothing to change ends with an answer saying so and no branch.

With `notify_each_run` left off, the nightly results arrive as one Slack message a day that each run updates, and a failed run still arrives on its own. The automation runs as the member who created it, so the pull requests carry that person's name.

## Why run it on Rush?

A load test is only believable once the exit code has been seen to flip, which needs the requirements installed, a server to hit and two headless runs with the aggregated stats kept, work that rarely happens on a laptop for a workflow change. The sandbox installs Locust, runs both and keeps the output, so the pull request opens with both runs quoted.

The run's record keeps each `locust` invocation and its stats line, so a reviewer reads what the listener saw rather than a sentence that thresholds work. A company with several services that already ship a Locust file starts one run per repository, and each pull request fits that service's own task set and workflow.

## Frequently asked questions

### Why run Locust from the runner instead of reading the in-cluster generator's logs?

The in-cluster generator runs forever with ten users and a one-second spawn rate and reports only through `kubectl logs`, which the current smoke test scrapes with `grep` and `awk`. Running from the runner gives a bounded `--run-time`, a CSV and HTML report, and an exit code the job can fail on.

### Does the listener change the generator that runs in the cluster?

No. `kubernetes-manifests/loadgenerator.yaml` sets `FRONTEND_ADDR`, `USERS` and `RATE` only, so the two threshold variables are unset there and the listener returns without touching the exit code. The container's entrypoint and image are unchanged.

### Where do the thresholds come from?

From repository or environment variables the team sets, read by the workflow step and passed as `LOAD_MAX_FAIL_RATIO` and `LOAD_MAX_P95_MS`. The agent fills in none, because a p95 for this app depends on the cluster size and the user count, and the first few runs on the real staging namespace are what tell the team where to set them.

### Will a load test on a shared staging cluster disturb other pull requests?

Each pull request deploys into its own `pr<N>` namespace and the test targets that namespace's `frontend-external` address, so the load lands on that pull request's pods. The node pool is shared, which is one reason the run time and user count are variables rather than large constants.

## More jobs like this: Write the missing tests

- [Add a Migration Check to CI for a TypeORM Project](https://getrush.ai/run/add-migration-check-to-ci/typeorm/)
- [Write Migration Rollback Tests for Alembic](https://getrush.ai/run/add-migration-rollback-tests/alembic/)
- [Add Mutation Testing to a .NET Solution](https://getrush.ai/run/add-mutation-testing/dotnet/)
- [Add Mutation Testing With Stryker to a Jest Suite](https://getrush.ai/run/add-mutation-testing/jest/)
- [Add Mutation Testing to a Maven Project](https://getrush.ai/run/add-mutation-testing/maven/)
- [Add Mutation Testing to a pytest Suite](https://getrush.ai/run/add-mutation-testing/pytest/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
