How uber-go/goleak works
Project type and purpose
• This is a Go library (“goleak”) designed to detect leaked goroutines in Go test suites. It is not a client-server app but a developer tool/library that hooks into testing and the Go runtime to capture and analyze active goroutines at test boundaries.
File structure
• Top-level files:
• leaks.go / leaks_test.go: core public API (VerifyNone, VerifyTestMain) and high-level leak-detection logic
• options.go / options_test.go: configuration/options parsing and defaults
• utils_test.go / signal_test.go: miscellaneous helpers and behavior tests
• internal/stack:
• scan.go / scan_test.go and stacks.go / stacks_test.go: the stack–capture and parsing engine, which invokes runtime.Stack, splits it into per-goroutine traces, and applies filters
• testdata/: example stack traces for unit tests
• CI and quality:
• .github/workflows: CI pipelines
• .golangci.yml: linting rules
• Makefile: build/coverage/test targets
README for additional insights
• Public API: VerifyNone(t *testing.T) and VerifyTestMain(m *testing.M)—these are the primary integration points
• Warning about t.Parallel() and best practices for leak testing
• No external services or databases—pure in-process library
a. Main components
1. Public API Layer (leaks.go, options.go)
2. Test Integration Layer (testmain.go)
3. Stack Scanning Engine (internal/stack: scan.go, stacks.go)
4. Configuration/Options Module (options.go)
5. Runtime Interface (Go runtime’s runtime.Stack, testing package)
b. Relationships & data flow
• A test calls VerifyNone or a TestMain calls VerifyTestMain
↓
• API Layer collects configuration and defers leak check to the Stack Scanning Engine
↓
• Scanning Engine calls runtime.Stack to retrieve raw stack traces
↓
• Stacks module parses the raw data into structured goroutine objects, applies filters (e.g., known runtime goroutines)
↓
• Results are returned to API Layer, which reports test failure if leaks are detected
c. Architectural patterns & principles
• Layered architecture: API → integration → engine → runtime
• Encapsulation: internal/stack is hidden from public API
• Dependency on Go’s testing framework and runtime only—no external dependencies
• Extensibility: options pattern allows users to adjust filtering or ignore lists
d. Key technologies & libraries
• Go runtime: runtime.Stack, goroutine internals
• Go testing: testing.T, testing.M, TestMain
• Go modules: go.mod, go.sum
• CI: GitHub Actions, golangci-lint