Skip to content
MaxoPerf MaxoPerf docs

Run tests from CI

Most teams want CI to start a performance test on every release candidate and fail the build when the result is worse than a baseline. The Platform API lets you do this from any CI system.

See the full API reference for request shapes and authentication.

What CI usually does

Section titled “What CI usually does”

A typical pipeline step:

  1. Starts a Maxoperf run for a specific test.
  2. Waits for the run to finish.
  3. Reads the run summary and passes or fails the build.

Each of the three steps is one HTTP call.

Authenticate

Section titled “Authenticate”

CI calls authenticate with a bearer token issued for an account-scoped principal. Treat the token like any other secret. Store it in your CI provider’s secret manager and never commit it to a repository.

Start a run

Section titled “Start a run”
  1. Read the test ID from the test detail page in the console.
  2. Call POST /v1/runs with the test ID and optional overrides for the load profile.
  3. Save the returned run_id. You need it in the next two steps.

A minimal example:

Terminal window
curl -X POST \
  -H "Authorization: Bearer $MAXOPERF_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.maxoperf.com/v1/runs \
  -d '{ "test_id": "tst-1234abcd56" }'

Wait for the run

Section titled “Wait for the run”
  1. Poll GET /v1/runs/{run_id} every few seconds.
  2. Watch the status field. Stop polling when it reaches finished, failed, or cancelled.
  3. For long runs, use the streaming endpoint or schedule a webhook instead of polling.

Decide pass or fail

Section titled “Decide pass or fail”

The run summary includes latency, throughput, and error counts. A simple gate:

  • If status !== "finished", fail the build.
  • If error_rate > threshold, fail the build.
  • If latency_p95_ms > baseline_p95_ms * 1.1, fail the build.

The exact field names are in the API reference.

Pattern recommendations

Section titled “Pattern recommendations”
  • Keep the test definition in the console, not in CI. If many CI pipelines edit a test, its history becomes hard to read.
  • Use one token per pipeline, so you can revoke each one on its own.
  • Tag the run with the commit SHA, so you can search the run history from the console.

Where to go next

Section titled “Where to go next”