On this page
The short answerStart with the reader's promiseWrite an example functionChoose the right example nameCompare ordered and unordered outputRun the package checks deliberatelyCheck README and Markdown snippets separatelyPin the version the page describesPut checks into CI and release workReview output and reader contextHow DocsAlive fitsFAQThe short answer
Use Go example functions to keep examples close to the package they demonstrate. Put them in _test.go files, give them the Example names described below, and run go test. A concluding // Output: comment makes the example run and compares standard output; // Unordered output: allows the lines in any order. An example without an output comment is compiled but not executed. That distinction matters when a green test run is used as evidence for a release.
README and Markdown fences need their own coverage. Extract complete examples into a temporary module, choose the module versions readers should use, and run go vet and go build. Add execution and assertions when the page promises behavior or output. Test in a clean environment, record what was supplied by the harness, and run the checks in CI. The README testing guide covers the surrounding installation journey; the release checklist helps turn the result into a decision.
DocsAlive recognizes compiled-language examples, including Go, but does not execute them yet. Use Go's own tooling or a separate harness for the Go checks in this guide.
Start with the reader's promise
Inventory where Go code appears: package examples, a repository README, quickstarts, reference pages, migration notes and generated pages. Record the published page and source location, the package version the reader is expected to use, and whether the block is a complete program, a fragment, or output. A package example can be correct while the README still shows an old import or omits a prerequisite.
For each example, decide what a pass should mean. Compilation can detect a missing import or an incompatible call; it cannot establish that the program produces the result the prose promises. Execution without an assertion establishes that the program ran, but may miss a wrong value. A comparison with an expected result checks a narrower, named behavior. Keep these levels separate in reports and release reviews.
Start with installation and the first useful result. Then include examples for the public APIs most likely to change, and any alternatives your documentation presents as supported. If a page has several tabs, record which alternatives are checked. A green result for one path does not prove that every tab or platform works. List intentionally incomplete fragments and give them an owner instead of silently counting them as tested.
Write an example function
The Go testing package documentation describes examples as functions that can run and verify example code. Put a small example in a _test.go file alongside the package. For example, this standalone package illustrates output checking:
package greeting
import "fmt"
func Example() {
fmt.Println("hello")
// Output: hello
}
Run go test in the package directory. The concluding line comment beginning with Output: supplies the expected standard output. The testing package compares it with what the function prints, ignoring leading and trailing space. A multiline expectation can put // Output: on its own line and continue with comment lines. Keep the expected text readable: it is part of the example a maintainer must understand.
Use representative values whose result is stable. If the example documents a public function, call that function and show the behavior a reader should expect rather than merely printing a hard-coded answer. If behavior changes, investigate whether the implementation or the documented promise should change before updating expected output. A test that simply accepts a new result can hide a regression.
An example is also documentation. Keep required imports and setup understandable, choose names that explain the task, and avoid depending on a developer's private files or credentials. If a setup helper supplies state a reader cannot see, record that limitation and test the reader-facing instructions separately. Code that passes in a test harness can still be difficult to copy into a real program.
Choose the right example name
The testing package documents these forms for a package, a function F, a type T, and a method M on T:
func Example() { /* package example */ }
func ExampleF() { /* function F */ }
func ExampleT() { /* type T */ }
func ExampleT_M() { /* method M on T */ }
Several examples may be associated with the same package, function, type or method by appending distinct suffixes. The suffix starts with a lowercase letter: Example_suffix, ExampleF_suffix, ExampleT_suffix, and ExampleT_M_suffix are the forms described in the testing documentation. Choose a suffix that tells readers why the variant exists, such as an alternative input or an error path. Review names when an API is renamed so that examples remain associated with the intended subject.
The testing package also describes when the entire test file is presented as the example: it contains a single example function, at least one other function, type, variable or constant declaration, and no test or benchmark functions. This can be useful when a small supporting declaration is needed to understand a complete example. Check what readers actually see; the presentation and the code's test result answer different questions.
Compare ordered and unordered output
Use // Output: when the order of printed lines is part of the promise. For output where line order is genuinely irrelevant, // Unordered output: matches the lines in any order. That is useful only when readers should accept those lines in any order. It should not be used to conceal a changed value or to weaken an ordering guarantee the page makes.
The comparison described by the testing package concerns standard output. If an example promises a file, a return value, a state change or an error, decide how that behavior will be checked too. A successful output comparison is evidence for the displayed text, not a complete review of all effects. Keep variable values out of an exact output contract unless their exact form is actually significant.
| Example | Useful evidence | What remains open |
|---|---|---|
| Stable printed result | // Output: comparison |
Other side effects and reader setup |
| Same lines in any order | // Unordered output: comparison |
Whether order matters to the reader |
| No output comment | Successful compilation | Runtime behavior and result |
| Markdown program | Build, then execution and assertions as needed | Other pages and variants |
| Intentional fragment | Explicit harness or review | Independent copy-and-paste use |
Examples without output comments are compiled but not executed. This makes them useful for checking that a displayed API call still compiles, but a runtime failure or wrong result can remain undetected. Mark them as compile-only in the coverage inventory. If the example makes a behavioral promise, add a suitable output expectation or a separate test that asserts that promise. Do not infer execution merely because go test returned successfully.
Run the package checks deliberately
Run go test from each relevant package context and keep the command and its result with the documentation revision. Decide whether your CI selection covers all packages containing examples; a command aimed at one package does not establish coverage of another. Inspect failures and the selected scope, not just the final status indicator. Keep compile-only examples separate from examples with output comparisons in the release record.
Run checks in an environment that resembles the supported reader setup. Record the Go toolchain, operating system, package revision and dependency versions used. A developer's machine can contain local configuration or files that make an incomplete example appear to work. A clean environment helps reveal hidden assumptions, but it is still one environment: record platforms and versions left untested.
Keep examples deterministic where possible. Use controlled inputs and temporary resources rather than personal directories or production services. If a live dependency is essential, use an authorized test environment and make the remaining dependency clear in the report. A passing run with a local fixture shows behavior against that fixture; it does not establish availability of a remote service.
Check README and Markdown snippets separately
An example function and a Markdown fence are different sources. Running package tests does not automatically prove that a code block in a README was found, copied correctly or built. Locate the Markdown or generated source that produces the published page. Use a format-aware extraction process that retains the page and line location; fences, tabs, includes and output blocks should not be treated as interchangeable code.
Classify blocks before building them. A complete program needs its package declaration, imports and entry point; a fragment might assume preceding setup. A sequence of blocks may build on earlier steps, while tabs may be alternatives. Preserve the reader's order for a sequence and test alternatives independently. Do not combine every Go fence into one file: doing so can hide a missing import or produce a program no reader was asked to create.
For a complete program, write the extracted code to a fresh temporary directory and initialize a temporary module. Resolve the intended dependency versions explicitly, then run go vet and go build there. The exact module path and dependencies depend on your project; document them in the harness and do not substitute a local checkout without recording it. A practical outline is:
mkdir -p /tmp/docs-go-example
cd /tmp/docs-go-example
go mod init docscheck.local/docs-check
# Write the extracted complete example to main.go and select its dependencies.
go vet ./...
go build ./...
This outline assumes a fresh directory and a complete main.go; it is not an extractor or a version-selection script. Use a unique disposable directory for each independent example or reader journey. Capture the extraction source, commands, module files, toolchain and output so someone can reproduce a failure. Remove temporary resources after the run according to your environment's cleanup policy.
A build checks compilation, while vet provides an additional check; neither alone verifies the example's output or its side effects. Where the documentation promises a result, run the built program in a suitable isolated environment and compare the meaningful result. Where a block is deliberately incomplete, either test it inside a visible harness or mark it for review. Say exactly what the harness added: an added import, declaration or value can make a fragment compile while the displayed block remains incomplete.
Pin the version the page describes
A migration page may describe an older release while the default quickstart describes the current one. Record the intended module version for each example and select it in the temporary module. Keep the dependency choices and the version under test with the result. A single pass against a local checkout cannot establish compatibility with every released version or with the package a reader obtains.
For release work, test the candidate intended for publication and distinguish that result from a later check of the published version. If the candidate requires a special source or local substitution, record it. Then repeat the important reader path against the published version when it is available. This can expose a difference between the candidate environment and the public installation path; it cannot retroactively block a release.
Pinning makes a result reproducible, but it can also hide a change in a dependency readers receive under a broader policy. Decide whether to run a separate supported-range or current-dependency check and label that result separately. Record the resolved versions on failure. Avoid treating a changing dependency resolution as proof that the documentation changed: first establish which input changed and whether the resulting combination is supported.
Put checks into CI and release work
Run focused checks when examples, public APIs or their dependencies change. Run the agreed release selection against the candidate before publishing, with enough time to investigate failures. Schedule a separate check for relevant external changes if that is part of your maintenance plan. The GitHub Actions guide describes how pull request and scheduled checks answer different questions.
A useful report identifies the documentation revision, source location, target version, command, environment, expected result and actual result. It also lists skipped blocks, compile-only examples, unselected tabs and manual checks. Retain failure output so an owner can distinguish a broken example from a setup or infrastructure problem. A retry can provide more evidence, but it should not erase an intermittent failure from the record.
Agree on a release policy before a failure occurs. A complete onboarding example that cannot build against the intended candidate may warrant blocking the release. A deliberately incomplete illustration may need a documentation fix or a clearly recorded exception instead. Name the decision maker, the affected readers, the reason for any exception and a follow-up owner. Review exceptions at the next release rather than allowing temporary gaps to become invisible.
Review output and reader context
Test the steps in the order readers encounter them, including installation and configuration where those steps are part of the page. A working code block does not prove that a link to it is correct, that the install command names the right version, or that the prose explains its prerequisites. Read the rendered page as well as the source, especially where includes or generated content affect what readers see.
Look for side effects and cleanup. An example that creates a file should identify where it goes; one that changes remote state should use an appropriate disposable target. Record what the harness supplies that the reader must supply themselves. Do not put real credentials in examples or logs. For interactive, graphical, destructive or long-running steps, define separate safe coverage and identify the remaining manual work.
When a check fails, preserve the smallest reproduction and route it to the owner of the relevant API and page. Ask whether the example is wrong, the product behavior changed, or the test environment is unavailable. A documentation edit may be right for an intentional API change; a product fix may be needed when the example expresses a supported contract. The decision needs both technical and documentation context.
How DocsAlive fits
DocsAlive extracts supported fenced examples and runs or checks them in page order, with a fresh container for each page. It selects one variant from each tab group. The framework reference describes coverage for Python, JavaScript on Node 20, simple TypeScript, shell and curl or HTTP examples. Go and other compiled-language examples are recognized but not executed yet. Use the separate Go checks above; a DocsAlive scan is not evidence that a Go example ran or compiled.
Credential-dependent examples are classified rather than executed with real keys. Review report.md and report.json using the findings reference, including skips and unselected variants. A pass can represent execution or a syntax check, so read the category rather than assuming every block ran. A person still needs to review the explanation, Go coverage and reader journey.
See pricing: the Open source plan is $0/month for public OSI-licensed projects, Team is $299 per month, Growth is $699 per month, and Scale starts at $1,499 per month. Contact us to discuss coverage or request a free health check.
FAQ
Does every example function run?
No. The testing package compiles examples without output comments but does not execute them. Use an output comment or a separate behavioral test when execution is needed.
Does go test cover my README?
Do not assume it does. Inventory the Markdown blocks and extract and check the intended examples separately, preserving their context and target versions.
When should I use unordered output?
Use it when the same output lines are valid in any order. Keep an ordered expectation when order is part of the documented behavior.
Can DocsAlive execute my Go examples?
DocsAlive recognizes compiled-language examples, including Go, but does not execute them yet. Run Go-specific checks separately and include their results in your release review.
For the comparable compiled-language boundary in Rust, see testing Rust documentation examples; for Java, see testing Java documentation examples, and for PHP, testing PHP documentation examples.
