8000 GitHub - sajith4u/VoltLoad: Simple API Load Testing Tool · GitHub
[go: up one dir, main page]

Skip to content
sajith4uPublic

About

Simple API Load Testing Tool

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

VoltLoad

Put Your Systems Under Pressure.

A local-first HTTP API load testing tool. It runs as a desktop app (built with Wails) or headless from the terminal, and both use the same Go engine. No server, database or internet connection is required apart from the target you are testing.

Screenshots

Dashboard: one card per performance suite, with a pass/fail strip of its recent runs, the last status, success rate and average response time.

VoltLoad dashboard showing a performance suite card

Run view: live and finished runs show requests/sec, average latency and active virtual users over time, followed by the run log.

VoltLoad run view with timeline charts and the run log

Features

  • Sign-in and sidebar navigation: the app opens on a login page. The first account is admin / admin; change the password from the sidebar ("Change password"). In browser mode (voltload serve) every API call, the event stream and the reports need the session, and the CLI is not affected
  • Frontend analysis (sidebar → Frontend analysis): enter a URL and VoltLoad loads it twice in headless Chrome (empty cache, then a repeat visit). It reports Core Web Vitals (TTFB, FCP, LCP, TBT, CLS) and page load, where the bytes go, every API call and request on a timeline, what the browser cached, and the React version, build type (development/production) and framework. It ends with ranked recommendations: slow or chained API calls, failed requests, large JavaScript bundles, missing compression or caching, large images, render-blocking files, layout shifts and more. Results are saved in a history. Needs Chrome, Chromium or Edge installed (or VOLTLOAD_CHROME=/path/to/chrome)
  • Performance suites: saved, re-runnable load tests, created through a step-by-step flow (details → request → workload → thresholds → review)
  • Dashboard: one card per suite with a pass/fail strip of its recent runs, last status, success rate, average response time and a Run button
  • Trend charts per suite across runs: average response time, hits/sec, p95 latency, error rate, total requests, duration
  • Virtual user engine: every virtual user runs concurrently as its own user, with a private connection, its own cookie session, optional random think time between requests, and its own statistics in the results
  • PDF report with the full details of a run: summary, response-time percentiles, thresholds, timeline charts, test configuration, status codes, errors and per-user statistics. Open it from a run with "View PDF report", or use --out report.pdf in the CLI
  • Request setup: method, URL, headers, body, timeout
  • Workloads: constant virtual users, or ramping stages, with Smoke / Load / Stress / Spike presets
  • Thresholds such as p95 < 500 or errorRate < 1 mark a run PASS or FAIL. The CLI exits with code 2 on FAIL, so CI jobs can gate on it
  • Live logs while a suite runs: stage changes, sampled requests per virtual user with status and response time, errors, and the final verdict, with filters for requests, errors and engine events. In the CLI: --logs
  • Backend logs: the same log is printed to the terminal running the app (so wails dev shows it) and appended to ~/.local/share/voltload/logs/voltload.log (%APPDATA%\VoltLoad\logs\voltload.log on Windows), each line tagged with the suite
  • Live run view (updates every 500 ms) with charts for requests/sec, latency and active VUs, plus a Stop button
  • Run history per suite: view, delete, compare two runs, export PDF / HTML / CSV / JSON reports
  • YAML scenarios shared by the desktop app (import/export) and the CLI. See examples/smoke.yaml

History is stored in ~/.local/share/voltload/database/voltload.db on Linux and %APPDATA%\VoltLoad\database\voltload.db on Windows.

Architecture

VoltLoad architecture: three clients (desktop window, browser, CLI) reach one Go application with a shared load engine, a SQLite database and report generators, all on the local machine

  • One engine, three front doors. The desktop window, the browser (voltload serve) and the CLI all drive the same load engine in internal/loader.
  • Desktop and browser share the same backend code (internal/gui). The desktop window reaches it through Wails bindings and events. The browser reaches it over HTTP (POST /api/call/{Method}) and Server-Sent Events, and that server only accepts loopback requests.
  • Every virtual user is its own user: a goroutine with its own connection and cookie jar. A stage controller raises and lowers how many of them are active, and the collector turns their results into percentiles, thresholds, a timeline and a sampled live log.
  • Everything is local. Suites and run history live in an embedded SQLite file, the backend log in a text file, and reports (PDF, HTML, CSV, JSON) are generated on demand. The only network traffic is to the API you are testing.
  • The CLI uses the engine, YAML scenarios and reports directly. It does not save history to the database.

The editable diagram sourc 74C6 e is docs/architecture.mmd (Mermaid). After editing it, re-render it, for example at mermaid.live, and replace docs/architecture.png.

Tech Stack

Backend: Go 1.26+

Frontend: React + TypeScript + Vite, embedded in the binary by Wails

Storage: SQLite (modernc.org/sqlite, pure Go)

Prerequisites

  • Go 1.26 or newer (Wails v2.17 requires it)
  • Node.js and npm
  • Wails CLI: go install github.com/wailsapp/wails/v2/cmd/wails@v2.17.1 (installs to $(go env GOPATH)/bin, so make sure that directory is on your PATH)
  • Linux only: sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev

Run wails doctor to check your setup.

Run Locally

Clone the project

  git clone https://github.com/sajith4u/VoltLoad.git
  cd VoltLoad

Desktop app, with live reload

  wails dev

Full app in your browser (no GTK/WebKit needed). It's the same backend as the desktop app: real load, the same database, reports and logs. It listens on 127.0.0.1 only:

  cd frontend && npm install && npm run build && cd ..
  go build -o voltload .
  ./voltload serve --open        # http://127.0.0.1:7878 (--addr, --data-dir to change)

Working on the UI with hot reload: cd frontend && npm run dev (or wails dev). The Vite dev server builds and starts the Go backend on 127.0.0.1:7878 by itself, forwards /api to it, and stops it on exit. If voltload serve is already running on that port, it uses that instead. Go changes need a dev-server restart. Set VOLTLOAD_NO_BACKEND=1 to skip starting the backend, or VOLTLOAD_PORT to use another port.

Desktop app, production build (output in build/bin/)

  wails build
  ./build/bin/voltload

CLI only (no GUI dependencies needed)

  go build -o voltload .
  ./voltload run --url https://example.com --vus 10 --duration 30
  ./voltload run --url https://api.local/items -X POST \
      -H "Content-Type: application/json" -d '{"a":1}' --requests 1000 --json

  # scenario file; flags override it. Exit code 2 if a threshold fails.
  ./voltload validate examples/smoke.yaml
  ./voltload run examples/smoke.yaml --threshold "p95<500" --out report.html
  ./voltload run examples/smoke.yaml --think-min 200 --think-max 800 --out report.pdf
  ./voltload run examples/smoke.yaml --logs      # live log instead of the progress line
  ./voltload report result.json -o report.pdf    # convert a saved JSON result
  ./voltload version

Running the binary with no arguments opens the desktop window. voltload <command> --help lists all flags. Press Ctrl+C to stop a CLI run early; the results collected so far are still printed.

Tests

  go test ./...

License

MIT License

About

Simple API Load Testing Tool

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

0