Test Suites
A test suite checks one route (or one workflow) for you. It sends the route a request you describe, then checks the answer against rules you write. You can run it any time, for example after changing the route, to make sure nothing broke.
Think of it as a saved "try it out" call that also knows what the right answer looks like.
What a suite can do
| You want to… | Use |
|---|---|
| Send the route a request (path values, query, headers, body) | The request |
| Check the status code, a header, a value in the body, or how long it took | Simple checks |
| Write your own checks in JavaScript | Custom JS checks |
| Stop a block from really running (for example, skip a database call) and give it a made-up result | Hooks |
| Change what a block receives or returns, to test an unusual case | Hooks |
| Add test data before the suite and remove it after | Setup and teardown |
| Point the route at a test database or use different settings | Overrides |
| Test a workflow with some input, once or once per case | Testing workflows |
What happens when you press Run
Every suite runs through the same steps, in this order:
- Setup (optional): a block you choose runs first, for example to add a test user.
- The request: the route runs with the request you described. Any hooks you added run inside it.
- Checks: your checks look at the answer.
- Teardown (optional): a block you choose runs last, for example to delete the test user. It runs even when checks fail.
Then the suite gets one result: passed, failed, error, or timeout. See Reading results.
Development and Production runs
When you run suites you pick an environment. The Run in Production toggle sits next to Run all (and next to Run suite). It is off by default, which means Development. Switching it on asks you to confirm first, so a production run is never one click away by accident.
| Run | What it tests | Credentials and values |
|---|---|---|
| Development | The route as it is saved on the canvas. You can test a change before anyone uses it. | Development |
| Production | The version you promoted, as production serves it now. | Still development |
What "Production" means here
A Production run tests the promoted version's blocks, but it always uses your development credentials and values. It never touches production data, so it is safe to run at any time. Use it to check that the version in production still passes after the working copy has moved on.
- A route or workflow that has not been promoted yet has no Production run: the toggle is disabled and says Not promoted yet.
- Each run in the history carries a Dev or Prod chip. Runs that a promote ran to check a version — its gate runs — also say Promote check.
- The AI agent's
run_test_suitetool takes the sameenvsetting. Withproductionit asks first, like any other production read, if your project is set to ask. - Promoting a version runs all its suites automatically. See The tests check.
Suites never touch live traffic
Each suite runs on its own, away from the requests your users are sending. Changes a suite makes for testing, such as a made-up block result or a different database, only apply to that suite.
Where to find it
Open a route, then choose the Tests tab next to Canvas. On the left is the list of suites for that route, in the middle is the editor for the selected suite, and on the right are the results.
Next: Create your first test suite.
