The recipe

The recipe tells a run how to install, build and start the program, and what each driver drives. Flow setup derives the recipe and proves it by running it. The recipe is stored with the rest of Flow setup’s results, one set per commit, and is never written into your repository. The web app does not edit the recipe. When the inputs the recipe was derived from change, the next Flow setup derives it again.

The recipe has a fingerprint. When it changes, the flows written against the old recipe are written again by the next Flow generation. That is also how declaring a service unblocks the flows that needed it.

Fields

{
  "install": "pnpm install --frozen-lockfile",
  "build": "pnpm build",
  "entry": ["node", "dist/cli.js"],
  "env": { "MY_FLAG": "1" }
}

Field	What it does
`install`	Optional. One shell command, run in the repository root before the build, to fetch dependencies.
`build`	One shell command, run in the repository root before the tests.
`entry`	The command line that CLI tests run. Each test’s own arguments are appended to it.
`env`	Extra environment variables for every test.
`ownHosts`	Hosts the program owns, such as its own production domain. URLs pointing at them are not counted as external services.
`api`	How to start the HTTP service that API tests drive.
`web`	How to start the web app that web steps drive.

The api block

{
  "build": "pnpm build",
  "api": {
    "serve": ["node", "dist/server.js"],
    "healthPath": "/health",
    "services": { "up": "docker compose up -d db", "down": "docker compose down" }
  }
}

Field	What it does
`serve`	The command that starts the server. The run picks a free port and sets `PORT`. A server that does not read `PORT` can take `${PORT}` in its command or its environment.
`cwd`	Where the server runs: `sandbox`, the default, or `repo`. Use `repo` for a package-manager command such as `pnpm --filter api start`.
`healthPath`	Polled until it answers 2xx. Defaults to `/`.
`readyTimeoutMs`	How long the server has to answer its health path. Defaults to 30 seconds.
`env`	Environment variables for the server only.
`services`	`up` and `down` shell commands for the datastores the server needs. They run once per run, in the repository root.
`servers` and `defaultServer`	Several named servers instead of one `serve`, for a repository with more than one service. Each server names the `app` directory it serves.
`credentials`	Secrets that tests send in request headers. See below.
`seed`	The data and principals tests need. See Seeding.
`externals`	Accounts for third-party services. See External services.

How API tests use the server:

Each API test gets a fresh server in its own sandbox.
A test sends requests and checks the status, headers and body. It can capture values from a response body with capture, or from its headers with captureHeaders, and reuse them in later steps.
Each test has its own cookie jar. A cookie the server sets is sent back on later requests, so a login is just a first step.
Tests can also drive the server process itself, with boot, signal and logs steps.

The web block

Field	What it does
`build`	Optional. Runs after the top-level build, and only when the run has web steps.
`serve`	The command that starts the web app. The run sets `PORT`.
`cwd`	`sandbox`, the default, or `repo`.
`healthPath`	Polled until it answers 2xx before the first web step. Defaults to `/`.
`readyTimeoutMs`	How long the web app has to become ready. Defaults to 60 seconds.
`env`	Extra environment variables for the web app.
`app`	The directory of the app under test, for a repository with more than one app.

A recipe that declares web also declares entry or api, because web steps run inside an ordinary test.

Credentials

Each entry in api.credentials names a request header and one source for its value: value, valueFromEnv or fromRequest. A test uses a credential by writing {{cred:<name>}} in a header value. An optional satisfies names the OpenAPI security scheme the credential fulfills, and an optional servers list limits it to the servers it authenticates against. fromRequest logs in instead of storing a value:

{
  "api": {
    "serve": ["node", "dist/server.js"],
    "credentials": {
      "owner": {
        "header": "Authorization",
        "fromRequest": {
          "method": "POST",
          "path": "/auth/login",
          "json": { "email": "dev@example.com", "password": "devpassword" },
          "capture": "token",
          "template": "Bearer ${value}"
        }
      }
    }
  }
}

The run makes that call once and uses the captured value. capture is a path into the JSON body, and captureHeader reads a response header instead. When the login fails, the whole run stops as credential-request-failed rather than running unauthenticated. Every resolved credential is masked in transcripts as «cred:<name>».

Getting Started

Workspace

Context

Code

Flows

Settings

Configuration

Enterprise

Fields

The api block

The web block

Credentials

Next steps

Seeding

External services

​Fields

​The api block

​The web block

​Credentials

​Next steps

Seeding

External services

Fields

The api block

The web block

Credentials

Next steps