Seeding

Some claims need data that exists before a test starts: an account, a token, a row. The seed creates it once per run, and every test in the run reuses what it made. Flow setup writes the seed in its Preparing data + principals step. It writes a seed script against the live services and runs it to prove it works. Then it proves the result again in a fresh environment before it keeps it. The seed script is stored with Flow setup’s results and is never written into your repository.

How the seed is declared

The seed lives in the recipe, under api.seed:

{
  "api": {
    "serve": ["node", "dist/server.js"],
    "services": { "up": "docker compose up -d db", "down": "docker compose down" },
    "seed": {
      "command": "node scripts/guard-seed.mjs",
      "script": "scripts/guard-seed.mjs",
      "provides": {
        "credentials": {
          "owner": { "header": "Authorization", "description": "org owner", "satisfies": "bearerAuth" }
        },
        "fixtures": { "org": ["id", "slug"] }
      }
    }
  }
}

Field	What it does
`command`	One shell command, run in the repository root.
`script`	The path of the seed script.
`provides`	What the seed promises to emit, without any values. Each credential names its `header`, and optionally a `description` of the principal and the OpenAPI scheme it `satisfies`. Each fixture maps a name to its fields.

No secret ever enters the recipe. Only provides does, so changing it changes which tests can be written.

The manifest

The run sets GUARD_SEED_OUT to a temporary file path. The seed command writes its results there as JSON:

{
  "credentials": { "owner": { "value": "Bearer eyJhbGci…" } },
  "fixtures": { "org": { "id": 42, "slug": "acme" } }
}

Every declared credential and every declared fixture field must be present. A gap stops the run as seed-failed, naming what is missing. Extra keys are ignored with a warning. Fixture values keep their JSON type, so a number stays a number.

When it runs

The seed runs once per run, in the repository root. It runs after api.services.up has started the datastores, and before any server boots.

Using it in tests

{{cred:owner}} sends a seeded credential in a header value. Seeded credentials join the static ones from api.credentials.
{{fixture:org.id}} inserts a fixture value. When a JSON value is exactly one placeholder, the native value is sent, so {"orgId": "{{fixture:org.id}}"} sends the number 42.

Credential values are masked in every transcript as «cred:<name>». Fixtures are ids and handles, not secrets, so they stay readable.

What survives

Each API test boots a fresh server. Seeded state survives only when it lives outside the server process, in a datastore that api.services.up starts, such as Postgres or Redis.

When a flow needs data the seed does not make

A flow that needs data the seed script does not create is Blocked, and says that it needs seed data. The app points you to Flow setup, which writes and proves the seed.

Getting Started

Workspace

Context

Code

Flows

Settings

Configuration

Enterprise

How the seed is declared

The manifest

When it runs

Using it in tests

What survives

When a flow needs data the seed does not make

Next steps

External services

Flow generation

​How the seed is declared

​The manifest

​When it runs

​Using it in tests

​What survives

​When a flow needs data the seed does not make

​Next steps

External services

Flow generation

How the seed is declared

The manifest

When it runs

Using it in tests

What survives

When a flow needs data the seed does not make

Next steps