tensgo
DOCUMENTATIONv0.2.0

tensgo Technical Reference

Single-binary Go stress engine. Everything from interactive TUI workflows to automated CI/CD latency gates.

01.

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$go install github.com/Errtu0/tensgo@latest
MOCK SERVER$go run ./examples/mock_server.go -addr :8080
LAUNCH TUI$tensgo
02.

Interactive 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.

[h]
Export HTML Report

Generates a self-contained dark-mode HTML artifact after any run.

[a]
Select All Routes

Toggles all discovered OpenAPI endpoints in the interactive picker.

[q] / [Ctrl+C]
Graceful Stop

Drains in-flight workers and prints final percentile summary.

03.

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 5s
04.

What-If Chaos Profiles

Available directly from the TUI control center to uncover non-linear failure thresholds before production traffic hits:

SPIKE

Sudden burst from baseline to peak VUs, measuring Recovery Time once load subsides.

RAMP-UP

Stepped concurrency escalation to pinpoint the exact Breaking Point VU capacity.

SOAK

Sustained load window tracking Latency Degradation % and memory/connection leaks.

05.

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.yaml
name: "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: 1
06.

CLI Flags & CI/CD Quality Gates

FlagDefaultDescription
-u <url>""Target URL to load test (required unless --openapi or --scenario is set).
-c <int>10Number of concurrent virtual users (workers).
-d <duration>10sTest duration (e.g. 5s, 30s, 2m).
-m <method>GETHTTP method for single-endpoint tests.
-H <header>[]HTTP header in 'Key: Value' format (repeatable).
-b <body>""Raw HTTP request body payload.
-t <duration>5sPer-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>0sCI/CD threshold: maximum allowed P95 latency (e.g. 300ms). Exits 1 on breach.
--max-error-rate <float>-1CI/CD threshold: maximum allowed error rate in percent (e.g. 1.0). Exits 1 on breach.
--no-tuifalseDisable 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.html
name: 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