Yao Sandbox V2 测试规范深度解析:从黑盒容器测试到 CI 集成
Yao Sandbox V2 测试规范深度解析:从黑盒容器测试到 CI 集成
导读
本文是 Yao 开源仓库 sandbox/v2/TEST.md 的完整技术解读,全面覆盖 Sandbox V2 容器沙箱模块的测试设计:从黑盒测试原则、Docker/Tai 环境准备、统一测试辅助函数,到 Manager、Box、gRPC 等各层的必测用例、Makefile 集成与 CI 流水线编排。读完本文,你将掌握如何为本模块编写可复用、可跳过、可覆盖远程节点的集成测试,并理解底层源码中容器生命周期、心跳恢复、OAuth 令牌注入等机制为何如此设计。
一、测试设计五原则:黑盒、真实容器、可跳过
Sandbox V2 的测试策略在 TEST.md 中确立了五条核心原则,每一条都能在源码中找到对应依据:
- 黑盒测试(Black-box testing):所有
*_test.go文件使用package sandbox_test(而非内部包package sandbox),测试只能访问导出的公开 API。这样保证测试不依赖未导出的内部实现细节,重构内部代码时测试无需改动。 - 真实容器(Real containers):测试通过 tai SDK 创建真实的 Docker 容器,不进行任何 mock。这意味着测试结果就是生产环境真实行为的缩影。
- 条件跳过(Skip when unavailable):通过
skipIfNoDocker(t)/skipIfNoTai(t)两个辅助函数,在本地开发环境缺少 Docker 或 Tai 节点时自动跳过相关测试,保证 CI 有完整环境、本地开发无环境也能跑通其余用例。 - 测试跟随实现(Tests follow implementation):
*_test.go与被测代码文件放在同一目录下,例如sandbox_test.go紧挨sandbox.go、manager_test.go紧挨manager.go。 - 覆盖率门槛(Coverage > 80%):单文件与整体覆盖率目标均为 80% 以上。
从源码看,黑盒原则的一个实际体现是 sandbox.go 只暴露两个函数:Init()(初始化全局 Manager)与 M()(获取全局单例,未调用 Init 时直接 panic)。测试正是围绕这两个公开入口展开,例如 sandbox_test.go 需要验证 Init 成功、M() 在未初始化前 panic、以及重复 Init 的安全性。
而 skipIfNoDocker(t) 等辅助函数集中定义在 testutils_test.go 中。该文件同时定义了 TestMain,在全部测试启动前执行两项关键准备工作:
func TestMain(m *testing.M) {
testprepare.MustLoadEnv() // 加载 YAO_TEST_APPLICATION 等环境变量
sandboxtest.PurgeStaleContainers("sb-") // 清理上次运行残留的 sb- 前缀容器
code := m.Run()
testprepare.Cleanup()
os.Exit(code)
}
其中 PurgeStaleContainers("sb-") 会清理所有以 sb- 开头的遗留容器,保证测试从干净状态开始——这正是「真实容器」原则下的必要前置清理。
二、环境准备:Docker、Tai 与环境变量
2.1 加载环境
所有测试开始前,需要先加载 Yao 的开发环境变量:
source $YAO_SOURCE_ROOT/env.local.sh
2.2 Docker(所有容器测试必需)
Docker daemon 必须处于运行状态,测试通过默认 socket 连接。没有 Docker 时,容器类测试会被 skipIfNoDocker 跳过。
2.3 Tai(仅远程模式测试必需)
远程模式测试需要一个 Tai 节点容器,它同时提供远端容器运行时、gRPC 转发、WebSocket/SSE 代理等能力:
docker run -d --name tai \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 2375:2375 -p 9100:9100 -p 8080:8080 -p 6080:6080 \
yaoapp/tai:latest
端口说明:2375 为 Docker 远程 API,9100 为 Tai 服务端口,8080 为 HTTP 代理,6080 为 VNC/WebSocket 相关端口。
2.4 环境变量一览
| 变量 | 用途 | 默认值 |
|---|---|---|
YAO_TEST_APPLICATION |
yao-dev-app 的路径 |
—(必填) |
YAO_DB_DRIVER / YAO_DB_PRIMARY |
数据库连接 | —(必填) |
YAO_JWT_SECRET / YAO_DB_AESKEY |
加密密钥(用于创建 OAuth 令牌) | —(必填) |
SANDBOX_TEST_IMAGE |
测试用容器镜像 | yaoapp/sandbox-v2-test:latest |
SANDBOX_TEST_REMOTE_ADDR |
Tai 远程地址,如 tai://127.0.0.1 |
—(为空则跳过远程测试) |
TAI_TEST_HOST |
Tai HTTP 代理主机 | 127.0.0.1 |
注意 SANDBOX_TEST_REMOTE_ADDR 是「远程测试的开关」:为空时 skipIfNoTai 直接跳过远程相关用例。这与 Makefile 中 test-remote 目标的逻辑一致——未设置该变量时直接输出跳过提示并退出。
三、目录结构与测试文件职责
sandbox/v2/
├── sandbox.go
├── sandbox_test.go # Init/M 单例测试
├── manager.go
├── manager_test.go # Create/Get/GetOrCreate/List/Remove、池管理
├── manager_lifecycle_test.go # 启动恢复、Cleanup、空闲跟踪、心跳
├── box.go
├── box_test.go # Exec/Stream/Workspace/Proxy/VNC、生命周期
├── box_attach_test.go # Attach WS/SSE(需要容器内服务)
├── config.go
├── types.go
├── errors.go
├── grpc.go
├── grpc_test.go # OAuth 令牌创建/吊销、环境变量构建
├── testutils_test.go # 共享测试辅助函数(未导出,package sandbox_test)
└── DESIGN.md
当前仓库 sandbox/v2 实际还包含 watcher.go、host.go、convert.go、export_test.go 等文件,且测试文件按模式拆分更细(如 manager_unit_test.go、box_unit_test.go、manager_sandbox_test.go、host_sandbox_test.go 等)。文档中的这份结构图是模块的经典划分,实际文件在演进中进一步细分了「纯单元测试」与「需真实容器的沙箱集成测试」。
四、testutils:共享测试辅助函数
testutils_test.go 不是独立包,而是直接位于 package sandbox_test 内的共享辅助代码。核心函数签名与用途如下:
// skipIfNoDocker skips the test if Docker is not available.
func skipIfNoDocker(t *testing.T)
// skipIfNoTai skips the test if SANDBOX_TEST_REMOTE_ADDR is empty.
func skipIfNoTai(t *testing.T)
// testImage returns SANDBOX_TEST_IMAGE or "yaoapp/sandbox-v2-test:latest".
func testImage() string
// setupManager initializes sandbox with a local pool, returns cleanup func.
// Calls sandbox.Init + sandbox.M().Start.
func setupManager(t *testing.T) func()
// setupManagerWithRemote initializes sandbox with local + remote pools.
func setupManagerWithRemote(t *testing.T) func()
// createTestBox creates a box with defaults and returns it. Registers t.Cleanup for removal.
func createTestBox(t *testing.T, opts ...sandbox.CreateOption) *sandbox.Box
这些辅助函数奠定了「三行起步」的测试范式:跳过判断 + 初始化 Manager + 创建 Box。setupManager 内部调用 sandbox.Init() + sandbox.M().Start(),对应源码 manager.go 中 Start 的行为:从 tai/registry 中枚举已注册节点,通过 recoverBoxes 恢复既有容器。也就是说,每次测试的 Manager 启动都是一次完整的「容器发现 + 状态恢复」演练。
createTestBox 注册了 t.Cleanup,测试结束后自动移除容器,避免资源泄漏。
五、如何编写测试:六类典型模式
5.1 标准模式(Manager 层)
// manager_test.go
package sandbox_test
import (
"context"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
sandbox "github.com/yaoapp/yao/sandbox/v2"
)
func TestCreate(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
Owner: "test-user",
})
require.NoError(t, err)
defer box.Remove(context.Background())
assert.NotEmpty(t, box.ID())
assert.Equal(t, "test-user", box.Owner())
}
func TestCreate_NoImage(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
_, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{})
assert.Error(t, err) // Image is required
}
源码佐证:Create 在 manager.go 中第一行就校验 opts.Image == "" 并返回错误「sandbox: image is required」。Create 的完整链路是:解析节点 → 生成 ID(缺省为 sb-<纳秒时间戳>)→ 调用 tai Runtime 创建容器 → 启动容器 → waitEntrypoint 等待入口点完成 UID 映射 → 构造 Box 存入 boxes map。
其中 waitEntrypoint 的实现很能体现测试价值:它轮询探测容器内 /workspace 属主 UID 是否与 sandbox 用户 UID 一致(兼容 Docker Desktop VirtioFS 下 UID 0 的情况),最多重试 9 次、退避递增至 2 秒。如果测试容器镜像的 entrypoint 行为异常,这类用例会第一时间暴露。
5.2 容器执行测试(Exec)
// box_test.go
package sandbox_test
func TestExec(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
result, err := box.Exec(context.Background(), []string{"echo", "hello"})
require.NoError(t, err)
assert.Equal(t, 0, result.ExitCode)
assert.Equal(t, "hello\n", result.Stdout)
assert.Empty(t, result.Stderr)
}
func TestExec_NonZeroExit(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
result, err := box.Exec(context.Background(), []string{"sh", "-c", "exit 42"})
require.NoError(t, err)
assert.Equal(t, 42, result.ExitCode)
}
源码佐证:Box.Exec 位于 box.go,内部会先 touch() 刷新活跃时间戳,再通过 injectGRPCAddr 注入 YAO_GRPC_ADDR 等环境变量,最后以 User: "sandbox" 身份在容器内执行命令。值得注意的细节:Exec 对 Docker 的 409 冲突做了最多 3 次幂等重试(每次间隔 500ms),因为 Docker 在上一 exec 会话尚未排空时可能返回 409。这正是 TestExec 这类用例能稳定通过的原因之一。
5.3 流式测试(Stream)
func TestStream(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
s, err := box.Stream(context.Background(), []string{"sh", "-c", "echo a; sleep 0.1; echo b"})
require.NoError(t, err)
out, _ := io.ReadAll(s.Stdout)
code, err := s.Wait()
assert.NoError(t, err)
assert.Equal(t, 0, code)
assert.Contains(t, string(out), "a\n")
assert.Contains(t, string(out), "b\n")
}
func TestStream_Cancel(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
s, err := box.Stream(context.Background(), []string{"sleep", "60"})
require.NoError(t, err)
s.Cancel()
code, _ := s.Wait()
assert.NotEqual(t, 0, code) // killed
}
func TestStream_Stdin(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
s, err := box.Stream(context.Background(), []string{"cat"})
require.NoError(t, err)
s.Stdin.Write([]byte("hello\n"))
s.Stdin.Close()
out, _ := io.ReadAll(s.Stdout)
code, _ := s.Wait()
assert.Equal(t, 0, code)
assert.Equal(t, "hello\n", string(out))
}
ExecStream 类型(见 types.go)暴露 Stdout/Stderr/Stdin 三个 I/O 句柄与 Wait()、Cancel() 两个控制方法,覆盖了「读输出、取消进程、写标准输入」三条主路径。源码中 Stream 还有一处健壮性处理:当底层返回「500 Internal Server Error」时,会先检查容器真实状态(inspectStatus),若容器仍在运行则等待 2 秒后重试一次,避免瞬时错误误伤测试。
5.4 工作区测试(Workspace)
func TestWorkspace_ReadWrite(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
ws := box.Workspace()
err := ws.WriteFile("test.txt", []byte("hello"), 0644)
require.NoError(t, err)
data, err := fs.ReadFile(ws, "test.txt")
require.NoError(t, err)
assert.Equal(t, "hello", string(data))
}
func TestWorkspace_MkdirAll(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
ws := box.Workspace()
err := ws.MkdirAll("a/b/c", 0755)
require.NoError(t, err)
info, err := fs.Stat(ws, "a/b/c")
require.NoError(t, err)
assert.True(t, info.IsDir())
}
func TestWorkspace_WalkDir(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
ws := box.Workspace()
ws.MkdirAll("src", 0755)
ws.WriteFile("src/main.go", []byte("package main"), 0644)
ws.WriteFile("src/util.go", []byte("package main"), 0644)
var files []string
fs.WalkDir(ws, "src", func(path string, d fs.DirEntry, err error) error {
if !d.IsDir() { files = append(files, path) }
return nil
})
assert.Len(t, files, 2)
}
Workspace() 返回的是 fs.FS 兼容的文件系统接口(见 box.go),底层由 taiworkspace.New(res.Volume, sessionID) 实现。关键设计是 session 的选择:优先使用挂载的 workspaceID,否则回退到 sandboxID(向后兼容)。因此测试可以直接用标准库 io/fs 的函数操作容器内文件系统——这本身就是对接口设计的验证。
5.5 生命周期测试(Lifecycle)
func TestIdleCleanup_Session(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
Policy: sandbox.Session,
IdleTimeout: 2 * time.Second,
})
require.NoError(t, err)
// Box exists
_, err = sandbox.M().Get(context.Background(), box.ID())
assert.NoError(t, err)
// Wait for idle + cleanup cycle
time.Sleep(4 * time.Second)
sandbox.M().Cleanup(context.Background())
// Box should be gone
_, err = sandbox.M().Get(context.Background(), box.ID())
assert.ErrorIs(t, err, sandbox.ErrNotFound)
}
func TestStartRecovery(t *testing.T) {
skipIfNoDocker(t)
// Phase 1: create a box, then shut down Manager
cleanup1 := setupManager(t)
box, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
Owner: "recovery-test",
})
require.NoError(t, err)
boxID := box.ID()
cleanup1() // closes Manager, but container stays
// Phase 2: new Manager, Start should discover the container
cleanup2 := setupManager(t)
defer cleanup2()
recovered, err := sandbox.M().Get(context.Background(), boxID)
require.NoError(t, err)
assert.Equal(t, boxID, recovered.ID())
assert.Equal(t, "recovery-test", recovered.Owner())
// Clean up
recovered.Remove(context.Background())
}
func TestHeartbeat(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
// Simulate heartbeat
err := sandbox.M().Heartbeat(box.ID(), true, 3)
assert.NoError(t, err)
info, _ := box.Info(context.Background())
assert.Equal(t, 3, info.ProcessCount)
}
func TestHeartbeat_NotFound(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
err := sandbox.M().Heartbeat("nonexistent", true, 1)
assert.ErrorIs(t, err, sandbox.ErrNotFound)
}
这三个用例分别验证了生命周期的三大机制:
- Session 空闲回收:
Policy: sandbox.Session配合 2 秒空闲超时,4 秒后调用Cleanup,容器应被移除。源码中空闲回收的真实执行者是 watcher.go 注册的sandboxWatcher——它以 30 秒为间隔轮询所有 Box,对Session策略的空闲容器执行mgr.Remove,对LongRunning策略的空闲容器执行b.Stop(停止而非删除),对OneShot策略则保留最长DefaultOneShotMaxAge(8 小时)作为清理失败的安全网。四种策略的默认超时定义在 types.go:DefaultStopTimeout=2s、DefaultSessionIdleTimeout=30min、DefaultLongRunningIdleTimeout=2h、DefaultOneShotMaxAge=8h、DefaultLifetimeGrace=5min。 - 启动恢复:
recoverBoxes(manager.go)通过查询标签managed-by=yao-sandbox的容器,读取sandbox-id、sandbox-owner、sandbox-policy等标签重建 Box。这就是TestStartRecovery中「Manager 关闭后容器仍在、重启后能找回」的底层原理。另外值得注意的是systemInfoFromLabels——恢复时优先从容器标签还原系统信息,不依赖 Tai 节点在线。 - 心跳更新:
Heartbeat(sandboxID, active, processCount)(manager.go)在active=true时刷新lastHeartbeat,并更新进程数;Box 不存在时返回ErrNotFound。
5.6 池管理测试(Pool Management)
func TestPoolLimits_MaxTotal(t *testing.T) {
skipIfNoDocker(t)
// Init with MaxTotal=1
err := sandbox.Init(sandbox.Config{
Pool: []sandbox.Pool{{
Name: "limited",
Addr: "local",
MaxTotal: 1,
}},
})
require.NoError(t, err)
sandbox.M().Start(context.Background())
defer sandbox.M().Close()
box1, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
})
require.NoError(t, err)
defer box1.Remove(context.Background())
_, err = sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
})
assert.ErrorIs(t, err, sandbox.ErrLimitExceeded)
}
func TestAddPool(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
err := sandbox.M().AddPool(context.Background(), sandbox.Pool{
Name: "new-pool",
Addr: "local",
})
assert.NoError(t, err)
pools := sandbox.M().Pools()
names := make([]string, len(pools))
for i, p := range pools { names[i] = p.Name }
assert.Contains(t, names, "new-pool")
}
func TestRemovePool_InUse(t *testing.T) {
skipIfNoDocker(t)
cleanup := setupManager(t)
defer cleanup()
box := createTestBox(t)
_ = box
err := sandbox.M().RemovePool(context.Background(), "local", false)
assert.ErrorIs(t, err, sandbox.ErrPoolInUse)
}
池管理测试验证了三类约束:容量上限(MaxTotal=1 时第二个容器创建返回 ErrLimitExceeded)、动态增池(AddPool 后 Pools() 列表包含新池)、在用保护(池内存在容器时 RemovePool 返回 ErrPoolInUse)。
5.7 多池测试(Multi-Pool / 远程模式)
func TestMultiNode(t *testing.T) {
skipIfNoDocker(t)
skipIfNoTai(t)
cleanup := setupManagerWithRemote(t)
defer cleanup()
// Create on local
local, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
Pool: "local",
})
require.NoError(t, err)
defer local.Remove(context.Background())
// Create on remote
remote, err := sandbox.M().Create(context.Background(), sandbox.CreateOptions{
Image: testImage(),
Pool: "remote",
})
require.NoError(t, err)
defer remote.Remove(context.Background())
// Both should exec
r1, _ := local.Exec(context.Background(), []string{"echo", "local"})
r2, _ := remote.Exec(context.Background(), []string{"echo", "remote"})
assert.Equal(t, "local\n", r1.Stdout)
assert.Equal(t, "remote\n", r2.Stdout)
}
这是唯一同时调用 skipIfNoDocker 与 skipIfNoTai 的用例:本地与远程两个池各自创建容器并执行命令。它完整验证了「一个 Manager 管理多个节点容器」的核心能力,对应 manager.go 中节点连接委托给 tai/registry 的设计——每个节点提供独立的 Runtime、Volume、Proxy、VNC 能力。
5.8 OAuth / gRPC 环境注入测试
func TestBuildGRPCEnv_Local(t *testing.T) {
env := sandbox.BuildGRPCEnv(&sandbox.Pool{Addr: "local"}, "sb-001", "tok", "ref")
assert.Equal(t, "sb-001", env["YAO_SANDBOX_ID"])
assert.Equal(t, "tok", env["YAO_TOKEN"])
assert.Equal(t, "ref", env["YAO_REFRESH_TOKEN"])
assert.NotEmpty(t, env["YAO_GRPC_ADDR"])
}
func TestBuildGRPCEnv_Remote(t *testing.T) {
env := sandbox.BuildGRPCEnv(&sandbox.Pool{Addr: "tai://gpu.internal"}, "sb-002", "tok", "ref")
assert.NotEmpty(t, env["YAO_GRPC_ADDR"])
}
func TestCreateContainerTokens(t *testing.T) {
// Requires Yao runtime for OAuth
cleanup := setupManager(t)
defer cleanup()
access, refresh, err := sandbox.CreateContainerTokens("sb-test", "user-1")
require.NoError(t, err)
assert.NotEmpty(t, access)
assert.NotEmpty(t, refresh)
}
gRPC 环境注入是 Sandbox V2 的「身份打通」机制。源码 grpc.go 的 BuildGRPCEnv 展示了完整逻辑:
- 所有容器固定通过
host.tai.internal访问宿主机(由 Tai 在创建容器时注入该 DNS); - local 模式:
YAO_GRPC_ADDR = host.tai.internal:<Yao gRPC 端口>(缺省 9099),且当 Yao 配置了 gRPC 证书时额外注入YAO_GRPC_TLS=true; - tunnel/cloud 模式:使用节点注册时上报的
Ports.GRPC,由 Tai Gateway 转发到 Yao; - 同时注入
YAO_SANDBOX_ID、CTX_CHAT_ID、CTX_WORKSPACE_ID供容器内进程识别上下文。
Exec 时还有一层动态注入:injectGRPCAddr(box.go)每次执行前从 registry 读取最新的 gRPC 端口,即使 Tai 重启换端口也不会失联——但若调用方显式设置了 YAO_GRPC_ADDR,则尊重显式值不覆盖。这是文档测试用例背后的深层设计逻辑。
六、必测用例清单(Required Test Cases)
| 文件 | 必测用例 |
|---|---|
sandbox_test.go |
Init 成功 / M() 在 Init 前 panic / 重复 Init 安全 |
manager_test.go |
Create / 显式 ID 创建 / 无镜像创建(报错)/ Get / Get 未找到 / GetOrCreate / List / 按 Owner 过滤 List / Remove / 池上限 MaxTotal / 池上限 MaxPerUser / AddPool / RemovePool / 在用池 RemovePool(报错)/ Pools |
manager_lifecycle_test.go |
从标签启动恢复 / Cleanup Session 空闲 / Cleanup LongRunning 停止后移除 / Persistent 永不清理 / 心跳更新 / 心跳未找到 / OneShot Exec 后自动移除 |
box_test.go |
Exec 成功 / Exec 非零退出 / Exec 指定 WorkDir / Exec 指定 Env / Exec 超时 / Stream 读取 / Stream 取消 / Stream 标准输入 / Workspace 读+写 / Workspace MkdirAll / Workspace Remove / Workspace Rename / Workspace WalkDir / VNC(无 VNC 镜像则跳过)/ Proxy URL / Start+Stop+Start / Info |
box_attach_test.go |
Attach WS(无 WS 服务器镜像则跳过)/ Attach SSE(无 SSE 服务器镜像则跳过) |
grpc_test.go |
BuildGRPCEnv 本地 / BuildGRPCEnv 远程 / CreateContainerTokens / RevokeContainerTokens |
注意「无则跳过」的用例:VNC、WS、SSE 三类依赖测试镜像内置的特殊服务,若镜像中不存在对应服务则跳过,避免假失败。这体现了文档「测试跟随能力」的设计思想。
七、Makefile 集成:覆盖率聚合
TEST.md 给出了在仓库根 Makefile 中添加 unit-test-sandbox-v2 目标的标准模板:
TESTFOLDER_SANDBOX_V2 := $(shell $(GO) list ./sandbox/v2/...)
.PHONY: unit-test-sandbox-v2
unit-test-sandbox-v2:
echo "mode: count" > coverage.out
for d in $(TESTFOLDER_SANDBOX_V2); do \
$(GO) test -tags $(TESTTAGS) -v -timeout=10m \
-covermode=count -coverprofile=profile.out \
-coverpkg=$$d \
$$d > tmp.out; \
cat tmp.out; \
if grep -q "^--- FAIL" tmp.out; then \
rm tmp.out; \
exit 1; \
elif grep -q "build failed" tmp.out; then \
rm tmp.out; \
exit 1; \
fi; \
if [ -f profile.out ]; then \
cat profile.out | grep -v "mode:" >> coverage.out; \
rm tmp.out; \
fi; \
done
该目标的关键设计:
-timeout=10m:容器测试耗时较长,需放宽超时;-covermode=count -coverpkg=$$d:按包统计覆盖率,多包结果聚合到coverage.out;grep "^--- FAIL"与grep "build failed"双保险:任一测试失败或编译失败立即退出并返回非零码,保证 CI 中断。
仓库实际已实现该目标,根 Makefile 中 unit-test-sandbox-v2: unit-test-tai unit-test-workspace 声明了依赖顺序(先跑 tai 与 workspace 的测试)。sandbox/v2/Makefile 还提供了更细粒度的本地目标:
make test-local:仅本地 Docker 模式(-run '/local');make test-remote:远程模式,未设置SANDBOX_TEST_REMOTE_ADDR时自动跳过;make test:双模式全量测试;make test-ci:带覆盖率聚合的 CI 版本。
八、CI 集成:GitHub Actions 编排
TEST.md 给出了完整的 sandbox-v2-test job 定义(用于 unit-test.yml 与 pr-test.yml):
sandbox-v2-test:
runs-on: ubuntu-latest
services:
mongodb:
image: mongo:6.0
ports:
- 27017:27017
env:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: "123456"
MONGO_INITDB_DATABASE: test
strategy:
matrix:
go: ["1.25"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: ${{ matrix.go }}
- name: Start Tai container
run: |
docker run -d --name tai \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 2375:2375 -p 9100:9100 -p 8080:8080 -p 6080:6080 \
yaoapp/tai:latest
sleep 3
- name: Build V2 test image
run: |
cd sandbox/docker
bash build.sh v2
- name: Setup ENV
run: |
echo "YAO_DB_DRIVER=sqlite3" >> $GITHUB_ENV
echo "YAO_DB_PRIMARY=${{ github.WORKSPACE }}/../app/db/yao.db" >> $GITHUB_ENV
echo "SANDBOX_TEST_IMAGE=yaoapp/sandbox-v2-test:latest" >> $GITHUB_ENV
echo "SANDBOX_TEST_REMOTE_ADDR=tai://127.0.0.1" >> $GITHUB_ENV
echo "TAI_TEST_HOST=127.0.0.1" >> $GITHUB_ENV
mkdir -p ${{ github.WORKSPACE }}/../app/db
- name: Run Sandbox V2 Tests
run: make unit-test-sandbox-v2
- name: Codecov Report
uses: codecov/codecov-action@v4
with:
token: ${{ secrets.CODECOV_TOKEN }}
CI 编排中的关键决策(原文明确列出):
- 仅 SQLite:沙箱是基础设施而非数据模型,测试不需要多数据库矩阵,用 SQLite 降低成本与抖动;
- Tai 容器提供远程模式:完整走一遍代理链路(proxy path),让
TestMultiNode等远程用例在 CI 中真实执行; sandbox-v2-test作为默认测试镜像:内置tai(心跳上报)、openai-proxy、Nginx、WS echo 与 SSE 测试服务,一次拉起即可覆盖 Exec、Attach、Proxy、Heartbeat 全部能力;- CI 从源码构建测试镜像(Step
Build V2 test image,bash build.sh v2):保证测试镜像与最新 tai SDK 变更保持二进制兼容,避免「镜像旧、代码新」导致的假阴性; - **Attach 测试(WS/SSE)**直接复用测试镜像的内置服务,无需额外起服务容器。
九、覆盖率策略
覆盖率目标:单文件 >80%、整体 >80%。TEST.md 对每个文件的覆盖路径做了明确规划:
sandbox.go(单例):通过sandbox_test.go覆盖——Init、M、panic 路径、重复 Init;manager.go(最重的文件):必须有独立的manager_test.go+manager_lifecycle_test.go双文件覆盖,因为Create的完整链路涉及节点解析、镜像检查、容器创建、entrypoint 等待、标签写入等多个分支;box.go:通过box_test.go覆盖所有 tai SDK 集成点(Exec/Stream/Workspace/VNC/Proxy/Start/Stop/Info);grpc.go:纯单元测试即可覆盖(令牌生成、环境构建),无需真实容器——这正是「按测试成本分级」的体现。
值得补充的是,当前仓库在演进中还出现了 export_test.go(导出内部函数供黑盒包测试)与各类 *_unit_test.go/*_sandbox_test.go 拆分——例如 manager_unit_test.go 直接对 ExportDefaultWorkspaceName、ExportSystemInfoFromLabels 做纯单元验证,无需 Docker。这种「无环境可跑的单元测试 + 需环境的沙箱测试」分层,正是达成 80% 覆盖率且不让 CI 过度依赖外部资源的实践路径。
十、运行测试的完整命令
# 所有 sandbox v2 测试(仅本地 Docker)
make unit-test-sandbox-v2
# 带远程模式(先启动 Tai)
SANDBOX_TEST_REMOTE_ADDR=tai://127.0.0.1 make unit-test-sandbox-v2
# 单文件
go test -v ./sandbox/v2/ -run TestCreate
# 单个测试
go test -v ./sandbox/v2/ -run TestExec_NonZeroExit
# 竞态检测
go test -race -v ./sandbox/v2/
实践建议:
- 本地开发阶段优先用
go test -v ./sandbox/v2/ -run TestCreate之类的定向运行,秒级反馈; - 提交前用
make test-local验证本地池路径,若配置了 Tai 节点再加SANDBOX_TEST_REMOTE_ADDR跑make test双模式; - 涉及并发与心跳的用例建议加
-race,因为Box内部大量使用atomic.Int64/atomic.Int32/sync.Map(manager.go、box.go),竞态检测能捕获lastCall、processCount等并发更新的隐患。
十一、与源码的对应关系速查
| 测试关注点 | 底层实现 |
|---|---|
| 单例初始化 / panic 语义 | sandbox.go(Init / M) |
| 创建、恢复、心跳、节点解析 | manager.go(Create / recoverBoxes / Heartbeat / getNode) |
| 生命周期清理、OneShot 安全网 | watcher.go(sandboxWatcher.Check) |
| Exec/Stream/Workspace/VNC/Proxy | box.go(Exec / Stream / Workspace / VNC / Proxy) |
| gRPC 环境注入、TLS 判定 | grpc.go(BuildGRPCEnv / resolveGRPCAddr / resolveGRPCTLS) |
| 生命周期策略与默认超时 | types.go(OneShot/Session/LongRunning/Persistent 及默认值) |
错误语义(ErrNotFound 等) |
errors.go |
| 测试辅助函数与 TestMain 清理 | testutils_test.go |
| 本地/远程/CI 测试目标 | Makefile 与根 Makefile 的 unit-test-sandbox-v2 |
十二、设计思路总结
Sandbox V2 的测试体系可以概括为三个层次:
- 无环境层:
grpc_test.go中的环境构建、manager_unit_test.go中的标签解析等纯单元测试,任何机器可跑,是覆盖率的基本盘; - 单机容器层:依赖 Docker 的
box_test.go、manager_test.go,通过skipIfNoDocker优雅降级; - 多节点层:依赖 Tai 的远程用例(
TestMultiNode、Attach 等),通过skipIfNoTai与 CI 中的 Tai 容器保证在流水线内真实执行。
这种分层配合「真实容器、无 mock、黑盒访问、覆盖率 80%」的原则,既保证了测试结果与生产行为高度一致,又让本地开发、PR 校验、发布流水线各取所需。对希望为本模块贡献测试的开发者而言,最快路径是:阅读 TEST.md 的必测用例表,对照 manager_test.go、box_test.go、grpc_test.go 的既有模式,套用 setupManager + createTestBox 三板斧即可写出风格一致的用例。更深入的设计背景可进一步阅读同目录的 DESIGN.md 与 IMPL.md。