testcontainers-go 使用指南

testcontainers-go 是一个用于 Go 的测试库，它允许你在测试中轻松启动和管理 Docker 容器作为依赖项。这对于集成测试特别有用，可以确保你的代码与真实服务（如数据库、消息队列等）正确交互。

安装

首先安装 testcontainers-go 库：

go get github.com/testcontainers/testcontainers-go

基本用法

1. 启动一个简单的容器

package main

import (
	"context"
	"fmt"
	"testing"
	"time"

	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/wait"
)

func TestWithRedis(t *testing.T) {
	// 创建 Redis 容器请求
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:        "redis:latest",
		ExposedPorts: []string{"6379/tcp"},
		WaitingFor:   wait.ForLog("Ready to accept connections").WithStartupTimeout(30 * time.Second),
	}

	// 启动容器
	redisC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	if err != nil {
		t.Fatal(err)
	}

	// 测试结束后清理容器
	defer func() {
		if err := redisC.Terminate(ctx); err != nil {
			t.Fatalf("failed to terminate container: %s", err)
		}
	}()

	// 获取容器IP和端口
	endpoint, err := redisC.Endpoint(ctx, "")
	if err != nil {
		t.Fatal(err)
	}

	fmt.Println("Redis endpoint:", endpoint)
	// 在这里可以使用 endpoint 连接到 Redis 进行测试
}

2. 使用预定义的模块

testcontainers-go 提供了一些常见服务的预定义模块：

package main

import (
	"context"
	"testing"

	"github.com/testcontainers/testcontainers-go/modules/postgres"
	"github.com/testcontainers/testcontainers-go/wait"
)

func TestWithPostgres(t *testing.T) {
	ctx := context.Background()
	
	// 使用 Postgres 模块
	pgContainer, err := postgres.RunContainer(ctx,
		postgres.WithDatabase("test-db"),
		postgres.WithUsername("postgres"),
		postgres.WithPassword("postgres"),
		testcontainers.WithWaitStrategy(
			wait.ForLog("database system is ready to accept connections").
				WithOccurrence(2).
				WithStartupTimeout(30*time.Second)),
	)
	if err != nil {
		t.Fatal(err)
	}
	defer pgContainer.Terminate(ctx)

	// 获取连接字符串
	connStr, err := pgContainer.ConnectionString(ctx)
	if err != nil {
		t.Fatal(err)
	}

	// 使用 connStr 连接到数据库进行测试
	t.Log("Postgres connection string:", connStr)
}

高级用法

1. 自定义容器配置

func TestWithCustomContainer(t *testing.T) {
	ctx := context.Background()
	
	req := testcontainers.ContainerRequest{
		Image:        "nginx:latest",
		ExposedPorts: []string{"80/tcp"},
		WaitingFor:   wait.ForHTTP("/").WithPort("80"),
		Env: map[string]string{
			"ENV_VAR": "value",
		},
		Mounts: testcontainers.ContainerMounts{
			testcontainers.BindMount("/host/path", "/container/path"),
		},
	}

	nginxC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	if err != nil {
		t.Fatal(err)
	}
	defer nginxC.Terminate(ctx)

	// 获取映射端口
	port, err := nginxC.MappedPort(ctx, "80")
	if err != nil {
		t.Fatal(err)
	}

	t.Logf("Nginx is running on port %s", port.Port())
}

2. 使用容器网络

func TestWithNetwork(t *testing.T) {
	ctx := context.Background()
	
	// 创建自定义网络
	networkName := "test-network"
	net, err := testcontainers.GenericNetwork(ctx, testcontainers.GenericNetworkRequest{
		NetworkRequest: testcontainers.NetworkRequest{
			Name:           networkName,
			CheckDuplicate: true,
		},
	})
	if err != nil {
		t.Fatal(err)
	}
	defer net.Remove(ctx)

	// 在网络上启动容器
	req := testcontainers.ContainerRequest{
		Image:    "alpine",
		Cmd:      []string{"tail", "-f", "/dev/null"}, // 保持容器运行
		Networks: []string{networkName},
	}

	alpineC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	if err != nil {
		t.Fatal(err)
	}
	defer alpineC.Terminate(ctx)
}

最佳实践

1. 复用容器：对于耗时较长的容器，考虑在多个测试间复用，可以使用 testing.M 和全局变量。

2. 并行测试：确保容器名称唯一，避免并行测试冲突：

   req := testcontainers.ContainerRequest{
       Name: fmt.Sprintf("container-%d", time.Now().UnixNano()),
       // ...
   }
   

3. 资源清理：始终使用 defer 确保容器被正确清理。

4. 等待策略：使用适当的等待策略确保容器真正准备好：

   WaitingFor: wait.ForAll(
       wait.ForLog("ready"),
       wait.ForListeningPort("8080/tcp"),
   ),
   

5. 调试：如果测试失败，可以临时禁用容器清理以检查容器状态：

   // defer container.Terminate(ctx) // 注释掉以检查容器
   

testcontainers-go 是一个强大的工具，可以显著提高集成测试的可靠性和真实性。通过使用真实的依赖服务而不是模拟，你可以更有信心地验证代码的行为。