Set Up and Run Go Test Coverage in GoLand

Desired Outcome

Execute Go tests with coverage collection enabled, view line-by-line coverage highlights in the editor, and inspect per-package and per-function metrics in the Coverage tool window. The configuration should persist across IDE restarts and work for both single-test and package-scope runs.

Prerequisites

• Go SDK 1.14 or newer configured in Settings → Go → GOROOT. Verify with go version in the terminal.
• A Go module project (contains go.mod) or a legacy GOPATH project with *_test.go files.
• GoLand 2023.1 or later (earlier versions lack the dedicated Coverage tool window).
• Write permission to the project directory for coverage data files (coverage.out generated by go test -coverprofile).

Create a Persistent Run/Debug Configuration

Using a saved configuration avoids re-enabling coverage on every run and lets you control scope precisely.

1. Open Run → Edit Configurations… (or press Alt+Shift+F10 then 0).
2. Click + → Go Test.
3. Name it (e.g., Test with Coverage - ./...).
4. Run kind: choose Package for a single package or Directory / File for broader scope. For whole-module coverage, select Directory and point to the module root.
5. Package path: auto-fills when you pick a directory; verify it matches the import path in go.mod.
6. Test framework: leave gotest (default).
7. Check Run with coverage — this adds -coverprofile=coverage.out to the go test invocation.
8. Optional: add -covermode=atomic in Program arguments if you have concurrent tests that race on coverage counters.
9. Click OK to save.

Run Tests with Coverage

With the configuration selected in the toolbar dropdown, press Shift+F10 (Run) or Shift+F9 (Debug). The Run tool window shows test progress; when tests finish, the Coverage tool window opens automatically.

Alternative quick runs:

• Gutter icon in a *_test.go file → Run 'TestXxx' with Coverage.
• Right-click a package in the Project view → Run 'go test' with Coverage.

Interpret the Coverage Tool Window

The Coverage tool window (View → Tool Windows → Coverage) has two tabs:

• Project — tree of packages with overall percentage. Click a package to see its files.
• Editor — line-by-line highlights in the active editor: green = covered, red = uncovered, yellow = partially covered (branch).

Toolbar actions:

• Flatten packages — toggle hierarchical vs. flat view.
• Show only covered / only uncovered — filter the tree.
• Export → HTML Report — generates a shareable coverage.html for CI artifacts.

Verify the Results

1. Open any source file exercised by tests. Confirm green/red gutter markers appear on executable lines.
2. Hover a highlighted line — tooltip shows hit count (e.g., covered 3 times).
3. In the Coverage tool window, select the root package; the status bar shows Total coverage: XX.X%.
4. Run the same configuration without the coverage checkbox (edit config, uncheck, run). The Coverage tool window should hide and gutter markers disappear, confirming the toggle works.

Troubleshooting and Recovery

Coverage tool window does not appear

• Ensure Run with coverage is checked in the active configuration.
• Check Settings → Build, Execution, Deployment → Coverage → Show coverage in editor is enabled.
• If the Go SDK path changed (e.g., after brew upgrade go), go to Settings → Go → GOROOT, click the folder icon, and select the new go binary directory. Apply and restart GoLand.

Slow test runs on large suites

Coverage instrumentation adds overhead. Mitigations:

• Narrow scope: change Run kind from Directory to Package for a single package.
• Use -coverpkg=./specific/pkg in Program arguments to limit instrumentation to targeted packages.
• Run without coverage for quick feedback loops; enable only before merge or CI.

Coverage data looks stale or missing

1. Delete coverage.out in the project root (or the directory where tests ran).
2. Invalidate caches: File → Invalidate Caches… → Invalidate and Restart.
3. Re-run the configuration.

Concurrent tests produce inconsistent counts

Add -covermode=atomic in Program arguments (see step 8 of configuration). This serializes counter updates at a small performance cost but eliminates race-induced zero counts.

Limitations

• GoLand's coverage UI reflects go test -cover output; it does not support go test -coverprofile with multiple -coverpkg entries merged into a single report — use go tool cover -html=coverage.out manually for advanced merging.
• Coverage for integration tests that spin up external processes (e.g., exec.Command) only covers the test process itself, not the child.
• Vendor directories are excluded by default; add -mod=vendor in Program arguments if you rely on vendored dependencies.

Quick Checklist

• [ ] Go SDK ≥ 1.14 configured and valid
• [ ] Run/Debug configuration saved with Run with coverage checked
• [ ] Coverage tool window opens and shows percentages after run
• [ ] Editor gutter highlights match expectations (green/red/yellow)
• [ ] Toggle off coverage → tool window hides, highlights disappear