Load Testing with atra

Run load, stress, spike, and soak tests with real-time terminal dashboards, thresholds, and export reports.

Getting Started

Running a Load Test

Load tests are defined as JSON spec files in a directory and run with atra run. Point atra to the directory containing your specs.

# Run all specs in a directory

atra run spec-folder-name

# Run specific specs

atra run spec-folder-name -s user-api,auth-api

# Run with an environment

atra run spec-folder-name -s user-api -e staging

Note: If you're already inside the spec folder, you can omit the path: atra run runs all specs in the current directory, or use atra run -s spec-1,spec-2 to select specific ones.

Test Types

Five Test Types

Select the test type with -t / --type. Each type has predefined VU counts, ramp periods, and durations that you can override in your spec.

load (default)

Gradual ramp up, sustained load, gradual ramp down. 50 VUs, 30s ramp, 60s duration.

stress

Aggressive increase to find breaking points. 200 VUs, 10s ramp, 60s duration.

spike

Sudden spike to high load. 300 VUs, 2s ramp, 30s duration.

soak

Long duration with low, steady load. 30 VUs, 30s ramp, 300s duration.

custom

User-defined stages with custom VU targets and durations.

# Run a stress test

atra run spec-folder-name -s user-api -t stress

# Run a spike test

atra run spec-folder-name -s user-api -t spike

# Run a soak test

atra run spec-folder-name -s user-api -t soak

Note: The values shown above (VUs, ramp, duration) are defaults. You can fully customize them per test type in Atrahasis Pro when creating your spec.

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 per iteration

Real-Time Dashboard

Terminal Dashboard

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

Live charts: response times, throughput, and error rates over time
Step execution table: status of each step with success/failure counts
Error tracking: real-time error log with breakdown by type
Spec summaries: per-spec results with pass/fail status

Export Reports

Report Formats

Export test results in multiple formats for sharing and archiving.

HTML: interactive report with embedded charts
PDF: printable report
JSON: the complete run result, including the config, the aggregate summary, the time series, the per-step breakdown and the threshold results

All three come from an After All script through at.export, exactly as they do in the desktop app and exactly as they do for flows. Generate the report and post it wherever it needs to go.

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

Live Metrics Streaming

A report tells you how the run went once it is over. Streaming lets you watch it while it happens. When a spec has OTLP export turned on, atra pushes a metrics snapshot every second to your collector, so a long soak test can be followed on a dashboard instead of a terminal.

There is no extra flag for it. The toggle and the collector URL live on the spec itself, set in the desktop app and carried in the same .spec.json file atra reads. Anything that accepts OTLP over HTTP works, whether that is an OpenTelemetry Collector, Grafana Alloy, or a vendor endpoint.

What is sent

Response time percentiles, throughput, error rate, active virtual users and cumulative request and error counters, plus the same family of metrics broken down per step. Every payload carries the run id, the spec name and the test type as resource attributes, so several runs can share one dashboard without mixing.

It never slows the test down

Sending is fire and forget. Each snapshot goes out on a background task with a three second timeout, a snapshot is skipped rather than queued if the previous one is still in flight, and a collector that is slow, unreachable or returning errors is ignored. The run continues either way, and the numbers in your report are unaffected.

Environments

Environment Variables

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

# Run with staging environment

atra run spec-folder-name -s user-api -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.

# Run with Vault-sourced secrets

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

atra run spec-folder-name -s user-api -e dev

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

Quick Reference

Run Command Flags

Flag	Alias	Description
-s	--spec	Spec names (comma separated)
-t	--type	Test type (load/stress/spike/soak/custom)
-e	--env	Environment name
VAULT_AUTH		Vault credentials (credentials@url)
VAULT_AUTH_<NAME>		Named vault connection (e.g., VAULT_AUTH_PROD)

Flow Runner Scripting