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.
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:).
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 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.Printlnis checked; output sent to stderr (thelogpackage) is not. - Whole-file examples. A
_test.gofile 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 outputor sort the keys). - Run only examples:
go test -run Example, or one withgo test -run ExampleReverse -v. - A failure prints
got:andwant: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 vetreports an example that refers to a function or method that does not exist.
Related
- testing, testing.T
- fmt.Println()
- Tutorial: Documentation and Testing