Go - Test Suites

Specification-driven test suites for Go.

gotest generates standard go test code from struct-based suites — BDD organization, lifecycle hooks, and structured output. No reflection, no runtime deps. This extension brings that into VS Code: run, debug, watch, and verify your suites without leaving the editor.

Why this extension?

Test Explorer shows your suites as Package > Suite > Method > Subtest — not a flat list of functions. Run or debug at any level. Coverage gutters track implementation progress. Watch mode streams results as you code.

The Spec View renders your test structure as a behavioral specification — a readable tree with pass/fail indicators, go-to-source navigation, and clipboard export. Your tests become documentation that's always in sync.

AI-assisted workflows — Paste specs into AI conversations as context. The clean exports feed well into LLM toolchains. You define what the system should do — the tests verify.

• Spec View — Your quality dashboard. BDD-formatted specification tree with pass/fail/skip indicators, go-to-source navigation, and structured clipboard export.
• Suite-aware Test Explorer — Navigate tests as Package > Suite > Method > Subtest, not a flat list of functions.
• Coverage gutters — Track implementation progress with native VS Code coverage integration, per-statement highlighting, and persistent results across sessions.
• One-click Run and Debug — CodeLens buttons above every suite and method. Debug with Delve, breakpoints included.
• Watch mode — Continuous verification on file changes with streaming results and a status bar indicator.
• Focus/Exclude management — Toggle F_/X_ prefixes via Quick Fix actions. Diagnostic warnings prevent focused tests from reaching CI.
• Scaffold generation — Generate test suite skeletons from types and files via code actions or the command palette.

Getting started

Prerequisites

• Go (1.25+)
• VS Code (1.123+)
• Delve (for debugging only)

The extension invokes the gotest CLI automatically — no separate install needed. It resolves the version from your go.mod and uses go run to execute it.

Install

Search "gotest" in the Extensions panel, or install from the command line:

code --install-extension mvrahden.gotest

Also available on Open VSX for VS Code forks.

First run

1. Open a Go project that uses gotest suites.
2. The extension discovers test suites automatically on activation.
3. Open the Testing sidebar to see your suites organized by package.
4. Click the Run or Debug button next to any suite or method.

Features

Test Explorer

Tests appear in a structured tree: Package > Suite > Method > Subtest. Run or debug at any level — a single method, an entire suite, or all tests in a package. Multi-select is fully supported. Test results persist across sessions, so you see pass/fail state immediately after reopening the editor. The tree itself is restored from disk on startup, so suites are browsable straight away instead of waiting for the Go toolchain to finish discovery.

CodeLens

Run and Debug buttons appear inline above every suite and test method in _test.go files. Click to execute immediately.

Package-level and file-level actions appear on the package declaration line:

• Run Package — run all suites in the package
• Run File — run all suites defined in the current file (shown when the file contains multiple suites)

Coverage

Use the Coverage run profile in Test Explorer to run tests with go test -coverprofile. Results appear as native VS Code coverage gutters. Coverage data persists across sessions and accumulates across packages. Source file edits automatically invalidate stale coverage for the affected package.

Copy a tabular coverage summary to the clipboard via the Go Test: Copy Coverage Summary command.

Watch mode

Start continuous testing with Go Test: Start Watch. The extension spawns a gotest watch process that re-runs tests on file changes. Results stream into Test Explorer in real-time. A status bar item shows active watcher count and lets you stop all watchers with a click.

Spec View

After each test run, the Spec View panel renders BDD-formatted output with color-coded pass/fail/skip indicators. Open it with Go Test: Show Spec View.

• Go-to-source — click any suite or method to navigate to its definition
• Toolbar — expand/collapse all, filter by pass/fail/skip status, search behaviors by name
• Copy / Clear — copy the full spec report to clipboard or clear results
• Persistence — the panel survives editor reload and restores its last state
• Live updates — auto-refreshes from test runs, coverage runs, and watch mode

Focus and Exclude

Place your cursor on a suite or method definition and use the Quick Fix menu (Ctrl+. / Cmd+.) to:

• Focus a test (F_ prefix) — only focused tests run
• Exclude a test (X_ prefix) — test is skipped
• Unfocus / Include — remove the prefix

A status bar warning and inline diagnostics alert you when focused tests exist, preventing CI failures from gotest --ci.

Scaffold

Generate test suite skeletons from existing code:

• Code action on a type declaration — "Generate test suite for TypeName"
• Code action on any Go file — "Generate test suite for this file"
• Command palette — "Go Test: Scaffold Suite" for manual target entry

The generated file opens automatically and discovery refreshes.

Multi-root workspaces

Fully supported. Each workspace folder is discovered independently. Commands resolve the correct workspace folder from the active editor, and file watchers trigger per-folder discovery. Per-project settings like cliPath, testFlags, and buildTags can be configured per folder via .vscode/settings.json. Projects using go.work are also supported.

Commands

Settings

Per-project settings (resource scope)

These can be set in .vscode/settings.json per workspace folder:

Global settings (window scope)

Example .vscode/settings.json

{
  // Use a local gotest binary instead of go run
  "gotest.cliPath": "./bin/gotest",

  // Pass build tags to discovery and test runs
  "gotest.buildTags": "integration,e2e",

  // Extra flags for go test (e.g. timeout, verbose)
  "gotest.testFlags": ["-timeout=120s", "-v"],

  // Control parallelism:
  //   --parallel=N  total concurrent tests across all suites (gotest flag)
  //   -parallel=N   concurrent tests within each suite (go test flag)
  // "gotest.testFlags": ["--parallel=12", "-parallel=4"],

  // Extra build flags for Delve debug sessions
  "gotest.buildFlags": ["-gcflags=all=-N -l"]
}

Gotest CLI resolution

The extension resolves the gotest CLI in this order:

1. gotest.cliPath — Explicit path to a binary. Highest priority; version-validated against the minimum required version.
2. Workspace is gotest module — If the workspace's go.mod declares the gotest module itself (development or go.work overlap), uses go run ./cmd/gotest.
3. go.mod + replace directive — If go.mod has a replace directive for the gotest module, uses go run modulePath (no version, respects replace resolution).
4. go.mod pinned version — If go.mod references the gotest module, uses go run modulePath@version with the pinned version.
5. go run @latest — Fallback when none of the above apply.

Go binary resolution

The extension resolves the Go toolchain per workspace folder:

1. go.mod go directive — If go.mod declares go 1.26.2, the extension looks for ~/sdk/go1.26.2/bin/go or go1.26.2 on PATH.
2. GOROOT — $GOROOT/bin/go if set.
3. Login shell — Runs bash -lc 'command -v go' to find Go on the user's full PATH.
4. Common paths — /usr/local/go/bin/go, ~/go/bin/go, /usr/bin/go, ~/sdk/go*/bin/go.

Requirements

• VS Code 1.123 or later
• Go 1.25 or later
• A Go project using gotest suites
• Delve for debug support

License

MIT