In Go, what makes go test execute a func Example() and check its output?

## What an example function is A *runnable example* is an ordinary function in a `_test.go` file whose name begins with `Example`, takes no parameters and returns nothing: ```go func ExampleCanonical() { fmt.Println(Canonical("https://example.com/p?b=2&a=1")) // Output: https://example.com/p?a=1&b=2 } ``` It serves two jobs at once. It is documentation — `go doc` and pkg.go.dev render it next to the symbol it names, so a stranger reading your package sees working code rather than prose. And it is a test — `go test` runs it and checks what it printed. ## The compile-only default Every example is compiled into the test binary regardless. That alone has value: an example that calls a function you have since renamed will not build, so the documentation cannot silently rot into something that no longer compiles. But compiling is not running. The test runner executes an example **only** when the function body ends with an output comment. The tooling takes the *last* comment block in the body and checks whether it begins with `Output:` (or `Unordered output:`). If it does, the block's text becomes the expected output. If it does not — no comment at all, or another comment placed after it — the example is registered with no expected output and is skipped. It will never fail, no matter what it does. This is the single most important fact about examples, and the reason a package can accumulate examples that all "pass" while printing nonsense. ## How the comparison works When an example does have an output comment, the runner: 1. Replaces `os.Stdout` with a pipe for the duration of the call. 2. Calls the function. 3. Reads everything the function wrote to `os.Stdout`. 4. Trims surrounding whitespace from both the captured text and the expected text, then compares them. Because only `os.Stdout` is redirected, output that goes elsewhere is invisible to the check. The standard `log` package writes to stderr by default, so `log.Println` inside an example produces noise in your terminal and contributes nothing to the comparison. `fmt.Println`, `fmt.Printf` and `os.Stdout.Write` are what count. There is no `*testing.T` in an example's signature, so there is nothing to call `t.Error` on. The printed text *is* the assertion. That constraint is deliberate: it keeps the body readable as documentation, since an example cluttered with assertions is a bad example for a reader. A panic inside an example fails the example, and its stack trace is reported the way any test panic is. ## Writing the output block Conventions that matter in practice: - Put the comment last in the body. Anything after it steals the "last comment" position. - One-line form (`// Output: 42`) and multi-line form both work: ```go func ExampleQuery_Encode() { q := Query{"a": {"1"}, "b": {"2"}} fmt.Println(q.Encode()) fmt.Println(len(q)) // Output: // a=1&b=2 // 2 } ``` - Keep the printed values deterministic. If the example prints something that varies between runs — a timestamp, an address, a randomly ordered iteration — the check will be flaky. Either make the output stable, or use the `// Unordered output:` form when only the line order varies. - Because the example is documentation first, prefer output a reader would find informative over output that is merely easy to assert on. ## Running and inspecting them `go test` runs examples along with tests. `go test -run Example -v` restricts the run to examples and prints each one it actually executed, which is how you confirm that a given example is not silently skipped. Since examples are compiled from `_test.go` files, they never ship in your package's build output. ## Why this design Go ties the test to the documentation on purpose. A prose comment describing what a function returns can drift from the code with nothing to stop it. An example that prints its result and declares that result in a comment cannot drift: the moment the behaviour changes, the package's own test suite fails. The cost of that guarantee is exactly one convention — the output comment — and the failure mode when you forget it is silence, not an error.