Load Testing

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 tgrs run. Point tgrs to the directory containing your specs.

# Run all specs in a directory

tgrs run spec-folder-name

# Run specific specs

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

# Run with an environment

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

Note: If you're already inside the spec folder, you can omit the path: tgrs run runs all specs in the current directory, or use tgrs 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

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

# Run a spike test

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

# Run a soak test

tgrs 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 Tigrister 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, tgrs 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
OpenTelemetry JSON — For integration with observability platforms

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 load tests. Select an environment at runtime with -e / --env.

# Run with staging environment

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

Tip: Environments are created and managed in Tigrister 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" \

tgrs 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