Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Logging, Flags and Testing

Go testing.T type

Reference for Go testing.T: Error versus Fatal, Log, Skip, Run subtests, Helper, Cleanup, TempDir, Setenv, Parallel and Context, with runnable test output.

*testing.T is the object that go test passes to every function named TestXxx. You use it to report failures, write log lines, skip tests, run subtests and register cleanup. A test passes if it returns without being marked failed.

The most important distinction is between methods that mark the test as failed and keep going (Error, Errorf, Fail) and those that fail and stop the test at once (Fatal, Fatalf, FailNow).

Go
func TestDivide(t *testing.T) {
	got, err := Divide(6, 3)
	if err != nil {
		t.Fatalf("unexpected error: %v", err) // no point continuing
	}
	if got != 2 {
		t.Errorf("Divide(6, 3) = %d, want 2", got)
	}
}

Try it

These examples launch the real test runner with testing.Main so you can see genuine -v output. Both finish with FAIL on purpose, so you can read a failing report: the first has a wrong expectation, the second calls Fatal in a subtest.

Go Error, Run and Skip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Helper, Cleanup, Fatal and TempDir

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func (c *T) Error(args ...any)
func (c *T) Errorf(format string, args ...any)
func (c *T) Fatal(args ...any)
func (c *T) Fatalf(format string, args ...any)
func (c *T) Log(args ...any)
func (c *T) Logf(format string, args ...any)
func (c *T) Fail()
func (c *T) FailNow()
func (c *T) Failed() bool
func (c *T) Skip(args ...any)       // also Skipf, SkipNow, Skipped
func (c *T) Helper()
func (c *T) Cleanup(f func())
func (c *T) TempDir() string
func (c *T) Setenv(key, value string)
func (c *T) Name() string
func (t *T) Run(name string, f func(t *T)) bool
func (t *T) Parallel()
func (t *T) Deadline() (time.Time, bool)
func (c *T) Context() context.Context // Go 1.24
func (c *T) Chdir(dir string)         // Go 1.24
Method Description
Error, Errorf Log the message and mark the test failed. Execution continues.
Fatal, Fatalf Log, mark failed and stop the current test via runtime.Goexit. Deferred calls and cleanups still run.
Log, Logf Record output shown on failure or with -v. Lines include the file and line number.
Skip* Mark skipped and stop. A skipped test is not a failure.
Run(name, f) Runs f as a subtest and waits for it. Returns false if it failed. Names with spaces become underscores.
Cleanup(f) Runs f after the test and its subtests finish, last registered first.
Context() A context cancelled just before cleanups run (Go 1.24).

Usage notes

  • Fatal must run in the test goroutine. Calling it from a goroutine you started does not stop the test properly; send the error over a channel and call Fatal from the test.
  • Subtests give names and isolation. Run one with -run 'TestSlugify/simple'. A failing subtest marks its parents failed too.
  • t.Parallel() inside a subtest makes it wait until the parent function returns, then run concurrently with its siblings.
  • Helper is per function: mark every function in a chain of assertion helpers that you want skipped in the reported line.
  • Do not use t after the test ends, for example from a background goroutine. It panics with "Log in goroutine after Test... has completed".
  • Test output goes through t.Log, not fmt.Println, so it stays attached to the right test, especially when tests run in parallel.
  • Setenv and Chdir cannot be used in parallel tests because they change process-wide state.
  • Newer additions. t.Attr(key, value) and t.Output() arrived in Go 1.25 for structured test metadata and writing to the test's log stream.