Create one flow for one named piece of logic, such as User onboarding, Login smoke, or Checkout happy path. Keep the sequence focused and ordered.
Use inputs for values the runner should ask for at runtime, such as email, name, or tenantId. Mark required inputs with "required": true.
Use extract to capture values from a response, then reuse them in later steps with {{vars.someName}}. Common examples are IDs, tokens, and timestamps.
Each step should validate the expected behavior. Start with status, then add body checks like "$.id" or "$.email". This keeps the same flow useful as an integration test.
{{input.email}}: runtime values entered in the UI or CLI{{vars.userId}}: values extracted from previous steps{{env.baseUrl}}: environment values loaded from the flow or env file{
"baseUrl": "{{env.baseUrl}}",
"request": {
"path": "/users/{{vars.userId}}",
"body": {
"email": "{{input.email}}"
}
}
}
{
"id": "create-user",
"request": {
"method": "POST",
"path": "/users",
"body": { "email": "{{input.email}}" }
},
"extract": {
"userId": { "from": "body", "path": "$.id" }
},
"assert": {
"status": 201
}
}
{
"extract": {
"userId": { "from": "body", "path": "$.id" },
"etag": { "from": "header", "path": "etag" }
},
"assert": {
"status": 201,
"body": {
"$.email": "{{input.email}}"
},
"exists": ["$.id", "$.createdAt"]
}
}
{
"version": 1,
"name": "User onboarding",
"baseUrl": "http://localhost:3000",
"inputs": {
"email": { "type": "string", "required": true },
"name": { "type": "string", "required": true }
},
"steps": [
{
"id": "create-user",
"request": {
"method": "POST",
"path": "/users",
"body": {
"email": "{{input.email}}",
"name": "{{input.name}}"
}
},
"extract": {
"userId": { "from": "body", "path": "$.id" }
},
"assert": { "status": 201 }
},
{
"id": "get-user",
"request": {
"method": "GET",
"path": "/users/{{vars.userId}}"
},
"assert": {
"status": 200,
"body": { "$.id": "{{vars.userId}}" }
}
}
]
}
Store flow files in doctreen-flows/*.json or configure flowsPath. The same definition can be run here in the docs UI or headlessly with doctreen-flow run ....
Select documented routes, configure steps, and export a reusable flow JSON draft.
{
"version": 1,
"name": "",
"description": "",
"baseUrl": "{{env.baseUrl}}",
"env": {
"baseUrl": "http://localhost:3000"
},
"inputs": {
"email": { "type": "string", "required": true }
},
"steps": []
}