go test -run TestName: run a single Go test

go test -run '^TestName$' ./path/to/pkg runs only the test functions whose name matches the regular expression after -run. The ^ and $ anchors make it an exact match; without them -run TestName also runs TestNameSomething. Add -v to see each test's name and result, and -count=1 to bypass the test cache.

Examples

# one test in the package of the current directory
go test -run '^TestParseConfig$' -v .

# one test in another package, without cached results
go test -run '^TestParseConfig$' -count=1 ./internal/config

# one subtest: parent and child patterns separated by a slash
go test -run '^TestParse$/^empty_input$' -v ./...

# all tests whose name starts with TestHTTP, skipping the slow ones (Go 1.20+)
go test -run '^TestHTTP' -skip 'Slow' ./...

Quote the pattern in the shell: $ and | would otherwise be interpreted by bash, and ^ has a meaning in cmd.exe.

How the pattern is matched

The documentation describes -run regexp as running only those tests, examples and fuzz tests matching the regular expression. For subtests, the regexp is split at unbracketed slashes into a sequence, and each part must match the corresponding element of the subtest name. Subtest names are the string passed to t.Run, with spaces replaced by underscores. Parents of matching subtests run too: -run X/Y runs every test matching X, even those without a Y subtest, because the parent must run to find its subtests.

Pitfalls

• "testing: warning: no tests to run". The pattern matched nothing in that package: check spelling and case (test names are case-sensitive), and that you passed the right package path. The package still reports ok.
• Test file rules. A test must be in a file ending in _test.go, in a function named TestXxx(t *testing.T) where Xxx does not start with a lowercase letter; otherwise go test does not see it.
• Compilation first. go test compiles the whole package, including the tests you are not running, so an error such as declared and not used in any file stops the run.
• Benchmarks and fuzz tests use -bench and -fuzz; -run alone never runs benchmarks.
• Running from an editor. IDE "run test" buttons call exactly this command with an anchored pattern, so copying it from the editor's output is a quick way to reproduce a failure in a terminal.

Confirm it worked

With -v, the output lists === RUN TestName and --- PASS: TestName lines only for the tests you selected, followed by ok and the package path. : how the regular expression matches tests and subtests, -skip, -count=1 to bypass the cache, and common mistakes." type: commands tool: go tags: [go, testing, go-test, run, subtests] versions: ["Go 1.7+ (subtests)", "-skip: Go 1.20+"] os: [any] status: draft sources:

• https://pkg.go.dev/cmd/go#hdr-Testing_flags
• https://pkg.go.dev/testing
• https://go.dev/doc/tutorial/add-a-test related:
• commands/go/go-mod-tidy
• commands/go/go-build-cross-compile
• errors/go/declared-and-not-used updated: "2026-10-23" faq:
• q: "Why does go test -run TestLogin also run TestLoginFailure?" a: "The value of -run is a regular expression matched anywhere in the test name, not an exact name. Anchor it with ^ and $, as in -run '^TestLogin$', to run only that test."
• q: "Why does go test print (cached) and not run my test?" a: "go test caches results of successful runs in package list mode when nothing relevant changed. Add -count=1 to force the tests to run again."
• q: "How do I run one test in every package?" a: "Combine the pattern with ./...: go test -run '^TestParse$' ./... runs TestParse in each package that has one and reports no tests to run for the others."

go test -run '^TestName$' ./path/to/pkg runs only the test functions whose name matches the regular expression after -run. The ^ and $ anchors make it an exact match; without them -run TestName also runs TestNameSomething. Add -v to see each test's name and result, and -count=1 to bypass the test cache.

Examples

# one test in the package of the current directory
go test -run '^TestParseConfig$' -v .

# one test in another package, without cached results
go test -run '^TestParseConfig$' -count=1 ./internal/config

# one subtest: parent and child patterns separated by a slash
go test -run '^TestParse$/^empty_input$' -v ./...

# all tests whose name starts with TestHTTP, skipping the slow ones (Go 1.20+)
go test -run '^TestHTTP' -skip 'Slow' ./...

Quote the pattern in the shell: $ and | would otherwise be interpreted by bash, and ^ has a meaning in cmd.exe.

How the pattern is matched

The documentation describes -run regexp as running only those tests, examples and fuzz tests matching the regular expression. For subtests, the regexp is split at unbracketed slashes into a sequence, and each part must match the corresponding element of the subtest name. Subtest names are the string passed to t.Run, with spaces replaced by underscores. Parents of matching subtests run too: -run X/Y runs every test matching X, even those without a Y subtest, because the parent must run to find its subtests.

Pitfalls

• "testing: warning: no tests to run". The pattern matched nothing in that package: check spelling and case (test names are case-sensitive), and that you passed the right package path. The package still reports ok.
• Test file rules. A test must be in a file ending in _test.go, in a function named TestXxx(t *testing.T) where Xxx does not start with a lowercase letter; otherwise go test does not see it.
• Compilation first. go test compiles the whole package, including the tests you are not running, so an error such as declared and not used in any file stops the run.
• Benchmarks and fuzz tests use -bench and -fuzz; -run alone never runs benchmarks.
• Running from an editor. IDE "run test" buttons call exactly this command with an anchored pattern, so copying it from the editor's output is a quick way to reproduce a failure in a terminal.

Confirm it worked

With -v, the output lists === RUN TestName and --- PASS: TestName lines only for the tests you selected, followed by ok and the package path.

FAQ