Skip and Short Mode Patterns in Go Tests Done Right

A skipped test is a test that decided it should not run in this environment. Go has two ways to say so, t.Skip and the -short flag, and both are simple. The details that matter are the reason you give, who notices, and which tests you skip.

package main

func main() {}

package main

import (
	"os"
	"testing"
	"time"
)

func TestFast(t *testing.T) {}

func TestSlowSkippedInShort(t *testing.T) {
	if testing.Short() {
		t.Skip("skipping in -short mode")
	}
	time.Sleep(200 * time.Millisecond)
}

func TestNeedsEnv(t *testing.T) {
	if os.Getenv("CI_ONLY") == "" {
		t.Skip("set CI_ONLY=1 to run")
	}
}

func TestSkipNowStopsTheTest(t *testing.T) {
	t.Skipf("skipped with %s", "a formatted reason")
	t.Fatal("never reached")
}

G='s/ \([0-9.]+s\)//; s#^ +[a-z_]+\.go:[0-9]+: #    #; s/\t[0-9.]+s$//'
echo "# go test -v"; go test -count=1 -v . | grep -vE '^(=== RUN|PASS)' | sed -E "$G"
echo; echo "# go test -short -v"; go test -count=1 -short -v . | grep -E '^--- SKIP: TestSlow' | sed -E "$G"
echo; echo "# go test -json: skip is its own action"; go test -count=1 -json . | grep -c '"Action":"skip"'

# go test -v
--- PASS: TestFast
--- PASS: TestSlowSkippedInShort
    set CI_ONLY=1 to run
--- SKIP: TestNeedsEnv
    skipped with a formatted reason
--- SKIP: TestSkipNowStopsTheTest
ok  	example.test/lab

# go test -short -v
--- SKIP: TestSlowSkippedInShort

# go test -json: skip is its own action
2

t.Skip and t.Skipf

t.Skip("reason") marks the test skipped and stops it by calling runtime.Goexit, like t.FailNow does for failures, so the code after it never runs. TestSkipNowStopsTheTest proves the point: the t.Fatal on the next line was not reached, and the test did not fail. The reason appears in the verbose output next to --- SKIP. t.Skipf takes a format string. With -v, a skipped test prints its reason; without it, skips are silent and the summary just says ok.

Skip for conditions the test cannot control: a missing environment variable, an operating system without the feature, a service that is not running. Do not skip to hide a failure. A test skipped "for now" with no issue number is a deleted test with better manners.

testing.Short()

go test -short sets a flag that testing.Short() reports. A slow test checks it first and skips: if testing.Short() { t.Skip("skipping in -short mode") }. The recorded run shows TestSlowSkippedInShort skipping under -short, and running through its 200 ms wait without it. Nothing skips unless a test asks, so the convention only works if the expensive tests remember. Pair it with -timeout and use it for local development: go test -short ./... runs the fast majority on every save, and the full run goes to CI.

Skip, do not return

A test that returns early with if os.Getenv("X") == "" { return } reports a pass. Nobody can tell from the output that it did nothing, and the green mark counts toward any metric of how many tests pass. t.Skip reports the same situation honestly. The same applies to a test that wraps its body in an if: restructure it to skip at the top. Reviewers should treat an early return in a test as a bug. Also consider t.Skip in a helper: it stops the calling test, as t.Fatal does, but the skip message then points at the helper's line, so pass the reason in clearly.

Make skips visible

Skips are silent by default, and a CI job full of them reports success. go test -json emits a skip action for each, and the lab counted two. A one-line step can count skips and fail if the number differs from what you expect, or if an integration-tagged test skipped when the environment was supposed to provide its dependency. The build tag article shows the REQUIRE_INTEGRATION approach, and the JSON note has the event format. The skip methods are in the testing package reference.