---
url: https://docs.fluxify.rest/testing/setup-and-teardown.md
description: >-
  Add test data before a test suite runs and clean it up afterwards, using
  custom blocks made only for testing.
---

# Setup and Teardown

Many routes need data to exist before you can test them: a user to log in, an order to cancel, a product to look up. **Setup** adds that data before the suite's request. **Teardown** removes it afterwards, so every run starts clean.

Setup and teardown are **custom blocks**, so they can do anything a custom block can: insert rows, call an API, generate fake data with a library, and so on.

## 1. Make a test-only custom block

1. Create a custom block (see [Custom Blocks](/blocks/custom-blocks)), for example `seed_users`.
2. In **Used for**, pick **Test setup & teardown**.
3. Finish creating it.

A test-only block:

* **is hidden from the block picker**, so nobody adds it to a live route by mistake;
* **can't be saved onto a route, workflow or normal custom block**, even through the API or the AI assistant;
* **never runs in live traffic**. It only runs as a suite's setup or teardown.

::: warning Picked once
**Used for** is chosen when the block is created and can't be changed later. To
turn a normal block into a test-only one, create a new block. See
[Where a custom block can be used](/blocks/custom-blocks#where-a-custom-block-can-be-used).
:::

## 2. Build what it does

Build the block's canvas like any other custom block. While it runs, it can read a value called `testsuite`:

| Name | What it is |
| --- | --- |
| `testsuite.phase` | `"setup"` when it runs before the request, `"teardown"` when it runs after. A workflow suite's [loader block](./workflows#where-the-value-comes-from) sees `"input"` |
| `testsuite.runId` | A value unique to this suite run. Put it in your test data so suites running at the same time never clash. It is the same in every case of a [workflow suite](./workflows#single-input-or-cases); add the case number for data that must differ per case (see [below](#unique-data-per-case)) |
| `testsuite.suite` | The suite's `id` and `name` |
| `testsuite.setup` | Teardown only: what the setup block returned |
| `testsuite.outcome` | Teardown only: how the suite ended: `"passed"`, `"failed"`, `"error"` or `"timeout"` |
| `testsuite.request` | Teardown only: what the suite sent (see [Clean up what the request created](#clean-up-what-the-request-created)) |
| `testsuite.response` | Teardown only: what came back, or `null` if nothing did |

The editor suggests these names only on the canvas of a test-only block.

**Whatever the block's last step returns is its result.** For setup, that result is handed to the rest of the suite (see [step 4](#_4-use-the-setup-result)).

### Example: seed a user

A `seed_users` block with **Entrypoint → JS Runner → Insert New Record** (into a `users` table), where the JS Runner makes the row:

```js
import { faker } from "@faker-js/faker";

return {
  email: `${testsuite.runId}@test.local`,
  name: faker.person.fullName(),
};
```

**Insert New Record** returns the new row, so the setup's result is the new user.

A `cleanup_users` block for teardown deletes it again, using what setup returned:

```js
// in a JS Runner before a Delete Record(s) block
return { id: testsuite.setup.id };
```

Packages such as `@faker-js/faker` must be added to the project first. See [Imports & Libraries](/scripting/imports).

### Clean up what the request created

A route often creates something the suite could not know about in advance, such as a new row with a database-made id. That id is in the response, and teardown can read it.

For a **route** suite:

| Name | What it holds |
| --- | --- |
| `testsuite.request` | What was sent: `method`, `path`, `headers`, `query`, `params`, `body` |
| `testsuite.response` | What came back: `status`, `headers`, `body`. It is `null` when the route failed to answer or ran out of time. Check `testsuite.outcome` to tell why |

A route that answers with an error status (such as `409`) did answer, so `testsuite.response` holds it. Only a route that crashed or timed out leaves it `null`.

```js
// teardown: delete the user the route created
const created = testsuite.response?.body;
if (!created?.id) return null; // nothing was created, nothing to clean
return { id: created.id };
```

For a **workflow** suite:

| Run | `testsuite.request` | `testsuite.response` |
| --- | --- | --- |
| Single input | `{ input }` | `{ successful, output, error }` |
| Cases | a list with one `{ name, input }` for each case | a list with one `{ name, successful, output, error }` for each case |

In **Cases** mode teardown still runs **once**, after all the cases, so loop over the list. Cases that never finished (the suite timed out first) are missing from the lists.

```js
// teardown for a workflow suite in Cases mode: remove every row a case created
return testsuite.response
  .filter((r) => r.successful && r.output?.id)
  .map((r) => ({ id: r.output.id }));
```

### Unique data per case

`testsuite.runId` (and `t.runId` in hooks and checks) is made once for each suite run. A route suite has one request, so it is unique per request. A workflow suite in **Cases** mode shares it across all its cases. When each case needs its own value, add the case number, which hooks and checks read as `t.case.index`:

```js
// hook or check
const email = `${t.runId}-${t.case.index}@test.local`;
```

## 3. Choose them in the suite

Open the suite, choose the **Setup & teardown** tab, and pick:

| Field | What it does |
| --- | --- |
| Setup | The test-only block that runs **before** the request, or None |
| Teardown | The test-only block that runs **after** the checks, or None |
| Time limit | How long each may take, in seconds (default 30, up to 600) |
| Run alone | Run this suite by itself, after the other suites (see [below](#run-alone)) |

Press **Save**. Only test-only blocks of the project are offered.

## 4. Use the setup result

Setup's result is available to the rest of the suite:

* in [hooks](./hooks) and [Custom JS checks](./checks#custom-js-checks) as `t.setup`;
* in the teardown block as `testsuite.setup`.

```js
// Custom JS check: the route returned the user setup created
t.expect(fluxify.response.body.id).toBe(t.setup.id);
```

## What happens when something goes wrong

| Situation | What happens |
| --- | --- |
| Setup fails or runs out of time | The request is **skipped** and the suite is marked **error** ("Setup failed: …"). Teardown **still runs**, so half-added data is cleaned up |
| The route runs out of time | The suite is marked **timeout**. Teardown **still runs**, with the setup result |
| Checks fail | The suite is marked **failed**. Teardown runs as normal |
| Teardown fails or runs out of time | The suite **keeps its result** (a passed suite stays passed), with a warning: "Passed, but teardown failed: …". You also get a notice when the run ends, because test data may have been left behind |

::: tip Write teardown so it can run twice
Teardown can run after a failed or half-finished setup. Delete by the values you created (for example by `testsuite.runId`), and don't fail if a row is already gone.
:::

## Run alone

When you press **Run all**, suites run at the same time to finish sooner. They share the same databases, so one suite's test data can show up in another suite's results.

Two ways to avoid that:

1. **Make data unique** with `testsuite.runId` (recommended). Suites then never see each other's rows.
2. Tick **Run alone** for suites that need the database to themselves, for example one that counts all rows. Those suites run one by one, after all the others have finished.

## Settings and databases

Setup and teardown use the same settings as the suite, including its [overrides](./overrides). If the suite points a database at a test copy, setup and teardown write to that test copy too.
