Flow Runner in atra

Chain multiple API calls into sequential flows with variable passing, assertions, retry logic, and parallel execution.

Getting Started

Running a Flow

Flows are defined as .flow.json files. Run them with the -f flag.

# Run a specific flow

atra run flow-folder-name -f user-registration

# Run with environment

atra run flow-folder-name -f user-registration -e dev

# Run 5 iterations sequentially

atra run flow-folder-name -f user-registration -i 5

# Run with 3 parallel workers

atra run flow-folder-name -f user-registration -p 3

# Stop on first failure

atra run flow-folder-name -f user-registration -c

Note: If you're already inside the flow folder, you can omit the path: atra run runs all flows in the current directory, or use atra run -f flow-name to select a specific one.

Variables

Variable Types

{{flow.varName}}Flow variables: carry data between steps (e.g., tokens, IDs)

{{varName}}Environment variables: see the Environments section for details

{{random.type}}Random variables: fresh random value each time

Parallel Execution

Iterations & Parallel

Run the same flow multiple times, sequentially or in parallel.

# Run 5 iterations sequentially

atra run flow-folder-name -f user-flow -i 5

# Run with 3 parallel workers

atra run flow-folder-name -f user-flow -p 3

Real-Time Dashboard

Terminal Dashboard

When you run a flow, atra displays a real-time terminal UI (TUI) dashboard showing:

Live charts: response times over time
Step execution table: status of each step with success/failure counts
Error tracking: real-time error log with breakdown by type
Anomaly detection: automatic detection of unusual patterns
Iteration summaries: per-iteration statistics when using -i or -p

Exit Codes

Flow Result Codes

0All steps passed, all assertions passed

1One or more steps failed or assertions failed

Tip: Use exit codes in CI/CD pipelines to gate deployments based on API flow test results.

Export Reports

Report Formats

Export flow results in multiple formats for sharing and archiving.

HTML: interactive report with embedded charts
PDF: printable report
OpenTelemetry JSON: spans and timings in OTLP shape, ready to post to an observability platform

Tip: Reports can be exported and sent to external services using lifecycle scripts. See the Scripting section for detailed examples.

Environments

Environment Variables

Use environments to manage different configurations (dev, staging, prod) for your flows. Select an environment at runtime with -e / --env.

atra run flow-folder-name -f user-flow -e staging

Tip: Environments are created and managed in Atrahasis Pro. See the Environments section for more details.

Vault Integration

HashiCorp Vault

Environment variables can be sourced from HashiCorp Vault for secure secret management. Provide vault credentials at runtime with VAULT_AUTH environment variables.

VAULT_AUTH="hvs.token@http://vault:8200" \

atra run flow-folder-name -f user-flow -e dev

Tip: See the Vault section for detailed configuration, multiple connections, and authentication methods.

Quick Reference

Flow Runner Flags

Flag	Alias	Description
-f	--flow	Flow names (comma separated)
-e	--env	Environment name
-i	--iterations	Number of iterations (default: 1)
-p	--parallel	Parallel execution count (default: 1)
-c	--stop-on-failure	Stop on first failure
VAULT_AUTH		Vault credentials (credentials@url)
VAULT_AUTH_<NAME>		Named vault connection (e.g., VAULT_AUTH_PROD)

Sessions & Storage Load Testing