Flow Runner

The Flow Runner executes .flow files sequentially — chaining requests, passing extracted values between steps, verifying assertions at each stage, and producing a visual test report.

Running a flow

Open any .flow file and press ⌘Enter (or click the ▶ button). The Results Panel shows an animated pipeline:

• ✅ Green — request succeeded, all assertions passed
• ❌ Red — request failed or an assertion failed (details shown inline)
• ⏳ Spinning — currently executing

Extraction

Use # @extract with a JSONPath expression to capture response values. Extracted variables are available in all subsequent steps.

### Create order
# @name createOrder
POST {{baseUrl}}/orders
Content-Type: application/json

{ "item": "Widget", "qty": 2 }

# @extract orderId = $.id
# @extract total   = $.price.total
# @extract status  = $.status

JSONPath examples:

# @extract id      = $.id
# @extract first   = $.users[0].name
# @extract count   = $.meta.total
# @extract token   = $.auth.access_token

Assertions

# Status code
# @assert status == 201
# @assert status != 404
# @assert status >= 200
# @assert status <  300

# Body content
# @assert body contains "success"
# @assert body matches ^\{          ← regex

# Header value
# @assert header[content-type] contains json

A failing assertion stops the flow at that step and shows the actual vs expected values.

Persist to .env.local

Use # @persist to save an extracted value into <env>.env.local so other files and future runs can use it — even across app restarts.

### Login
POST {{BASE_URL}}/auth/login
Content-Type: application/json

{ "email": "dev@example.com", "password": "..." }

# @extract token = $.access_token
# @assert  status == 200

# Write token to dev.env.local for reuse
# @persist token

# Or write with a different key
# @persist API_TOKEN = {{token}}

Rules:

• Persists run after all @asserts — a failing assertion prevents every persist in that request.
• Persists are skipped for envs named prod or production.

Skip & retry

### Optional step — won't run
# @skip
GET {{baseUrl}}/health

### Flaky endpoint — retry up to 3 times on failure
GET {{baseUrl}}/health
# @retry 3

Literate test reports

Non-directive # comments become prose in the report. This lets you write .flow files that read like documentation when run.

# Checkout Flow
#
# Validates the end-to-end purchase process:
# add item to cart, apply coupon, and complete checkout.

### Add item to cart
# We add a single item and verify the cart total.
POST {{baseUrl}}/cart/items
Content-Type: application/json

{ "productId": 42, "qty": 1 }

# @extract cartId = $.cartId
# @assert status == 200

Click Export as Markdown in the Results toolbar to share the report.

Full example

# User CRUD Lifecycle

@baseUrl = https://api.example.com

### Step 1 · Create user
# @name createUser
POST {{baseUrl}}/users
Content-Type: application/json

{ "name": "Jane", "email": "jane@example.com" }

# @extract userId   = $.id
# @extract userName = $.name
# @assert  status == 201

### Step 2 · Fetch user
GET {{baseUrl}}/users/{{userId}}
# @assert status == 200
# @assert body contains {{userName}}

### Step 3 · Update user
PUT {{baseUrl}}/users/{{userId}}
Content-Type: application/json

{ "name": "Jane Updated" }

# @assert status == 200

### Step 4 · Delete user
DELETE {{baseUrl}}/users/{{userId}}
# @assert status == 204

See the .flow file format for the complete syntax reference.