Hooks
A hook is a small piece of code, attached to one block of the route, that runs only while a test suite runs. It lets you:
- skip a block and give it a made-up result, for example skip a database call and pretend it returned a user;
- change what a block receives, to steer the route down a certain path;
- change what a block returns, to try an unusual case with real data;
- check values in the middle of the route with
t.expect; - make a block fail, to test your error handler.
Hooks never affect the live route. They exist only inside the suite they belong to.
In a test's trace, a block a hook skipped or changed carries a Mocked badge, so you can tell made-up values from real ones.
Add a hook
- Open the suite and choose the Hooks tab.
- On the left, pick a block. Only blocks that can have hooks are listed.
- Choose Before (runs just before the block) or After (runs just after it).
- Choose Script to write JavaScript, or JSON to type a made-up result. Off removes the hook.
- Press Save.
Blocks with a hook show a dot in the list. Switching between Off, Script and JSON keeps what you typed until you leave the page; only the choice selected when you press Save is stored.
Before
A Before hook runs just before the block. input is the value about to go into the block.
| What your code does | What happens |
|---|---|
| Returns nothing | The block runs as normal |
| Returns a value | The block runs with that value as its input |
Calls t.skip(output) | The block does not run; output is passed on as if the block had returned it |
Throws an error, or calls t.fail("message") | The block fails, and the route's error handler runs |
// change the input
return { ...input, email: input.email.toLowerCase() };// skip the database call and pretend it found this user
t.skip({ id: 7, name: "Test user" });The JSON shortcut
Choosing JSON for a Before hook is the same as calling t.skip with that JSON and no path: the block is skipped and the JSON is passed on as its result. It is the quickest way to fake a block:
{ "id": 7, "name": "Test user" }A JSON hook can't pick a path. On a block with two paths it always takes the first one, Success. To make Row Exists answer "not found", or a transaction fail, use a script (see below).
Skipping a block that has two paths
Some blocks send their result down one of two paths, such as Row Exists (found / not found) or Database Transaction (success / failure). Pick the path as the second argument of t.skip:
// pretend the row exists
t.skip({ id: 7 }, "success");
// pretend it does not
t.skip(null, "failure");Without a path, the first one ("success") is used. These are the path names to use:
| Block | Paths for t.skip (the first is the default) |
|---|---|
| Row Exists | success (a record was found), failure (none was) |
| Send Message | success, failure |
| Database Transaction | success, failure |
| Rollback Transaction | none: skipping it ends the flow there |
| Every other block that can be skipped | one path, source. Leave the path out |
The names are the block's output handles, the same ones the AI assistant gets from get_block_schemas.
A path name the block doesn't have is an error. If the name is written out as text, as in t.skip(null, "sucess"), Save refuses it and lists the names the block has. A name held in a variable can't be checked when you save, so the test fails when it runs, with "A db_exists block has no branch …".
After
An After hook runs just after the block. It gets input (what the block ran with) and output (what it returned).
| What your code does | What happens |
|---|---|
| Returns nothing | The output is passed on unchanged |
| Returns a value | That value is passed on instead |
Throws an error, or calls t.fail("message") | The block fails, and the route's error handler runs |
// check the real result, then force an edge case
t.expect(output).toHaveLength(2);
return [];A JSON After hook replaces the output with that JSON.
If a Before hook skipped the block, its After hook does not run.
What t gives you
| Name | What it does |
|---|---|
t.skip(output, path?) | Before only: skip the block and pass output on (down path, if the block has two) |
t.fail(message) | Make the block fail with this message |
t.expect(value) | Check a value; each check is a line in the results (all checks) |
t.call | How many times this block has run so far in this suite: 1, 2, 3… Useful in loops |
t.vars | The route's variables, to read or change |
t.block | This block's id, type and name |
t.setup | What the suite's setup block returned |
t.runId | A value unique to this suite run. The same in every case of a workflow suite; add t.case.index when each case needs its own (details) |
t.case | Workflow suites: the case being run (index, name, input) |
t.zod | The zod library, to check the shape of a value |
t.expect lines from hooks appear in the results first, labelled with the block, for example:
✗ db_getall "Load users": expected 1 to be 2Values from earlier blocks
input is only the value from the block just before. To read what an earlier block produced, use t.vars:
t.vars.outputs.<name>: the result of any block that has Save output to variable turned on, under that name.t.vars.<key>: anything stored with a Set Var block.
Which blocks can have hooks
| Blocks | Allowed |
|---|---|
| Entrypoint, Response, Error Handler, sticky notes | No hooks: they are the frame of the route, not steps in it |
| If, Switch, For Loop, Foreach Loop, Orchestrator, Retry | Before script only, to change the input. They run other blocks, so they cannot be skipped |
| Every other block, including custom blocks | Before and After, Script or JSON |
A custom block placed on the route is hooked as a whole: you can skip or change the whole custom block, but not the blocks inside it.
When a hook points at the wrong place
Hooks are checked when you save the suite:
| Mistake | What happens |
|---|---|
| A block that is not on this suite's route or workflow (for example one deleted from the canvas, or from another route) | Save is refused: "Block … is not on this suite's route" (or "workflow") |
| A block that can't have hooks, such as Response | Save is refused: "A response block cannot have hooks" |
| A skip or an After hook on If, Switch, a loop, Orchestrator or Retry | Save is refused: "A if block only allows an onBefore script that changes its input" |
| Two hooks for one block | Save is refused: "A block can have only one hook entry" |
| A JSON hook that isn't valid JSON | Save is refused: "Invalid JSON" |
t.skip with a path name the block doesn't have, written as text | Save is refused: "A db_exists block has no branch "sucess"; t.skip can use: success, failure" |
t.skip with a path name held in a variable, or a script that throws | The suite saves. The block fails when it runs, like any error in a hook |
Examples
Test the "not found" path without a database
On the Row Exists block, Before, Script:
t.skip(null, "failure");Then check the status in Assertions: Status code equals 404.
A different result on each pass of a loop
On a Get Single Record block inside a loop, Before, Script:
// first pass: nothing found; after that: a row
t.skip(t.call === 1 ? null : { id: t.call });Check what a block was given
On any block, Before, Script:
t.expect(input.userId, "user id sent to payments").toBe(42);Hooks follow the canvas
A hook belongs to one block. If you delete that block from the canvas, its hooks are deleted too.
