Yao Sandbox V2 测试规范深度解析:从黑盒容器测试到 CI 集成

原创2026-09-26 20:57:242,333 阅读
文章标签:Agent 框架后端低代码RAG

Yao Sandbox V2 测试规范深度解析:从黑盒容器测试到 CI 集成

导读

本文是 Yao 开源仓库 sandbox/v2/TEST.md 的完整技术解读,全面覆盖 Sandbox V2 容器沙箱模块的测试设计:从黑盒测试原则、Docker/Tai 环境准备、统一测试辅助函数,到 Manager、Box、gRPC 等各层的必测用例、Makefile 集成与 CI 流水线编排。读完本文,你将掌握如何为本模块编写可复用、可跳过、可覆盖远程节点的集成测试,并理解底层源码中容器生命周期、心跳恢复、OAuth 令牌注入等机制为何如此设计。


一、测试设计五原则:黑盒、真实容器、可跳过

Sandbox V2 的测试策略在 TEST.md 中确立了五条核心原则,每一条都能在源码中找到对应依据:

  1. 黑盒测试(Black-box testing):所有 *_test.go 文件使用 package sandbox_test(而非内部包 package sandbox),测试只能访问导出的公开 API。这样保证测试不依赖未导出的内部实现细节,重构内部代码时测试无需改动。
  2. 真实容器(Real containers):测试通过 tai SDK 创建真实的 Docker 容器,不进行任何 mock。这意味着测试结果就是生产环境真实行为的缩影。
  3. 条件跳过(Skip when unavailable):通过 skipIfNoDocker(t) / skipIfNoTai(t) 两个辅助函数,在本地开发环境缺少 Docker 或 Tai 节点时自动跳过相关测试,保证 CI 有完整环境、本地开发无环境也能跑通其余用例。
  4. 测试跟随实现(Tests follow implementation):*_test.go 与被测代码文件放在同一目录下,例如 sandbox_test.go 紧挨 sandbox.go、manager_test.go 紧挨 manager.go。
  5. 覆盖率门槛(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 的测试体系可以概括为三个层次:

  1. 无环境层:grpc_test.go 中的环境构建、manager_unit_test.go 中的标签解析等纯单元测试,任何机器可跑,是覆盖率的基本盘;
  2. 单机容器层:依赖 Docker 的 box_test.go、manager_test.go,通过 skipIfNoDocker 优雅降级;
  3. 多节点层:依赖 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。

登录后查看全文
yao