如何在Go中编写可测试的示例测试代码？

下面给你几个实用方案，解决示例代码既要放进文档又要能测试/检查的问题：

方案1：测试函数+文档注释关联 #

把你的示例测试代码写成标准的TestFoo函数，放在常规的xxx_test.go测试文件里，直接用go test就能运行验证。然后在框架的包注释或者核心函数的注释里，把这段代码以Markdown代码块的形式贴进去，godoc会自动把注释里的代码展示在文档中。

比如在mytestframework_test.go里写真实可运行的测试：

func TestFoo(t *testing.T) {
    f := mytestframework.FromT(t)
    // 这里写实际的测试逻辑，比如验证f的功能是否正常
    if err := f.DoSomething(); err != nil {
        t.Fatal(err)
    }
}

然后在框架核心函数FromT的注释里引用这段示例：

// FromT 基于testing.T创建测试框架实例
// 示例用法：
//
// func TestFoo(t *testing.T) {
//     f := mytestframework.FromT(t)
//     // 用f执行测试操作
//     if err := f.DoSomething(); err != nil {
//         t.Fatal(err)
//     }
// }
func FromT(t *testing.T) *Framework {
    // 函数实现
}

这样文档里能展示示例，测试代码也能随时运行验证，不会过时。

方案2：用go:embed嵌入示例文件+编译检查 #

单独创建一个不带_test.go后缀的示例文件，比如test_example.go，把你的示例代码放进去，然后用//go:embed把这个文件嵌入到文档中，同时写一个测试函数来检查这个文件能否正常编译。

1. 先写test_example.go：

package mytestframework

import "testing"

func TestFoo(t *testing.T) {
    f := FromT(t)
    // code using f
}

2. 在doc.go里嵌入并展示这个示例：

package mytestframework

import _ "embed"

//go:embed test_example.go
var testExample string

// 测试框架使用示例：
//
// ```go
// {{.testExample}}
// ```
// 运行`go test -run TestFoo`就能验证这个示例的有效性

3. 加一个测试函数检查编译：

func TestExampleCompiles(t *testing.T) {
    cmd := exec.Command("go", "build", "./test_example.go")
    if err := cmd.Run(); err != nil {
        t.Fatalf("示例代码编译失败: %v", err)
    }
}

这样文档里的示例直接来自真实文件，编译测试能确保代码没有语法和类型错误。

方案3：脚本提取文档代码做静态检查 #

如果坚持把示例写在Markdown文档里，那可以写个简单脚本，提取文档中的Go代码块，用go vet或者go build做静态检查，把这个脚本加到CI流程里，每次提交都自动校验。

比如bash脚本：

# 从docs.md里提取Go代码块到临时文件
grep -A 100 "```go" docs.md | grep -B 100 "```" | grep -v "```" > temp_example.go
# 做类型检查
go vet temp_example.go
# 清理临时文件
rm temp_example.go

这样至少能保证文档里的示例代码没有语法错误，不会悄悄过时。

内容的提问来源于stack exchange，提问作者kcza