Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Logging, Flags and Testing

Go example functions (ExampleXxx)

Concept guide to Go example functions: ExampleXxx naming, the Output and Unordered output comments, how go test verifies them, suffixes and whole-file examples.

An example function is documentation that the compiler and the test runner check. It is a function named ExampleXxx in a _test.go file, with no parameters and no results. go doc and pkg.go.dev show its body as sample code attached to the thing it names. If the function ends with an // Output: comment, go test also runs it, captures standard output, and fails when the text differs. That way examples cannot silently go out of date.

Go
func ExampleReverse() {
	fmt.Println(Reverse("stressed"))
	// Output: desserts
}

Try it

Normally go test finds examples itself. Here testing.RunExamples does what go test does with them: run each function and compare the printed text with the expected output (the part after // Output:).

Go A passing and a failing example

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 Unordered output and whitespace

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 ExampleXxx()

Naming ties an example to what it documents. The go doc tool shows it under that identifier.

Function name Documents
Example The package as a whole.
ExampleF Function F.
ExampleT Type T.
ExampleT_M Method M of type T.
ExampleF_suffix, ExampleT_M_suffix An additional example for the same item. The suffix starts with a lowercase letter (ExampleReverse_unicode).
Comment Behavior
// Output: The example runs; its stdout must equal the comment text.
// Unordered output: Same, but lines may appear in any order (maps, goroutines).
none The example is compiled but not run. Use this for code that needs a network or never ends.

Comparison ignores leading and trailing white space of the whole output, but the lines inside must match exactly. Only the last comment in the function is considered.

Usage notes

  • Examples go to stdout. Output written with fmt.Println is checked; output sent to stderr (the log package) is not.
  • Whole-file examples. A _test.go file that holds exactly one example, no tests or benchmarks, and at least one other top-level declaration is shown as a complete runnable program in the docs, including those declarations and imports.
  • Use package-qualified code in examples (package foo_test) so they read like real client code and prove the exported API is usable.
  • Keep them deterministic. No timestamps, addresses, or unsorted map iteration (use Unordered output or sort the keys).
  • Run only examples: go test -run Example, or one with go test -run ExampleReverse -v.
  • A failure prints got: and want: blocks like the first TryIt shows.
  • Not for assertions beyond output. If you need to inspect values or errors, write a normal test; examples are for documentation first.
  • Vet checks names. go vet reports an example that refers to a function or method that does not exist.