OpenSandbox JavaScript E2E 测试完全指南环境准备、运行流程与源码剖析【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxtests/javascript/README.md是 OpenSandbox 仓库中 JavaScript/TypeScript SDK 端到端E2E测试套件的使用说明。本指南以该文档为骨架结合仓库中真实测试代码tests/javascript/tests与工程配置package.json、vitest.config.ts系统讲解这套严格 E2E 测试的定位、前置条件、环境变量、完整运行流程以及每个测试模块所验证的 SDK 能力矩阵。读完本文你将能够在本地一键拉起 OpenSandbox 服务后运行全部 JS E2E 用例并能读懂每个用例背后对应的 SDK API 行为契约。一、测试套件定位与 Python/Java E2E 对齐的严格回归防线按照 tests/javascript/README.md 的说明该目录包含针对 JavaScript/TypeScript SDK 的严格 E2E 测试strict E2E tests并与仓库中OpenSandbox/tests/python、OpenSandbox/tests/java两套测试对齐。所谓严格体现在测试不是对 SDK 内部函数的单元测试而是真正连上一个正在运行的 OpenSandbox Server通过 sdks/sandbox/javascriptalibaba-group/opensandbox与 sdks/code-interpreter/javascriptalibaba-group/opensandbox-code-interpreter这两个 SDK 的公共 API 完成沙箱创建、命令执行、文件操作、网络策略、代码解释执行等全链路验证。从目录结构看套件由两部分组成工程配置文件package.jsonpnpm 项目定义与脚本、vitest.config.tsVitest 运行参数、tsconfig.jsonTypeScript 编译选项、eslint.config.mjs扁平化 ESLint 配置。9 个测试文件位于 tests/javascript/tests 下其中 base_e2e.ts 是共享测试基座其余 8 个.test.ts为 Vitest 用例文件。测试采用type: moduleESM风格编写依赖通过link:协议直接引用仓库内 SDK 源码目录见 package.json这意味着测试运行前会先构建 SDK保证被测代码与仓库当前源码一致而不是使用 npm 上发布的旧版本。二、前置条件Prerequisites原文档明确列出三条前置要求逐一说明前置条件要求说明Node.js经 nvm 安装 20SDK 的engines字段要求node 20这也是测试环境的下限pnpm9.xcorepack 或全局安装仓库锁定packageManager: pnpm9.15.0见 package.jsonOpenSandbox Server处于运行状态测试通过localhost:8080默认访问 Server API此外代码解释器相关用例依赖opensandbox/code-interpreter:latest镜像默认值因此建议先完成镜像拉取避免首个用例因镜像拉取超时而失败。三、环境变量与 Python 测试同名对齐这套测试遵循与 Python 测试相同的命名约定四个核心环境变量及其默认值如下默认值定义可对照 tests/javascript/tests/base_e2e.ts环境变量默认值作用OPENSANDBOX_TEST_DOMAINlocalhost:8080OpenSandbox Server 的域名与端口OPENSANDBOX_TEST_PROTOCOLhttp访问协议可设为https启用 TLSOPENSANDBOX_TEST_API_KEYe2e-test访问 Server 的 API KeyOPENSANDBOX_SANDBOX_DEFAULT_IMAGEopensandbox/code-interpreter:latest默认沙箱镜像从源码看这些变量在 base_e2e.ts 中通过process.env.XXX ?? DEFAULT模式读取即未设置时优雅回退到默认值方便本地零配置启动export const TEST_DOMAIN process.env.OPENSANDBOX_TEST_DOMAIN ?? DEFAULT_DOMAIN; export const TEST_PROTOCOL process.env.OPENSANDBOX_TEST_PROTOCOL ?? DEFAULT_PROTOCOL; export const TEST_API_KEY process.env.OPENSANDBOX_TEST_API_KEY ?? DEFAULT_API_KEY; export const TEST_IMAGE process.env.OPENSANDBOX_SANDBOX_DEFAULT_IMAGE ?? DEFAULT_IMAGE;除上述四个变量外从测试源码还可以发现一个可选开关OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP见 test_credential_vault_e2e.test.ts。只有当该变量被设置指向凭据保险库 E2E 目标主机的 IP时凭据保险库相关用例才会执行否则这些用例会被test.skip跳过。这一点在原 README 中未提及属于源码揭示的隐藏行为。四、完整运行流程从零到全部用例通过原文档给出了一套完整的命令行流程以下逐条展开说明其背后的工程含义。4.1 切换 Node.js 版本cd OpenSandbox/tests/javascript # Node 20 是必需的SDK engines: node 20 source ~/.nvm/nvm.sh nvm use 22OpenSandbox 仓库的 JS SDK 要求node 20而当前 Node.js 主版本线22 及以上均可使用。通过 nvm 切换版本可确保本地环境与 CI 一致。4.2 激活 pnpm 9.x# 确保 pnpm 可用仓库锁定 pnpm9.x corepack enable corepack prepare pnpm9.15.0 --activate仓库在 package.json 中通过packageManager: pnpm9.15.0字段锁定了 pnpm 版本同时声明了rollup、vite、esbuild等依赖的overrides覆盖见 package.json用于统一传递依赖版本、规避供应链解析差异。使用 corepack 激活的 pnpm 9.15.0 可以确保这些 overrides 按预期生效。4.3 安装测试依赖# 安装测试依赖vitest、typescript 等 pnpm installdevDependencies 包括vitest ^4.1.0、typescript ^5.7.2、vite ^6.4.3、eslint ^9.39.4与typescript-eslint ^8.59.0见 package.json。pnpm install会自动执行pretest钩子中的pnpm install --prefer-offlinepackage.json优先使用本地缓存以加速安装。4.4 运行测试# 运行测试同时会构建 SDK pnpm testpnpm test实际执行的是pnpm run prep:sdk pnpm exec vitest run见 package.json分两步prep:sdk构建 SDK执行pnpm -C ../../sdks install --prefer-offline pnpm -C ../../sdks run build:js即先安装 sdks 工作区依赖再构建alibaba-group/opensandbox与alibaba-group/opensandbox-code-interpreter两个 JS SDK。这正是测试同时构建 SDK的来源。vitest run执行用例以单次运行非 watch模式执行全部测试。4.5 关键运行参数源码级解读vitest.config.ts 定义了三个关键行为export default defineConfig({ test: { environment: node, // 这些 E2E 测试可能因 provider 不同而较慢 testTimeout: 15 * 60_000, hookTimeout: 15 * 60_000, // 保持执行顺序确定对齐 Python/Java E2E 套件的有序执行 sequence: { concurrent: false }, }, });environment: node在 Node.js 环境运行不加载浏览器环境符合 SDK 的纯服务端 API 特性。testTimeout与hookTimeout均为 15 分钟E2E 用例涉及真实的沙箱创建、镜像拉取与远程执行必须给足超时余量beforeAll/afterAll钩子同样有 15 分钟上限。sequence.concurrent: false串行执行所有用例保证执行顺序确定与 Python/Java E2E 套件的有序策略保持一致避免并发用例之间互相干扰例如共享端口、共享镜像。4.6 CI 模式仓库还提供了面向 CI 的脚本test:ci见 package.jsonpnpm test:ci它与本地模式的区别在于vitest run会同时输出默认报告器和 JUnit 报告JUnit XML 写入build/test-results/junit.xml便于 CI 平台如 Jenkins、GitLab CI解析测试结果。五、测试基座 base_e2e.ts 剖析base_e2e.ts 是全部用例的公共底座封装了三类能力1. 连接配置工厂base_e2e.ts#L31-L39export function createConnectionConfig(useServerProxy false): ConnectionConfig { return new ConnectionConfig({ domain: TEST_DOMAIN, protocol: TEST_PROTOCOL https ? https : http, apiKey: TEST_API_KEY, requestTimeoutSeconds: 180, useServerProxy }); }requestTimeoutSeconds: 180所有 SDK 请求的超时统一为 180 秒。useServerProxy为true时走 Server 代理模式。网络策略用例专门验证了两种模式直连与代理下 egress 端点行为的一致性见 test_sandbox_e2e.test.ts。2. 时间戳校验base_e2e.ts#L45-L51assertRecentTimestampMs断言时间戳落在now ± 180s容差内用于验证 SDK 返回的 metrics 时间戳是活的而非陈旧缓存。3. 端点端口校验base_e2e.ts#L53-L73assertEndpointHasPort兼容两种端点形态——host:port直连形式以及带路由的/sandboxes/{id}/proxy/{port}代理形式后者要求以/{expectedPort}结尾。这正好呼应了useServerProxy两种模式下端点格式的差异。六、测试模块能力矩阵每个文件验证什么以下结合源码逐模块梳理 8 个测试文件覆盖的能力方便读者按需挑选或定位用例。6.1 Sandbox 全生命周期与执行 APItest_sandbox_e2e.test.ts这是体量最大、覆盖面最广的用例文件约 1164 行包括生命周期Sandbox.create→isHealthy→getInfo→getMetrics→renew续期→Sandbox.connect按 ID 重连→kill校验entrypoint、metadata、expiresAt等字段test_sandbox_e2e.test.ts#L77-L122。Extensions 回传创建时传入extensions键值对getInfo后原样读回#L124-L150。网络策略NetworkPolicy创建时指定defaultAction: deny与 egress 白名单用curl实测pypi.org可达、github.com被拒再通过patchEgressRules热更新策略并验证反转效果。该用例在直连与 Server 代理两种模式下各跑一遍#L174-L264。卷挂载覆盖 host 目录只读/读写挂载、PVC 命名卷只读/读写挂载、PVC subPath 挂载五类场景验证沙箱内外文件读写双向可见性与只读保护#L266-L623。命令执行契约成功执行、workingDirectory指定工作目录、background后台运行、失败命令CommandExecError四类结果并借助ExecutionHandlers流式回调收集onStdout/onStderr/onResult/onInit/onExecutionComplete/onError事件#L643-L728。后台命令日志getCommandStatusgetBackgroundCommandLogs带游标分页拉取#L730-L759。命令级环境变量注入run(..., { envs })仅对单条命令生效#L761-L782。Bash 会话 APIcreateSession/runInSession/deleteSession验证会话内工作目录切换与export环境变量跨命令持久化#L784-L837。文件系统 APIcreateDirectories、getFileInfo、writeFiles支持字符串与Uint8Array字节、owner/group/mode、search、readFile含rangeHTTP Range 与offset/limit行读取、readBytes、readBytesStream异步迭代器流式读取、setPermissions、replaceContentsDetailed返回替换计数覆盖无匹配/多匹配/批量替换、moveFiles、deleteFiles、deleteDirectories#L839-L1038。中断命令interrupt(initId)终止运行中的长任务#L1040-L1097。Pause/Resume该用例目前被显式跳过return提前退出#L1099-L1101保留代码供参考。x-request-id 透传在ConnectionConfig中注入X-Request-ID请求头断言 Server 报错时SandboxApiException.requestId能原样回传便于日志追踪#L1142-L1164。6.2 Code Interpreter 多语言代码执行test_code_interpreter_e2e.test.ts围绕alibaba-group/opensandbox-code-interpreter的CodeInterpreter类验证上下文管理createContext/getContext/listContexts/deleteContext/deleteContexts支持按SupportedLanguages.PYTHON过滤#L179-L201。多语言执行Java、Python、Go、TypeScript 四语言codes.run验证 stdout、返回值result[0].text与EvalException错误语义#L203-L301。上下文隔离同一语言的多个 context 之间变量互不可见Python 变量在另一 context 中访问触发NameError#L303-L327。并发执行Python/Java/Go 三个 context 并行运行容忍 CI 抖动断言至少 2/3 成功#L329-L364。中断与错误处理codes.interrupt(initId)终止长任务伪造 ID 的中断必须抛错#L366-L405。值得注意的工程实践该文件实现了withRetry重试助手与ensureSandboxAlive健康检查针对terminated、other side closed、fetch failed、session is busy、UND_ERR_SOCKET等可重试错误自动重建沙箱#L92-L136显著降低长跑套件在网络抖动下的偶发失败率。6.3 客户端沙箱池test_sandbox_pool_e2e.test.ts验证SandboxPool的完整生命周期pool.start()预热 →snapshot()轮询至idleCount 1→acquire({ policy: AcquirePolicy.FAIL_FAST })获取并执行命令 →resize(0)releaseAllIdle()回收 → 空池时FAIL_FAST抛PoolEmptyException→ 降级AcquirePolicy.DIRECT_CREATE直接创建。状态存储使用InMemoryPoolStateStoretest_sandbox_pool_e2e.test.ts#L36-L89。该用例 5 分钟超时是对客户端侧沙箱池机制对应 osep 0005 设计的端到端背书。6.4 凭据保险库test_credential_vault_e2e.test.ts在设置OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP后启用验证sandbox.credentialVault.create支持bearer、basic、apiKey、customHeaders四类鉴权类型且返回的 state 载荷不泄露任何明文密钥同时验证占位符在 query、path、body 中的运行时替换test_credential_vault_e2e.test.ts#L36-L100。6.5 隔离会话test_isolated_session_e2e.test.ts通过extensions: { bootstrap.execd.isolation: enable }开启隔离能力先查询sandbox.isolation.capabilities()再验证会话的创建、查询、列表、后台运行轮询与删除create/get/list/getRunStatus/deletetest_isolated_session_e2e.test.ts#L36-L80。6.6 Sandbox Managertest_sandbox_manager_e2e.test.ts验证SandboxManager.create后的listSandboxInfos按状态、metadata 过滤分页与getSandboxInfo并用waitForState轮询等待目标状态如Running→ 过期回收覆盖多沙箱管理与状态机流转test_sandbox_manager_e2e.test.ts#L58-L80。6.7 生命周期指标test_lifecycle_metrics_e2e.test.ts直接向/v1/metrics/events端点 POST SDK 形态的sandbox.create事件断言返回 204随后用包装fetch的方式拦截 SDK 请求验证Sandbox.create会自动向生命周期 Server 上报sandbox.create指标test_lifecycle_metrics_e2e.test.ts#L27-L80。6.8 就绪等待诊断信息test_wait_until_ready_diagnostics.test.ts这是一个准单元测试用假对象注入失败的health.ping断言waitUntilReady超时抛出的SandboxReadyTimeoutException消息中包含最后一次健康检查错误、domain、useServerProxy等诊断上下文当 ping 持续返回false时消息中还会出现Health check returned false continuously.提示test_wait_until_ready_diagnostics.test.ts#L19-L78。七、代码质量配套TypeScript 严格模式与 ESLinttsconfig.json 开启strict: true、target/module: ES2022、moduleResolution: BundlernoEmit仅做类型检查allowImportingTsExtensions允许直接import ... from ./base_e2e.ts这种带扩展名导入测试代码中确实如此使用。eslint.config.mjs 采用typescript-eslint扁平化配置忽略node_modules、build与*.d.ts关闭no-explicit-any以适配 E2E 测试中的断言代码同时以^_前缀豁免未使用参数/变量保证pnpm lint--max-warnings 0零告警通过。八、常见问题与排查建议结合源码中内置的重试与诊断机制给出以下实操建议健康检查失败导致用例批量失败先确认 OpenSandbox Server 已启动且OPENSANDBOX_TEST_DOMAIN/OPENSANDBOX_TEST_API_KEY与 Server 实际配置一致若为网络抖动Code Interpreter 用例自带的withRetry/ensureSandboxAlive会自动重建沙箱重试。镜像相关失败确认OPENSANDBOX_SANDBOX_DEFAULT_IMAGE指向的镜像已存在testTimeout15 分钟足够覆盖首次镜像拉取但建议提前手动docker pull。用例执行顺序影响套件串行执行sequence.concurrent: false个别用例对共享资源如 PVC 卷opensandbox-e2e-pvc-test、host 目录/tmp/opensandbox-e2e/host-volume-test有隐式依赖请勿通过vitest --no-threads之外的并行参数运行。凭据保险库用例被跳过属正常未设置OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP时该模块用例全部skip这是设计行为而非失败。定位超时问题利用SandboxReadyTimeoutException消息中的最后一次健康检查错误 连接上下文domain/useServerProxy以及x-request-id透传能力可在 Server 日志中精准串联单次请求链路。九、结语OpenSandbox 的 JS E2E 测试套件以 tests/python 与 tests/java 为对齐基准通过 Vitest 串行执行、15 分钟超时与 SDK 预构建机制对alibaba-group/opensandbox和alibaba-group/opensandbox-code-interpreter两个 SDK 的沙箱生命周期、命令/文件/会话 API、网络策略、卷挂载、沙箱池、凭据保险库、隔离会话、生命周期指标等能力进行了全链路严格验证。本文从 tests/javascript/README.md 出发将其环境变量表、运行命令完整继承并下沉到 base_e2e.ts 与各用例源码给出了可直接复制运行的实战步骤与可追溯的源码依据。开发者既可以按文执行整套回归也可以把单个用例文件当作 SDK API 的活的用法示例来阅读。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenSandbox JavaScript E2E 测试完全指南环境准备、运行流程与源码剖析【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxtests/javascript/README.md是 OpenSandbox 仓库中 JavaScript/TypeScript SDK 端到端E2E测试套件的使用说明。本指南以该文档为骨架结合仓库中真实测试代码tests/javascript/tests与工程配置package.json、vitest.config.ts系统讲解这套严格 E2E 测试的定位、前置条件、环境变量、完整运行流程以及每个测试模块所验证的 SDK 能力矩阵。读完本文你将能够在本地一键拉起 OpenSandbox 服务后运行全部 JS E2E 用例并能读懂每个用例背后对应的 SDK API 行为契约。一、测试套件定位与 Python/Java E2E 对齐的严格回归防线按照 tests/javascript/README.md 的说明该目录包含针对 JavaScript/TypeScript SDK 的严格 E2E 测试strict E2E tests并与仓库中OpenSandbox/tests/python、OpenSandbox/tests/java两套测试对齐。所谓严格体现在测试不是对 SDK 内部函数的单元测试而是真正连上一个正在运行的 OpenSandbox Server通过 sdks/sandbox/javascriptalibaba-group/opensandbox与 sdks/code-interpreter/javascriptalibaba-group/opensandbox-code-interpreter这两个 SDK 的公共 API 完成沙箱创建、命令执行、文件操作、网络策略、代码解释执行等全链路验证。从目录结构看套件由两部分组成工程配置文件package.jsonpnpm 项目定义与脚本、vitest.config.tsVitest 运行参数、tsconfig.jsonTypeScript 编译选项、eslint.config.mjs扁平化 ESLint 配置。9 个测试文件位于 tests/javascript/tests 下其中 base_e2e.ts 是共享测试基座其余 8 个.test.ts为 Vitest 用例文件。测试采用type: moduleESM风格编写依赖通过link:协议直接引用仓库内 SDK 源码目录见 package.json这意味着测试运行前会先构建 SDK保证被测代码与仓库当前源码一致而不是使用 npm 上发布的旧版本。二、前置条件Prerequisites原文档明确列出三条前置要求逐一说明前置条件要求说明Node.js经 nvm 安装 20SDK 的engines字段要求node 20这也是测试环境的下限pnpm9.xcorepack 或全局安装仓库锁定packageManager: pnpm9.15.0见 package.jsonOpenSandbox Server处于运行状态测试通过localhost:8080默认访问 Server API此外代码解释器相关用例依赖opensandbox/code-interpreter:latest镜像默认值因此建议先完成镜像拉取避免首个用例因镜像拉取超时而失败。三、环境变量与 Python 测试同名对齐这套测试遵循与 Python 测试相同的命名约定四个核心环境变量及其默认值如下默认值定义可对照 tests/javascript/tests/base_e2e.ts环境变量默认值作用OPENSANDBOX_TEST_DOMAINlocalhost:8080OpenSandbox Server 的域名与端口OPENSANDBOX_TEST_PROTOCOLhttp访问协议可设为https启用 TLSOPENSANDBOX_TEST_API_KEYe2e-test访问 Server 的 API KeyOPENSANDBOX_SANDBOX_DEFAULT_IMAGEopensandbox/code-interpreter:latest默认沙箱镜像从源码看这些变量在 base_e2e.ts 中通过process.env.XXX ?? DEFAULT模式读取即未设置时优雅回退到默认值方便本地零配置启动export const TEST_DOMAIN process.env.OPENSANDBOX_TEST_DOMAIN ?? DEFAULT_DOMAIN; export const TEST_PROTOCOL process.env.OPENSANDBOX_TEST_PROTOCOL ?? DEFAULT_PROTOCOL; export const TEST_API_KEY process.env.OPENSANDBOX_TEST_API_KEY ?? DEFAULT_API_KEY; export const TEST_IMAGE process.env.OPENSANDBOX_SANDBOX_DEFAULT_IMAGE ?? DEFAULT_IMAGE;除上述四个变量外从测试源码还可以发现一个可选开关OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP见 test_credential_vault_e2e.test.ts。只有当该变量被设置指向凭据保险库 E2E 目标主机的 IP时凭据保险库相关用例才会执行否则这些用例会被test.skip跳过。这一点在原 README 中未提及属于源码揭示的隐藏行为。四、完整运行流程从零到全部用例通过原文档给出了一套完整的命令行流程以下逐条展开说明其背后的工程含义。4.1 切换 Node.js 版本cd OpenSandbox/tests/javascript # Node 20 是必需的SDK engines: node 20 source ~/.nvm/nvm.sh nvm use 22OpenSandbox 仓库的 JS SDK 要求node 20而当前 Node.js 主版本线22 及以上均可使用。通过 nvm 切换版本可确保本地环境与 CI 一致。4.2 激活 pnpm 9.x# 确保 pnpm 可用仓库锁定 pnpm9.x corepack enable corepack prepare pnpm9.15.0 --activate仓库在 package.json 中通过packageManager: pnpm9.15.0字段锁定了 pnpm 版本同时声明了rollup、vite、esbuild等依赖的overrides覆盖见 package.json用于统一传递依赖版本、规避供应链解析差异。使用 corepack 激活的 pnpm 9.15.0 可以确保这些 overrides 按预期生效。4.3 安装测试依赖# 安装测试依赖vitest、typescript 等 pnpm installdevDependencies 包括vitest ^4.1.0、typescript ^5.7.2、vite ^6.4.3、eslint ^9.39.4与typescript-eslint ^8.59.0见 package.json。pnpm install会自动执行pretest钩子中的pnpm install --prefer-offlinepackage.json优先使用本地缓存以加速安装。4.4 运行测试# 运行测试同时会构建 SDK pnpm testpnpm test实际执行的是pnpm run prep:sdk pnpm exec vitest run见 package.json分两步prep:sdk构建 SDK执行pnpm -C ../../sdks install --prefer-offline pnpm -C ../../sdks run build:js即先安装 sdks 工作区依赖再构建alibaba-group/opensandbox与alibaba-group/opensandbox-code-interpreter两个 JS SDK。这正是测试同时构建 SDK的来源。vitest run执行用例以单次运行非 watch模式执行全部测试。4.5 关键运行参数源码级解读vitest.config.ts 定义了三个关键行为export default defineConfig({ test: { environment: node, // 这些 E2E 测试可能因 provider 不同而较慢 testTimeout: 15 * 60_000, hookTimeout: 15 * 60_000, // 保持执行顺序确定对齐 Python/Java E2E 套件的有序执行 sequence: { concurrent: false }, }, });environment: node在 Node.js 环境运行不加载浏览器环境符合 SDK 的纯服务端 API 特性。testTimeout与hookTimeout均为 15 分钟E2E 用例涉及真实的沙箱创建、镜像拉取与远程执行必须给足超时余量beforeAll/afterAll钩子同样有 15 分钟上限。sequence.concurrent: false串行执行所有用例保证执行顺序确定与 Python/Java E2E 套件的有序策略保持一致避免并发用例之间互相干扰例如共享端口、共享镜像。4.6 CI 模式仓库还提供了面向 CI 的脚本test:ci见 package.jsonpnpm test:ci它与本地模式的区别在于vitest run会同时输出默认报告器和 JUnit 报告JUnit XML 写入build/test-results/junit.xml便于 CI 平台如 Jenkins、GitLab CI解析测试结果。五、测试基座 base_e2e.ts 剖析base_e2e.ts 是全部用例的公共底座封装了三类能力1. 连接配置工厂base_e2e.ts#L31-L39export function createConnectionConfig(useServerProxy false): ConnectionConfig { return new ConnectionConfig({ domain: TEST_DOMAIN, protocol: TEST_PROTOCOL https ? https : http, apiKey: TEST_API_KEY, requestTimeoutSeconds: 180, useServerProxy }); }requestTimeoutSeconds: 180所有 SDK 请求的超时统一为 180 秒。useServerProxy为true时走 Server 代理模式。网络策略用例专门验证了两种模式直连与代理下 egress 端点行为的一致性见 test_sandbox_e2e.test.ts。2. 时间戳校验base_e2e.ts#L45-L51assertRecentTimestampMs断言时间戳落在now ± 180s容差内用于验证 SDK 返回的 metrics 时间戳是活的而非陈旧缓存。3. 端点端口校验base_e2e.ts#L53-L73assertEndpointHasPort兼容两种端点形态——host:port直连形式以及带路由的/sandboxes/{id}/proxy/{port}代理形式后者要求以/{expectedPort}结尾。这正好呼应了useServerProxy两种模式下端点格式的差异。六、测试模块能力矩阵每个文件验证什么以下结合源码逐模块梳理 8 个测试文件覆盖的能力方便读者按需挑选或定位用例。6.1 Sandbox 全生命周期与执行 APItest_sandbox_e2e.test.ts这是体量最大、覆盖面最广的用例文件约 1164 行包括生命周期Sandbox.create→isHealthy→getInfo→getMetrics→renew续期→Sandbox.connect按 ID 重连→kill校验entrypoint、metadata、expiresAt等字段test_sandbox_e2e.test.ts#L77-L122。Extensions 回传创建时传入extensions键值对getInfo后原样读回#L124-L150。网络策略NetworkPolicy创建时指定defaultAction: deny与 egress 白名单用curl实测pypi.org可达、github.com被拒再通过patchEgressRules热更新策略并验证反转效果。该用例在直连与 Server 代理两种模式下各跑一遍#L174-L264。卷挂载覆盖 host 目录只读/读写挂载、PVC 命名卷只读/读写挂载、PVC subPath 挂载五类场景验证沙箱内外文件读写双向可见性与只读保护#L266-L623。命令执行契约成功执行、workingDirectory指定工作目录、background后台运行、失败命令CommandExecError四类结果并借助ExecutionHandlers流式回调收集onStdout/onStderr/onResult/onInit/onExecutionComplete/onError事件#L643-L728。后台命令日志getCommandStatusgetBackgroundCommandLogs带游标分页拉取#L730-L759。命令级环境变量注入run(..., { envs })仅对单条命令生效#L761-L782。Bash 会话 APIcreateSession/runInSession/deleteSession验证会话内工作目录切换与export环境变量跨命令持久化#L784-L837。文件系统 APIcreateDirectories、getFileInfo、writeFiles支持字符串与Uint8Array字节、owner/group/mode、search、readFile含rangeHTTP Range 与offset/limit行读取、readBytes、readBytesStream异步迭代器流式读取、setPermissions、replaceContentsDetailed返回替换计数覆盖无匹配/多匹配/批量替换、moveFiles、deleteFiles、deleteDirectories#L839-L1038。中断命令interrupt(initId)终止运行中的长任务#L1040-L1097。Pause/Resume该用例目前被显式跳过return提前退出#L1099-L1101保留代码供参考。x-request-id 透传在ConnectionConfig中注入X-Request-ID请求头断言 Server 报错时SandboxApiException.requestId能原样回传便于日志追踪#L1142-L1164。6.2 Code Interpreter 多语言代码执行test_code_interpreter_e2e.test.ts围绕alibaba-group/opensandbox-code-interpreter的CodeInterpreter类验证上下文管理createContext/getContext/listContexts/deleteContext/deleteContexts支持按SupportedLanguages.PYTHON过滤#L179-L201。多语言执行Java、Python、Go、TypeScript 四语言codes.run验证 stdout、返回值result[0].text与EvalException错误语义#L203-L301。上下文隔离同一语言的多个 context 之间变量互不可见Python 变量在另一 context 中访问触发NameError#L303-L327。并发执行Python/Java/Go 三个 context 并行运行容忍 CI 抖动断言至少 2/3 成功#L329-L364。中断与错误处理codes.interrupt(initId)终止长任务伪造 ID 的中断必须抛错#L366-L405。值得注意的工程实践该文件实现了withRetry重试助手与ensureSandboxAlive健康检查针对terminated、other side closed、fetch failed、session is busy、UND_ERR_SOCKET等可重试错误自动重建沙箱#L92-L136显著降低长跑套件在网络抖动下的偶发失败率。6.3 客户端沙箱池test_sandbox_pool_e2e.test.ts验证SandboxPool的完整生命周期pool.start()预热 →snapshot()轮询至idleCount 1→acquire({ policy: AcquirePolicy.FAIL_FAST })获取并执行命令 →resize(0)releaseAllIdle()回收 → 空池时FAIL_FAST抛PoolEmptyException→ 降级AcquirePolicy.DIRECT_CREATE直接创建。状态存储使用InMemoryPoolStateStoretest_sandbox_pool_e2e.test.ts#L36-L89。该用例 5 分钟超时是对客户端侧沙箱池机制对应 osep 0005 设计的端到端背书。6.4 凭据保险库test_credential_vault_e2e.test.ts在设置OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP后启用验证sandbox.credentialVault.create支持bearer、basic、apiKey、customHeaders四类鉴权类型且返回的 state 载荷不泄露任何明文密钥同时验证占位符在 query、path、body 中的运行时替换test_credential_vault_e2e.test.ts#L36-L100。6.5 隔离会话test_isolated_session_e2e.test.ts通过extensions: { bootstrap.execd.isolation: enable }开启隔离能力先查询sandbox.isolation.capabilities()再验证会话的创建、查询、列表、后台运行轮询与删除create/get/list/getRunStatus/deletetest_isolated_session_e2e.test.ts#L36-L80。6.6 Sandbox Managertest_sandbox_manager_e2e.test.ts验证SandboxManager.create后的listSandboxInfos按状态、metadata 过滤分页与getSandboxInfo并用waitForState轮询等待目标状态如Running→ 过期回收覆盖多沙箱管理与状态机流转test_sandbox_manager_e2e.test.ts#L58-L80。6.7 生命周期指标test_lifecycle_metrics_e2e.test.ts直接向/v1/metrics/events端点 POST SDK 形态的sandbox.create事件断言返回 204随后用包装fetch的方式拦截 SDK 请求验证Sandbox.create会自动向生命周期 Server 上报sandbox.create指标test_lifecycle_metrics_e2e.test.ts#L27-L80。6.8 就绪等待诊断信息test_wait_until_ready_diagnostics.test.ts这是一个准单元测试用假对象注入失败的health.ping断言waitUntilReady超时抛出的SandboxReadyTimeoutException消息中包含最后一次健康检查错误、domain、useServerProxy等诊断上下文当 ping 持续返回false时消息中还会出现Health check returned false continuously.提示test_wait_until_ready_diagnostics.test.ts#L19-L78。七、代码质量配套TypeScript 严格模式与 ESLinttsconfig.json 开启strict: true、target/module: ES2022、moduleResolution: BundlernoEmit仅做类型检查allowImportingTsExtensions允许直接import ... from ./base_e2e.ts这种带扩展名导入测试代码中确实如此使用。eslint.config.mjs 采用typescript-eslint扁平化配置忽略node_modules、build与*.d.ts关闭no-explicit-any以适配 E2E 测试中的断言代码同时以^_前缀豁免未使用参数/变量保证pnpm lint--max-warnings 0零告警通过。八、常见问题与排查建议结合源码中内置的重试与诊断机制给出以下实操建议健康检查失败导致用例批量失败先确认 OpenSandbox Server 已启动且OPENSANDBOX_TEST_DOMAIN/OPENSANDBOX_TEST_API_KEY与 Server 实际配置一致若为网络抖动Code Interpreter 用例自带的withRetry/ensureSandboxAlive会自动重建沙箱重试。镜像相关失败确认OPENSANDBOX_SANDBOX_DEFAULT_IMAGE指向的镜像已存在testTimeout15 分钟足够覆盖首次镜像拉取但建议提前手动docker pull。用例执行顺序影响套件串行执行sequence.concurrent: false个别用例对共享资源如 PVC 卷opensandbox-e2e-pvc-test、host 目录/tmp/opensandbox-e2e/host-volume-test有隐式依赖请勿通过vitest --no-threads之外的并行参数运行。凭据保险库用例被跳过属正常未设置OPENSANDBOX_CREDENTIAL_VAULT_E2E_TARGET_IP时该模块用例全部skip这是设计行为而非失败。定位超时问题利用SandboxReadyTimeoutException消息中的最后一次健康检查错误 连接上下文domain/useServerProxy以及x-request-id透传能力可在 Server 日志中精准串联单次请求链路。九、结语OpenSandbox 的 JS E2E 测试套件以 tests/python 与 tests/java 为对齐基准通过 Vitest 串行执行、15 分钟超时与 SDK 预构建机制对alibaba-group/opensandbox和alibaba-group/opensandbox-code-interpreter两个 SDK 的沙箱生命周期、命令/文件/会话 API、网络策略、卷挂载、沙箱池、凭据保险库、隔离会话、生命周期指标等能力进行了全链路严格验证。本文从 tests/javascript/README.md 出发将其环境变量表、运行命令完整继承并下沉到 base_e2e.ts 与各用例源码给出了可直接复制运行的实战步骤与可追溯的源码依据。开发者既可以按文执行整套回归也可以把单个用例文件当作 SDK API 的活的用法示例来阅读。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
