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).
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.
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.
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
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
Fatalmust 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 callFatalfrom 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.Helperis per function: mark every function in a chain of assertion helpers that you want skipped in the reported line.- Do not use
tafter 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, notfmt.Println, so it stays attached to the right test, especially when tests run in parallel. SetenvandChdircannot be used in parallel tests because they change process-wide state.- Newer additions.
t.Attr(key, value)andt.Output()arrived in Go 1.25 for structured test metadata and writing to the test's log stream.
Related
- testing, testing.B
- defer and panic()
- Tutorial: Table-driven tests and Testing concurrent code