🧪 TTGO

Self-hosted, source-available test management — own your data, automate everything.

_{The test library — hierarchical folders, a filterable test grid, categories and bulk actions.}

---

Note

This README has two parts. Part 1 is the quick tour — what TTGO does, screenshots, and how it compares to other test management tools. Part 2 is the technical reference — stack, local setup, configuration, deployment and API. If you just want to run it, skip to the setup.

Part 1 · Overview

Why TTGO?

Test management usually forces a trade-off: a polished commercial SaaS (TestRail, Xray, qTest) that bills per seat and keeps your data on someone else's servers — or a free, self-hosted tool that feels a decade old.

TTGO is both. It's a modern, self-hosted, source-available platform with the features QA teams actually expect — rich test cases with version history, run execution with defect tracking, analytics with flaky-test detection, requirements traceability, AI test generation, a first-class CLI, and real-time collaboration — all running as a single Go binary against one SQLite file. Your infrastructure, your data, no per-seat pricing.

Highlights

• 🏠 Self-hosted — own your data. Runs entirely on your own infrastructure as a single Go binary and one SQLite file. Source-available under PolyForm Shield — no per-seat SaaS bills, nothing leaving your network.
• 🤖 AI test generation. Draft test cases from requirements using your own LLM provider (bring your own key). A review-and-approve flow means nothing is saved until you accept it.
• ⌨️ CLI & Claude Code automation. A first-class ttgo CLI drives tests, runs, analytics and more from the terminal or CI — and a bundled Claude Code skill lets you operate TTGO in plain English.
• ⚡ Real-time collaboration. WebSocket-powered live sync keeps every open tab and teammate up to date as runs are executed and test cases change.

…plus built-in defect tracking, rich-text editing with full version history, scheduled SQLite backups, API tokens & webhooks, and Jira / Confluence integrations. See the full feature list below.

Feature tour

Rich test cases — TipTap rich-text descriptions, ordered steps with expected results, full version history, and tabs for runs, defects and linked requirements.	Run execution — snapshot-based runs with per-result pass/fail, defect classification (product / automation / system), defect links, durations and comments.
Analytics — pass-rate trends, flaky-test detection, slowest tests, component health and side-by-side run comparison across any date range.	Requirements & traceability — a coverage-at-a-glance matrix linking requirements to test cases and surfacing the gaps.
Native defect tracking — lightweight bugs with severity and status, linked to failing results and managed on a dedicated Defects page in the Quality workspace; optionally reference an external Jira issue.	AI test generation — pick a requirement for context, describe what you want, and let your configured model draft test cases for review.

How TTGO compares

How TTGO stacks up against popular commercial and self-hosted test management tools:

Capability	TTGO	TestRail	Xray	qTest	Kiwi TCMS	Qase
Self-hosted / on-prem	✅	⚠️ 1	⚠️ 2	✅	✅	⚠️ 4
Source-available / open source	✅	❌	❌	❌	✅	❌
Free to self-host (no per-seat license)	✅	❌	❌	❌	✅	❌ 5
Built-in AI test generation	✅	✅	✅	✅	❌	✅
First-class CLI	✅	✅	❌	❌	⚠️	✅
REST API	✅	✅	✅	✅	⚠️ 3	✅
Webhooks / push notifications	✅	✅	⚠️ 6	✅	⚠️	⚠️ 6
Requirements & traceability matrix	✅	✅	✅	✅	⚠️	✅
Native Jira integration	✅	✅	✅	✅	✅	✅

_{✅ yes · ⚠️ partial, paid-tier-only, or caveated · ❌ no}

_{1. TestRail self-hosting is the customer-managed Server edition (seat minimum + annual contract); the default product is Cloud SaaS.  2. Xray runs as an app inside Jira, so on-prem requires Jira Data Center; Xray Cloud is SaaS.  3. Kiwi TCMS exposes a JSON-RPC / XML-RPC API rather than a conventional REST API.  4. Qase self-hosting is an Enterprise-tier dedicated-installation add-on; the standard product is SaaS.  5. Qase offers a free cloud plan (not self-hosted).  6. Webhooks vary by plan/host — e.g. Qase webhooks require a paid tier, and Xray typically relies on Jira's automation engine.}

Competitor capabilities and pricing are summarized from public documentation as of mid-2026 and change frequently — verify the current details with each vendor. Spotted something out of date? Open a PR.

---

Part 2 · Technical documentation

A self-hosted test case management tool built with Go and React.

Features

• Test Suite & Folder Management — hierarchical organization with drag-and-drop reordering
• Test Cases — rich text descriptions and steps, full version history with diff view
• Test Runs — snapshot-based execution, per-step pass/fail, screenshots, comments, native defect linking
• Defect Tracking — native, lightweight defects (title, description, severity, status) linked to test results and managed on a dedicated Defects page; optionally reference an external issue (e.g. Jira)
• Real-time Updates — WebSocket-powered live sync across open browser tabs
• Analytics — pass rate trends, flaky test detection, duration tracking, run comparisons
• Requirements & Traceability — link test cases to requirements, traceability matrix view
• Jira Integration — import requirements from Jira and post generated test cases back to the ticket
• Confluence Import — import requirements from Confluence pages
• AI Test Generation — generate test cases from requirements using LLM providers
• Database Backups — manual and scheduled SQLite backups with restore support
• API Tokens & Webhooks — automate runs and receive push notifications
• CLI — ttgo command-line tool for managing tests, runs, analytics, and more from the terminal
• Swagger Docs — full API documentation at /swagger/
• User Auth — session-based auth with admin and regular user roles
• Demo Data — one-click seed for exploring the UI

Tech Stack

Layer	Technology
Backend	Go 1.25, GORM, SQLite (mattn/go-sqlite3)
CLI	Cobra, tabwriter, JSON/table/plain output
API	net/http + routegroup, Gorilla WebSocket
Frontend	React 19.2, Vite, React Router
UI	TipTap (rich text), Recharts (analytics), @dnd-kit (drag & drop)
Deployment	Docker, Docker Compose, Nginx

Quick Start (local)

System requirements

TTGO is deliberately light — a single Go binary and one SQLite file. Measured footprint (see Performance): ~30 MB RAM idle, under 200 MB even at maximum load with 1,000 live WebSocket clients; the database grows roughly 2 GB per million stored results.

	Minimum (evaluation / small team)	Recommended (busy CI, large history)
CPU	1 core	2+ cores (the ~500 results/s ingest ceiling was measured on 10)
RAM	512 MB	1 GB (covers Docker + nginx comfortably)
Disk	1 GB	10 GB+ — ~2 GB per 1M results, plus WAL headroom during sustained CI bursts

Any small VPS or spare machine qualifies. Building from source needs the Go toolchain (1.25+, CGO with a C compiler for SQLite FTS5) and Node 22 for the frontend; the Docker deployment needs neither.

Backend

cd backend
make setup             # one-time: enables the required sqlite_fts5 build tag (needs CGO + gcc)
cp .env.example .env   # set ADMIN_EMAIL and ADMIN_PASSWORD
go run ./cmd/server/

Runs on http://localhost:8080. API docs at http://localhost:8080/swagger/.

Frontend

cd frontend
npm install
npm run dev

Runs on http://localhost:5173.

CLI

cd backend
make setup                     # if not already done
go build -o ttgo ./cmd/ttgo/
ttgo config set-server http://localhost:8080
ttgo config set-token <your-api-token>
ttgo tests list

Run ttgo --help for all available commands (tests, runs, folders, analytics, requirements, AI, backups, and more).

Claude Code Integration

The project includes a Claude Code skill (.claude/skills/ttgo/SKILL.md) that lets you operate TTGO through natural language. With Claude Code installed, just describe what you need:

> "Run the smoke tests and report the results"
> "Find all flaky tests and show their recent executions"
> "Import REQ-42 from Jira and generate test cases for it"

Claude Code will translate your request into the appropriate ttgo CLI commands, parse the output, and chain multi-step workflows automatically. The skill is loaded automatically when working in this repo.

E2E result reporting (dogfooding)

The Playwright e2e suite can push its own results into a running TTGO instance as a test run. It is opt-in: set TTGO_REPORT_TOKEN (a write-scoped API token from Settings → API Tokens) and the reporter auto-provisions a Playwright E2E folder, category, and one test case per Playwright test, then records each run with per-test pass/fail, duration, and failure details. With the token unset, the suite behaves exactly as before.

cd frontend
TTGO_REPORT_TOKEN=<write-token> npx playwright test

Variable	Default	Description
TTGO_REPORT_TOKEN	—	Write-scoped API token. Unset = reporter disabled.
TTGO_REPORT_URL	http://localhost:8080	TTGO API base URL to push results to
TTGO_REPORT_FOLDER	Playwright E2E	Folder that holds the auto-provisioned test cases
TTGO_REPORT_CATEGORY	Playwright E2E	Category attached to each run
TTGO_REPORT_RUN_NAME	Playwright E2E	Run-name prefix (a timestamp is appended)
TTGO_REPORT_ENV	e2e	environment label stored on each result

Reporting failures are logged and never fail the test run.

Configuration

The backend is configured via environment variables (or a .env file in the backend/ directory):

Variable	Default	Description
DB_PATH	tracker.db	Path to the SQLite database file
ADMIN_EMAIL	—	Email for the auto-created admin account
ADMIN_PASSWORD	—	Password for the auto-created admin account
CORS_ORIGIN	http://localhost:5173	Allowed CORS origin
LISTEN_ADDR	:8080	Address the server listens on

Deployment (Docker)

Copy the example env file and fill in your values. The example file lives at the repo root.

cp .env.example .env

Build and start:

docker compose up -d --build

The app will be available on port 80. The backend API is proxied under /api/ and WebSocket under /ws.

Redeploy after updates:

git pull
docker compose up -d --build

Performance

Measured with the load-test suite in perf/ (k6 against a single instance — one Go binary, one SQLite file — on an M1 Pro laptop, load generator on the same machine, so the numbers are conservative):

• Result ingestion: one instance sustains ~500 results/s; up to ~55 concurrent CI pipelines report simultaneously before add-result p95 exceeds 500 ms. Overload degrades gracefully — latency rises, errors stay near zero (first 5xx at ~135 concurrent pipelines), recovery is immediate.
• Dashboards stay fast while CI reports: read latencies are statistically unchanged under a sustained 250 results/s ingest load (SQLite WAL concurrent reads, verified empirically).
• Large datasets: full-text search and run-detail pages stay flat up to 1M results (search ≤16 ms p95); the runs list serves a page in ~61 ms p95 at that scale.
• Live updates: 1,000 concurrent WebSocket clients receive result events with ~26 ms p95 broadcast lag.
• A regression gate (make -C perf gate) guards these numbers against future changes. Methodology, caveats, and reproduction: perf/README.md.

API

Full REST API documentation is available at /swagger/ when the server is running.

Quick example — trigger a test run from CI:

# Create a run
curl -X POST http://localhost:8080/api/runs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"suite_id": "YOUR_SUITE_ID", "name": "CI Run #42"}'

# Update a result
curl -X PUT http://localhost:8080/api/runs/{run_id}/results/{test_id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "passed"}'

License & Usage

TTGO is source-available under the PolyForm Shield License 1.0.0 — see LICENSE. For almost everyone, that means one thing: it's free — no per-seat bills, no time limits, no catch.

✅ Free to use for:

• Running it internally — your team, your company, your infrastructure
• Personal projects, side projects, and evaluation
• Embedding it inside your own product, as long as that product doesn't compete with TTGO

The only catch — the few things PolyForm Shield doesn't allow:

• Re-offering TTGO itself as a hosted service (SaaS)
• White-labeling or reselling it as a standalone product
• Using it to build a competing test-management tool

In plain terms: build on it, run it, ship your product on it — just don't repackage TTGO into a competitor. The full legal terms are in LICENSE; the bullets above are a summary for convenience only.