Run tests from CI

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

See the full API reference for request shapes and authentication.

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 decides whether to pass or fail the build.

You can do all three with three HTTP calls.

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, never commit it to a repository.

Token scope and rotation

Issue the narrowest token that still lets CI start the runs it needs. Rotate tokens regularly and revoke any token that may have been exposed.

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. Capture the returned run_id — you will use it in the next two steps.

A minimal example:

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

1. Poll GET /v1/runs/{run_id} every few seconds.
2. Watch the status field. When it reaches finished, failed, or cancelled, stop polling.
3. For long runs, use the streaming endpoint or schedule a webhook instead of polling.

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

• Keep the test definition in the console, not in CI. Editing a test from many CI pipelines makes the history hard to read.
• Use one token per pipeline so you can revoke individually if needed.
• Tag the run with the commit SHA so the run history is searchable from the console.

Where to go next

• API reference — full HTTP surface for automation.
• Schedule recurring tests — when a recurring schedule fits better than a CI trigger.
• Build reporting dashboards — make CI-triggered runs visible to humans too.