Repo layout
Tests live undertests/<slug>/
:
config.json
fields managed by the CLI:
- Slug is the unique test name.
host
is protocol+hostname+port; the CLI resolves/creates the Host and sendshost_id
.- New tests require
region
present on create; for updates,region
defaults to remote if omitted. - Only
test_type = "load"
is supported for pull/push currently.
Required secret
Add to your repo or org secrets:API_KEY
: your LoadForge API key (used as env varAPI_KEY
).
Install method in CI
Use npx (no install step needed; both aliases work):Workflow: sync configs on push to main
Sync local configs and locustfiles to LoadForge when PRs are merged. Creates new tests and updates existing ones by slug; optionally prunes remote tests not present locally.- Intersection (same slug) → PATCH
- Local-only → create (with
--allow-create
) - Remote-only → delete/prune (with
--allow-delete
) - Extended fields are attempted; if rejected, the CLI falls back to base fields.
Workflow: drift check (no changes)
Detect drift between main and LoadForge without making changes.Workflow: run tests on demand (matrix by slug)
Start runs and wait for completion. Thewait
command exits with:
- 0: run_status=3 and run_passed=true
- 2: run_status=3 and run_passed=false (explanation printed)
- 1: run_status>=4 (failure reason printed)
Workflow: nightly scheduled runs
Hosts management via config.host
- Specify a host string in
config.json
, e.g.,"host": "https://example.com:443"
. - On push, the CLI resolves to an existing Host (protocol/url/port match) or creates one if missing, and sends
host_id
automatically. - No need to store host IDs in git.
Pulling from LoadForge
To bootstrap or refresh local files:tests/<slug>/locustfile.py
and tests/<slug>/config.json
for all load tests. It writes host
strings by resolving host_id
via the Hosts API.
Creating new tests (local scaffold)
Create a new test folder (interactive or via flags). Then push with--allow-create
to create it remotely.
References
- Intro/Auth: /api-reference/introduction
- Hosts (list): /api-reference/endpoint/hosts-list
- Tests (list): /api-reference/endpoint/tests-list
- Tests (update): /api-reference/endpoint/tests-update
- Run (start): /api-reference/endpoint/run-start
- Result (get): /api-reference/endpoint/result-get