go test, test files and the testing package

A Go test is a function named TestXxx(t *testing.T) in a file whose name ends with _test.go, in the same package as the code it tests. The toolchain is the runner: go test compiles the package with the test files, runs the tests and reports. There is no framework to install and no assertion library to agree on, and a test that fails prints the file and line where it called t.Errorf. The sorting lesson finished Part 3; Part 4 is about proving code right.

A test file next to the code

The file sum_test.go sits in the package directory and declares the same package, so the test can call unexported functions. go test ignores every _test.go file when it builds the package for a program, so the tests cost nothing at run time. Each test starts with t, calls the function under test and compares the result with the expected one.

package mathx import "testing" func TestSum(t *testing.T) { if got := Sum(1, 2, 3); got != 6 { t.Errorf("Sum(1, 2, 3) = %d, want 6", got) } if got := Sum(); got != 0 { t.Errorf("Sum() = %d, want 0", got) } }

go test -v .

=== RUN TestSum
--- PASS: TestSum (0.00s)
PASS
ok example.com/mathx 0.009s

The output lists each test with its result and a final ok line with the time. t.Errorf records a failure and continues, so one test reports every wrong case; t.Fatalf stops the test at the first failure, which is right when the rest of the test would panic on a nil or an invalid value.

What a failure looks like

The message in t.Errorf is for the person who reads the failure at two in the morning: the call, the arguments, the result and the expectation. The runner adds the function name and the line, so the message itself does not repeat them. A failed test makes go test exit with status 1, which is what a CI job reads.

package mathx import "testing" func TestAverage(t *testing.T) { if got := Average(1, 2); got != 1.5 { t.Errorf("Average(1, 2) = %v, want 1.5", got) } if got := Average(1, 2, 4); got != 2 { t.Errorf("Average(1, 2, 4) = %v, want 2", got) } }

go test -v -run TestAverage .

=== RUN TestAverage
average_test.go:10: Average(1, 2, 4) = 2.3333333333333335, want 2
--- FAIL: TestAverage (0.00s)
FAIL
FAIL example.com/mathx 0.004s
FAIL

The second case failed because the average of 1, 2 and 4 is 2.333, not 2, and the message names the call and both numbers. A test written this way is also a description of the contract: a reader can see what the function promises without running anything.

Running one test

go test -run TestSum runs only the tests whose name matches the regular expression, which is how a developer iterates on one case in a large package. The package argument . means the current directory, ./... means this package and every package below it, and -count=1 turns off the result cache that the toolchain keeps between runs.

package mathx import "testing" func TestSum(t *testing.T) { if got := Sum(1, 2, 3); got != 6 { t.Errorf("Sum(1, 2, 3) = %d, want 6", got) } if got := Sum(); got != 0 { t.Errorf("Sum() = %d, want 0", got) } }

go test -v -count=1 -run TestSum .

=== RUN TestSum
--- PASS: TestSum (0.00s)
PASS
ok example.com/mathx 0.004s

The (cached) marker appears when the same test is run again with the same inputs and the toolchain reuses the result; -count=1 forces a fresh run, which is what a benchmark or a timing-sensitive test needs. A cache hit is a feature, not a bug: it makes the suite fast in a loop.

Skipping the slow path

testing.Short() reports the -short flag, so a test with a large input can skip itself when the suite is run quickly. t.Skip marks the test as skipped rather than passed, which keeps the report honest. The same mechanism gates tests that need a network, a database or a file the repository does not carry.

package mathx import "testing" func TestSumLarge(t *testing.T) { if testing.Short() { t.Skip("skipping the large input in short mode") } if got := Sum(1000, 2000, 3000); got != 6000 { t.Errorf("Sum(1000, 2000, 3000) = %d, want 6000", got) } }

go test -v -short .

=== RUN TestSumLarge
slow_test.go:7: skipping the large input in short mode
--- SKIP: TestSumLarge (0.00s)
PASS
ok example.com/mathx 0.004s

The skipped test printed its reason and the package still ended with ok. A skipped test that hides a real failure is worse than no test, so the reason string should say what was skipped and why, and a CI job should run the full suite at least once.

Exercises

  1. Write a test for Average with no arguments and make it pass. What should the function return, and does the test or the code decide?
  2. Change a t.Errorf to t.Fatalf in a test with three cases and compare the output. When is the stop worth losing the other messages?
  3. Add a test that skips unless an environment variable is set, and run the package with and without it. What does the summary line report in each case?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What must a test file be named?

    Answer

    Something ending in _test.go, in the package directory

    The suffix is what tells the toolchain to build the file only for tests.

  2. What is the signature of a test function?

    Answer

    func TestXxx(t *testing.T)

    The name starts with Test and the parameter is a *testing.T.

  3. What is the difference between t.Errorf and t.Fatalf?

    Answer

    Errorf records the failure and continues, Fatalf stops the test

    A test that would panic after a wrong value needs Fatalf.

  4. What does go test -run TestSum do?

    Answer

    Runs the tests whose name matches the expression

    -run filters by name with a regular expression.

  5. What does testing.Short() report?

    Answer

    Whether the -short flag was passed

    It is how a test skips an expensive path in a quick run.

  6. What does a failed test make go test return?

    Answer

    Exit status 1

    The non-zero status is what a CI job checks.

  7. Why can a test call an unexported function?

    Answer

    It is compiled in the same package

    Same package, same visibility; an external test package uses the exported API only.

  8. What does the (cached) marker mean in go test output?

    Answer

    The same test ran before with the same inputs and the result was reused

    The cache makes repeated runs fast; -count=1 forces a new run.

  9. What does t.Skip do?

    Answer

    Marks the test skipped and records the reason

    A skip is reported as a skip, not as a pass or a failure.

  10. Where does the test file live?

    Answer

    In the same directory as the package it tests

    The package directory is the unit of building and testing in Go.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev