CLI Load Testing

Run load, stress, spike, and soak tests from your terminal. .spec.json files define virtual users, stages, thresholds, and multi-step request flows. A real-time terminal dashboard shows response times, throughput, error rates, and percentile breakdowns.

Quick Start

# Run all specs in a directory
tgrs run api-specs

# Run specific specs
tgrs run api-specs -s user-api,auth-api

# Run with environment
tgrs run api-specs -s user-api -e staging

# Run a stress test
tgrs run api-specs -s user-api -t stress

Test Types

Type	VUs	Ramp	Duration	Purpose
load (default)	50	30s	60s	Gradual ramp up, sustained load, gradual ramp down
stress	200	10s	60s	Aggressive increase to find breaking points
spike	300	2s	30s	Sudden spike to high load
soak	30	30s	300s	Long duration with low, steady load
custom	Custom	Custom	Custom	User-defined stages

Flags

Flag	Alias	Description
-s	--spec	Spec names (comma-separated)
-t	--type	Test type (load, stress, spike, soak, custom)
-e	--env	Environment name

Real-time Dashboard

The terminal dashboard updates live during test execution:

• Summary cards - Total requests, success rate, average response time, throughput, active VUs
• Response time chart - Per-spec line chart over time
• Throughput chart - Requests per second
• Error rate chart - Error percentage over time
• Active VUs chart - Virtual user count over time
• Step breakdown table - Requests, average, P50, P90, P95, P99, error rate, r/s per step
• Error analysis - Pinpoints which steps fail and why (assertion failures, network errors)

Multi-Step Specs

Each spec can contain multiple steps that execute sequentially per virtual user. Steps support:

• Variable extraction between steps ({{flow.varName}})
• Environment variables ({{varName}})
• Random data ({{random.*}})
• Assertions per step
• Pre/post scripts with the tg scripting API

Scripting API in Load Tests

The same tg API available in flows works in load test specs:

beforeAll script - Run once before the test starts:

tg.flow.set("token", "shared-auth-token");

Pre-request script - Run before each request:

tg.request.setHeader("X-VU-Id", tg.flow.get("vuId"));

Post-response script - Run after each response:

tg.flow.set("orderId", tg.response.json().id);

afterAll script - Export reports after the test completes:

var html = tg.export.html();
fetch("https://webhook.example.com/report", {
  method: "POST",
  headers: { "Content-Type": "text/html" },
  body: html,
});

var pdf = tg.export.pdf();
fetch("https://webhook.example.com/report-pdf", {
  method: "POST",
  headers: { "Content-Type": "application/pdf" },
  body: pdf,
});

Export Reports

Generate reports from afterAll scripts:

• HTML - Interactive report with embedded charts
• PDF - Printable documentation
• JSON - OpenTelemetry-compatible format for observability platforms

Environments

Define variables per environment in environments.json:

Variable	Development	Staging	Production
base_url	http://localhost:3000	https://staging.api.com	https://api.com
api_key	dev-key-123	stg-key-456	prod-key-789

Variables marked as secret are masked in the UI. Vault-sourced variables are supported via VAULT_AUTH environment variable.