got

Test runner for Go, Rust, vitest, and Lua with interactive TUI.

Install

go install github.com/mdjarv/got@latest
# or
just build

Usage

got [path]              # run tests, show summary (default)
got ./...               # run all tests
got -v ./...            # verbose: show every test pass/fail
got -r ./...            # race detection
got -t "TestFoo" ./...  # filter by pattern
got -q ./...            # exit code only
got --json ./...        # NDJSON to stdout
got --json -w ./...     # streaming NDJSON with watch
got --json-file out.json ./...  # NDJSON to file
got --json --filter fail,build_error ./...  # emit only specific event types
got --json --summary ./...      # compact: run_start + failures + run_end
got --json --failures-only ./...  # suppress passing test output
got --rerun-failed ./...        # re-run only previously failed tests
got --report ./...      # single JSON report (failures, counts, rerun commands)
got ui [path]           # interactive TUI
got ui -w ./...         # TUI with watch mode
got discover [dir]      # static test discovery (JSON)
got discover --names .  # plain text, one test per line
got serve [path]        # socket server for editor integration
got client status       # query running server
got client status --json  # JSON output (--json works on all client subcommands)
got client failures     # show failing tests from server
got client failures --format '{{.Package}}/{{.Test}} {{.File}}:{{.Line}}'
got client rerun        # trigger rerun on server
got client run -t "TestFoo" ./pkg  # focused run via server
got client stop         # stop current run on server
got client list         # list all tests from last run
got client list --status fail  # filter by status (pass|fail|skip)
got client coverage     # show coverage from server
got client coverage --threshold 80  # exit 1 if below 80%
got client wait         # block until current run finishes
got client watch        # stream live events from server
got history runs        # list recent test runs
got history flaky       # list flaky tests
got history test TestFoo  # per-test pass/fail timeline
got skill               # print AI agent skill prompt

Features

• Real-time streaming test output
• Tree hierarchy: package > test > subtest
• Smart sorting: failures first, then by duration
• Watch mode: auto-rerun on file changes
• Testify assertion formatting (expected/actual/diff)
• Panic stack trace parsing
• Build error handling
• Output pane with scroll and word wrap
• Fuzzy filter (/)
• Help overlay (?)
• Hide passed tests
• JSON/NDJSON output mode (--json, --json-file)
• Event type filtering (--filter)
• Summary mode: compact failure list at end (--summary)
• Failures-only mode: suppress passing output (--failures-only)
• Output budget per test (--max-output)
• Single JSON report (--report)
• Rerun only previously failed tests (--rerun-failed)
• Coverage analysis (--cover, --coverprofile)
• Benchmark support (--bench)
• Test history with flaky detection (--history)
• Test quarantine (--quarantine)
• Socket server for editor integration (got serve)
• CLI client for querying server state (got client)
• Static test discovery (got discover)
• Language support: Go, Rust (nextest/cargo test), vitest, Lua (busted/plenary)
• AI agent skill prompt (got skill)

Keybindings

Key	Action
j / k	Move down / up
gg / G	Jump to top / bottom
Enter	Toggle expand/collapse
h / l	Collapse / expand node
ctrl+d / ctrl+u	Half-page scroll
Tab	Toggle tree/output focus
o	Toggle output pane
W	Toggle word wrap
p	Toggle hide passed
r	Rerun selected
R	Rerun all failed
a	Rerun all
w	Toggle watch mode
/	Filter
?	Help
Esc	Clear filter / close
q	Quit

Flags

Flag	Description
-r, --race	Enable race detection
-v, --verbose	Verbose output
-t, --run	Test name pattern filter
-w, --watch	Watch mode (requires --json; use got ui -w for interactive)
-q, --quiet	Suppress output, exit code only
--json	NDJSON output to stdout
--json-file	NDJSON output to file
--filter	Emit only listed event types, comma-separated (requires --json)
--summary	Show only failures and final counts (requires --json)
--failures-only	Suppress passing test output (requires --json)
--max-output	Max output lines per test (0 = unlimited)
--report	Single JSON report with failures, counts, and rerun commands
--cover	Enable coverage analysis
--coverprofile	Write coverage profile to file
-b, --bench	Run benchmarks matching pattern
--benchtime	Benchmark duration (e.g. 5s, 1000x)
--benchmem	Report benchmark memory allocations
--history	Track test history for flaky detection
--quarantine	Quarantine flaky tests (mark as expected-fail)
--rerun-failed	Re-run only tests that failed in the previous run (requires --history)
--version	Print version

Exit Codes

Code	Meaning
0	All tests passed
1	Test failure
2	Build error
3	Connection error

JSON Protocol

See docs/protocol.md for the NDJSON event specification.

Test Discovery

See docs/discover.md for the got discover output format.

Development

just build      # build binary
just test       # run tests (excludes fixtures)
just lint       # golangci-lint (fast)
just check      # all quality gates (fmt, mod, lint, vulncheck, docs, coverage)
just audit      # check + race-enabled tests
just cover      # coverage report in browser
just run        # build + run TUI on fixtures
just discover   # build + run discover
just serve      # build + run socket server on fixtures
just install    # install to $GOPATH/bin
just fmt        # format code

Editor Plugins

• got.nvim — Neovim integration with diagnostics, gutter signs, and tree panel