Go 示例测试未执行的常见原因及正确写法

go 的示例函数（examplexxx）必须包含以 // output: 开头的输出注释，否则虽能编译但不会被执行；这是 go test 识别并运行示例的必要条件。

在 Go 中，示例（Example）是一种特殊的测试形式，主要用于文档演示和轻量级功能验证。它与普通测试函数（TestXXX）不同：示例函数本身不会自动运行，除非满足两个关键条件：

1. 函数名符合命名规范：以 Example 开头，可选后缀（如 Example, ExamplePoke, ExampleCow_Poke）；
2. 必须包含 // Output: 注释行：该注释需位于函数体末尾（或紧随代码之后），且其后的内容将作为预期输出——go test 会实际执行函数，并比对标准输出是否与 // Output: 后的文本完全一致（含空行、换行符）。

例如，修正后的 example_test.go 应如下所示：

package cow_test  import (     "gist.github.com/85469ecc65bb5bb85857" // 注意：此为示意路径，实际应使用合法模块路径 )  func Example() {     cow.Poke()     // Output: MOOOO! }

⚠️ 注意事项：

• // Output: 必须独占一行，且不能有前置空格（即顶格书写）；
• 输出内容需与 Poke() 实际打印内容逐字节匹配（包括末尾换行）；若函数输出 “MOOOO!n”，则注释必须写 // Output: MOOOO!（Go 自动忽略末尾换行，但中间换行需显式写出）；
• 示例文件必须属于 _test 包（如 cow_test.go），且导入被测包时使用正确的包名（推荐通过 go mod init 管理模块，避免使用非法 gist 路径）；
• 运行命令建议使用 go test -v（不指定具体文件），或确保当前目录为模块根目录，否则可能因包解析失败导致“no tests to run”。

✅ 正确执行后，你将看到类似输出：

=== RUN   Example --- PASS: Example (0.00s) PASS

总结：Go 示例不是“只要写了就能跑”的测试，而是“文档即测试”的设计——// Output: 既是预期结果声明，也是 go test 的执行开关。缺失它，函数仅被编译，不会触发运行。