tensgo Technical Reference
Single-binary Go stress engine. Everything from interactive TUI workflows to automated CI/CD latency gates.
Installation & Quickstart
Install tensgo directly via Go 1.22+ or download a prebuilt static binary for Linux, macOS, or Windows from GitHub Releases.
go install github.com/Errtu0/tensgo@latestgo run ./examples/mock_server.go -addr :8080tensgoInteractive TUI & Shortcuts
Running tensgo with no flags launches the Larch-themed TUI control center. Navigate between Quick HTTP Load Test, OpenAPI Auto-Discovery, What-If Chaos Profiles, and Stateful YAML Scenarios using arrow keys.
Generates a self-contained dark-mode HTML artifact after any run.
Toggles all discovered OpenAPI endpoints in the interactive picker.
Drains in-flight workers and prints final percentile summary.
OpenAPI Auto-Discovery & Auto-Auth
Provide a Swagger 2.0 or OpenAPI 3.0 JSON file or URL via --openapi. tensgo automatically synthesizes valid request payloads from schema definitions, detects login routes to extract Bearer tokens when needed, and benchmarks every selected route into a ranked Bottleneck Comparison Matrix.
tensgo --openapi ./examples/03-openapi-demo.json --token "Bearer demo-token-123" -d 5sWhat-If Chaos Profiles
Available directly from the TUI control center to uncover non-linear failure thresholds before production traffic hits:
Sudden burst from baseline to peak VUs, measuring Recovery Time once load subsides.
Stepped concurrency escalation to pinpoint the exact Breaking Point VU capacity.
Sustained load window tracking Latency Degradation % and memory/connection leaks.
Stateful YAML Scenarios
Each virtual user maintains an isolated variable store. Extract tokens or IDs via JSONPath in an early step and inject them downstream with {{token}}.
tensgo --scenario ./examples/02-auth-checkout-flow.yamlname: "Authenticated Checkout Flow" # Scenario display name
base_url: "http://localhost:8080" # Base URL prepended to all step paths
vus: 20 # Concurrent virtual users
duration: "15s" # Total scenario execution window
steps:
- name: "Login"
method: "POST"
path: "/api/login"
body:
email: "demo@larch.dev"
password: "secret"
extract: # JSONPath extraction scoped per-VU
token: "$.token"
- name: "Fetch Profile"
method: "GET"
path: "/api/profile"
headers:
Authorization: "Bearer {{token}}"
- name: "Create Order"
method: "POST"
path: "/api/orders"
headers:
Authorization: "Bearer {{token}}"
body:
item: "tensgo-pro"
quantity: 1CLI Flags & CI/CD Quality Gates
| Flag | Default | Description |
|---|---|---|
| -u <url> | "" | Target URL to load test (required unless --openapi or --scenario is set). |
| -c <int> | 10 | Number of concurrent virtual users (workers). |
| -d <duration> | 10s | Test duration (e.g. 5s, 30s, 2m). |
| -m <method> | GET | HTTP method for single-endpoint tests. |
| -H <header> | [] | HTTP header in 'Key: Value' format (repeatable). |
| -b <body> | "" | Raw HTTP request body payload. |
| -t <duration> | 5s | Per-request HTTP timeout. |
| --openapi <path|url> | "" | OpenAPI/Swagger JSON URL or local file path to scan and benchmark. |
| --token <value> | "" | Authorization header value for OpenAPI scan (e.g. 'Bearer xyz'). |
| --scenario <path> | "" | Path to stateful YAML scenario file (e.g. ./examples/02-auth-checkout-flow.yaml). |
| --html <file> | "" | Write standalone dark-mode HTML report to file (e.g. report.html). |
| --max-p95 <duration> | 0s | CI/CD threshold: maximum allowed P95 latency (e.g. 300ms). Exits 1 on breach. |
| --max-error-rate <float> | -1 | CI/CD threshold: maximum allowed error rate in percent (e.g. 1.0). Exits 1 on breach. |
| --no-tui | false | Disable live TUI progress animation (auto-disabled in non-TTY CI environments). |
GitHub Actions Gate Example
tensgo -u https://api.staging.example.com/health -c 50 -d 30s --max-p95 250ms --max-error-rate 1.0 --html gate-report.htmlname: tensgo Performance Gate
on:
pull_request:
branches: [main]
jobs:
latency-gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.22"
- name: Install tensgo
run: go install github.com/Errtu0/tensgo@latest
- name: Run CI/CD Gate
run: tensgo -u https://api.staging.example.com/health -c 50 -d 30s --max-p95 250ms --max-error-rate 1.0