CubeSandbox SDK 兼容性 E2E 用例开发参考领域划分、pytest Marker 规范与执行工作流【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox导读本文围绕 CubeSandbox 仓库中 tests/skills/sdk-e2e-cases/REFERENCE.md 展开系统讲解在tests/e2e/sdk_compat下编写、审查、运行 SDK 兼容性 E2E 用例的完整规范从行为领域Domain划分、模块级 pytest Marker 模板、优先级与能力标记体系到模板/创建选项的注入方式再到一套可复制的执行命令与结果上报预期。读者在掌握本文后能够为 CubeSandbox 与 E2B 双后端兼容测试贡献新的用例、正确审查既有用例的契约质量并按优先级与后端组合精准运行 live E2E 验证。仓库中的 SKILL.md 与 README.md 是本文的配套阅读材料。领域映射把行为归入正确的目录REFERENCE.md要求除非新行为具有清晰的 API 或能力边界否则一律使用既有领域。这是保证用例可维护、可检索、可并行运行的前提。commands/ command stdout/stderr, exit code, timeout, environment concurrency/ multi-sandbox isolation and concurrent behavior filesystem/ file API behavior and shell interoperability host-mount/ host-directory mount extension, allowlist, and boundary behavior lifecycle/ create, connect, pause/resume, kill, platform lifecycle network/ network policy, public access, traffic access token run_code/ Code Interpreter output, errors, stateful kernel behavior该映射与仓库中tests/e2e/sdk_compat/cases/目录结构一一对应另有auth/、volume/、templates/、framework/等扩展领域例如cases/lifecycle/create/info、connect、create options、pause/resume、kill以及平台管理的 auto-pause/auto-resume/auto-killcases/commands/stdout/stderr、exit code、环境变量、特殊字符、多行输出、命令不存在等cases/network/创建期网络策略allow/deny、公网访问、DNS allow、L7 egress、mask_request_host与运行中策略原位更新cases/host-mount/宿主机目录挂载扩展、边界行为与快照/回滚/克隆语义。从case-authoring.md可知只有在行为拥有独立 API、能力边界或执行范围时才应创建新领域例如proxy/、metadata/、errors/被列为未来可选领域。领域划分的落地依据可在 capabilities.py 的能力常量中交叉验证lifecycle、commands、filesystem、filesystem_extended、run_code是双后端公共能力host_mount、volume_plugin、platform_lifecycle、rollback_clone、auth_simple_key等则是 CubeSandbox 独有能力。模块 Marker 模板一套可复用的头部每个用例模块或单个测试都应携带统一的 marker 组合标明其执行类别、兼容层级、优先级与所属领域。REFERENCE.md给出的模板如下import pytest from framework.capabilities import COMMANDS pytestmark [ pytest.mark.e2e, pytest.mark.sdk_compat, pytest.mark.p1, pytest.mark.commands, pytest.mark.requires_capability(COMMANDS), ]实际用例的写法与之一致例如 test_create.pypytestmark [ pytest.mark.e2e, pytest.mark.sdk_compat, pytest.mark.lifecycle, pytest.mark.p0, ]所有 marker 都在 pytest.ini 中注册未注册的 marker 会触发PytestUnknownMarkWarning因此新增 marker 时必须同步登记。conftest.py在pytest_configure阶段也会补充注册sdk_compat、requires_capability、sandbox_create_options、sandbox_template_id、requires_code_interpreter、requires_internet、requires_cubeproxy、auth等关键 marker。模块级与函数级 marker 的取舍模块级pytestmark适用于整个文件共享的标记如领域、优先级、公共能力。函数级适用于单个用例的标记如pytest.mark.smoke见test_create_returns_usable_sandbox、requires_code_interpreter、sandbox_create_options、sandbox_template_id。优先级与环境 Marker 全解REFERENCE.md归纳了常用的优先级与运行环境 marker其语义在README.md与pytest.ini中进一步明确smoke最小化 live 环境校验用于快速探测环境是否可用p0稳定的 PR 门禁覆盖每次 SDK 兼容性门禁都应运行p1每日兼容性回归p2/p3更广泛、更慢或发布质量release qualification级别的覆盖slow耗时超过常规 PR 预算的用例requires_internet需要沙箱具备公网出口conftest.py中gate_internet_testsfixture 会在设置SDK_E2E_SKIP_INTERNET_TESTS时自动跳过requires_cubeproxy依赖 CubeProxy 路由或平台生命周期cube-proxy lifecycle-manager 协调未设置SDK_E2E_PLATFORM_LIFECYCLEtrue时被sdk_sandboxfixture 跳过requires_code_interpreter需要暴露 Code Interpreter / Jupyter 的模板host_mount宿主机目录挂载扩展需与pytest.mark.requires_capability(host_mount)配对使用。能力 marker 的底层门控requires_capability(name)是双后端兼容测试的核心机制。在conftest.py的sdk_sandboxfixture 中会遍历节点上的requires_capabilitymarker用 capabilities.py 的capabilities_for_backend(backend)判断当前后端是否支持for marker in request.node.iter_markers(requires_capability): capability marker.args[0] if capability not in capabilities_for_backend(sdk_backend): pytest.skip(fbackend {sdk_backend!r} does not support capability {capability!r})capabilities.py定义了COMMON_CAPABILITIES双后端公共能力以及E2B_CAPABILITIES、CUBESANDBOX_CAPABILITIES两套后端能力集BACKEND_CAPABILITIES字典是能力集映射的唯一事实来源。这意味着共享用例不得在函数体内用后端分支隐藏差异而应通过能力 marker 表达支持边界详见 framework-design.md 与 case-authoring.md。模板与创建选项如何在用例中注入创建契约模板选择除非用例需要特定模板能力如 Code Interpreter 内核、额外暴露端口否则一律使用默认的CUBE_TEMPLATE_ID可通过--cube-template-id或CUBE_TEMPLATE_ID环境变量指定。需要特定模板时用sandbox_template_idmarker 覆盖pytest.mark.sandbox_template_id(tpl-code-interpreter-xxxxxxxx) pytest.mark.requires_code_interpreter def test_kernel_state(sdk_sandbox): ...创建选项sandbox_create_options用于传递与测试契约直接相关的、后端无关的创建参数例如timeout、network、env_vars、lifecyclepytestmark [ pytest.mark.e2e, pytest.mark.sdk_compat, pytest.mark.p1, pytest.mark.lifecycle, pytest.mark.sandbox_create_options(timeout120), ]其实现细节在conftest.py的_create_options_for_node中多个 marker 的 kwargs 会被合并后者覆盖前者也接受单个 dict 作为位置参数。网络策略类用例按case-authoring.md的建议直接传入 wire-shaped 的network字典pytest.mark.requires_capability(NETWORK_ALLOW_DENY) pytest.mark.requires_internet pytest.mark.sandbox_create_options( network{ allow_out: [8.8.8.8/32], deny_out: [0.0.0.0/0], } )注意不要在共享用例中硬编码模板 IDsandbox_template_id只接受一个非空字符串参数非法用法会被_template_id_for_node抛错。编写清单新用例落地前的逐项核对REFERENCE.md的 Authoring Checklist 是写用例时的自检表结合case-authoring.md与README.md可得到完整落地指引行为被分配到正确的领域目录测试名准确描述契约与预期结果如test_create_returns_usable_sandbox、test_pause_sets_state_paused共享行为不被后端专属分支守卫——后端差异一律走requires_capability或环境 marker不支持的先决条件使用能力或环境 marker 表达如requires_internet、requires_code_interpreter、requires_cubeproxy、host_mount优先使用既有 fixtures 与 helpers而非自创新抽象sdk_sandbox、sdk_e2e_config、sdk_backend、sandbox_create_options、sandbox_template_id断言包含有用的诊断信息stdout/stderr、sandbox ID、状态码、URL、简短响应片段但不暴露密钥与 traffic access token通过既有 fixtures 完成确定性的资源清理若用例自行创建 resumed adapter须在finally中close()外部依赖被显式标记且可配置例如公网探测目标SDK_E2E_TCP_TARGET_IP、L7 echo 服务SDK_E2E_L7_ECHO_HOST新增环境变量同步加入env.example与 README 文档新增 marker 在pytest.ini中登记注册。case-authoring.md还补充了两条关键实践断言可观测结果而非控制面状态state running只是控制面结果不代表数据面就绪应使用wait_until_running等 helper并在调查就绪竞争时单独记录首次数据面操作。生命周期用例应先播种状态、再转换、后验证例如先run_code(value 41)与write_file(/tmp/checkpoint, before)pause/resume 后再验证value 1 42且文件内容保持为before。网络用例使用被测协议本身TCP 用socket.connect_exUDP/DNS 发送 DNS 查询并等待匹配响应HTTP/HTTPS 断言状态码与响应体L7 验证 host/path/method/SNI/规则顺序/inject 行为。仅凭 TCP 连通不能证明 HTTP 或 L7 策略生效。审查清单让用例为正确的缺陷而失败REFERENCE.md的 Review Checklist 是评审既有变更时的核心问题集该测试是否针对正确的产品缺陷失败是否避免了宽泛的异常吞没broad exception swallowing需要轮询时是否避免了固定 sleepfixed sleeps——应使用wait_until_running、wait_for_platform_pause、wait_for_platform_destroy等轮询型 helperlive E2E 成本是否与其优先级 marker 匹配smokep0p1p2/p3是否避免在日志中打印CUBE_API_KEY、E2B_API_KEY、traffic access token 或敏感基础设施细节是否保留了 setup/call 失败与 teardown 清理失败之间的区分——conftest.py的_test_failed只把 setup/call 阶段的失败视为失败SDK_E2E_KEEP_SANDBOX_ON_FAILUREtrue只保留这类失败用例的沙箱passed/skipped 及通过自有 helper 直接建箱的边界用例始终被清理文档是否与实际命令、marker、环境行为保持一致SKILL.md的 Review Workflow 还要求检查用例断言的是产品/SDK 契约而非偶发实现细节running语义是数据面可用创建出的沙箱通过既有 fixtures 清理安全性不打印密钥、token、机器 IP、敏感 header可维护性优先既有 helper、marker 可读、用例聚焦。执行命令从收集到双后端回归REFERENCE.md给出了从收集到调试的完整命令集。所有 live 命令都应在tests/e2e/sdk_compat目录下执行且需要先设置CUBE_API_URL与CUBE_TEMPLATE_ID。结构或 marker 变更后先收集cd tests/e2e/sdk_compat pytest --collect-only -q收集不触发 live 环境。未加--run-e2e时套件只运行打上framework标记的封闭式纯逻辑单元测试其余 live 用例全部被跳过见conftest.py的pytest_collection_modifyitems保证 PR 门禁封闭性。参数化用例可先用--collect-only -q查看精确的 node ID 再定向运行。定向 live 验证pytest --run-e2e cases/lifecycle/test_create.py -q pytest --run-e2e cases/network/test_policy.py -q更细粒度可指定文件、用例函数乃至参数化节点pytest --run-e2e cases/lifecycle/test_pause_resume.py::test_pause_sets_state_paused pytest --run-e2e --sdk-e2e-backendscubesandbox \ cases/lifecycle/test_pause_resume.py::test_pause_sets_state_paused[cubesandbox]按优先级选择pytest --run-e2e -m smoke or p0 pytest --run-e2e -m p1 and not slowREADME.md给出了按场景划分的推荐范围PR 门禁用-m smoke or p0 --sdk-e2e-backendscubesandbox每日双 SDK 回归用SDK_E2E_BACKENDSe2b,cubesandbox pytest --run-e2e -m p0 or p1平台生命周期回归用SDK_E2E_PLATFORM_LIFECYCLEtrue pytest --run-e2e -k lifecycle -m p1 and slowVolume Plugin 回归用pytest --run-e2e -m volume --sdk-e2e-backendscubesandbox。双后端兼容运行仅在两个 SDK 环境都配置好时运行SDK_E2E_BACKENDSe2b,cubesandbox pytest --run-e2e -qe2b后端需要E2B_API_KEY自托管 HTTPS 沙箱端点还需通过SSL_CERT_FILE提供可信 CA。后端列表会通过pytest_generate_tests对sdk_backendfixture 参数化每个后端独立跑一遍共享用例。调试选项SDK_E2E_TRACEtrue pytest --run-e2e cases/lifecycle/test_create.py -q SDK_E2E_KEEP_SANDBOX_ON_FAILUREtrue pytest --run-e2e cases/network/test_policy.py -qSDK_E2E_TRACEtrue等价于--sdk-e2e-trace会打印每次 SDK adapter 操作并附带 tracetrace 模式可能把非机密的命令/代码输出暴露到终端但 JSONL 脱敏在两种模式下都保持开启。SDK_E2E_KEEP_SANDBOX_ON_FAILUREtrue仅用于调试失败会保留失败用例的沙箱便于现场排查排查后需手动清理。创建容量重试相关变量SDK_E2E_CREATE_CAPACITY_RETRIES、_BACKOFF、_BACKOFF_MAX、_BUDGET用于应对调度器瞬时130597: no more resource错误并行运行时conftest.py会按 xdist worker 数等比放大重试次数与预算。并行注意SDK_E2E_WORKERS或-n显式开启 pytest-xdist 并行默认串行以避免压垮本机共享的 CubeAPI/scheduler。每个测试都会创建自己独立的按 UUID 命名的沙箱create 路径已带容量重试抖动因此并行 worker 不会锁定步调重试。输出预期向用户汇报时的必填项运行或交付用例变更后REFERENCE.md要求汇报结果时包含变更的文件新增/修改的用例、fixtures、docs、pytest.ini、env.example已运行的验证命令及是否通过未运行的 live E2E 命令及原因例如未配置 E2B 环境、未设置SDK_E2E_PLATFORM_LIFECYCLEtrue、无公网出口剩余风险尤其是环境假设与后端特定覆盖缺口。这一输出预期与 SKILL.md 的 Execution Workflow 一致live 运行前须确认所需环境变量已按文档设置并有意识启用SDK_E2E_KEEP_SANDBOX_ON_FAILUREtrue仅在调试时使用。框架佐证Fixture 生命周期与能力门控的实现落地REFERENCE.md中的 marker 与模板规范并非纸面约定其执行路径在 conftest.py 中有完整实现。sdk_sandboxfixture 的执行顺序是加载 pytest 配置、环境变量与.envshell 中已导出的值优先于.env--run-e2e开启时执行会话级 preflight校验CUBE_TEMPLATE_ID、GET /health、模板ready/active/available状态平台生命周期模式还会探测 CubeProxy admin heartbeat检查能力与平台 markerrequires_capability、requires_code_interpreter、requires_cubeproxy、volume并视情况 skip合并sandbox_create_options通过create_adapter_with_capacity_retry创建沙箱并附加TraceCollectoryield adapter 给测试体依据SDK_E2E_KEEP_SANDBOX_ON_FAILURE决定保留还是清理清理失败时回退到DELETE /sandboxes/{sandboxID}见 README.md 的 Cleanup 章节。报告方面套件将 JSONL 事件写入SDK_E2E_REPORT_DIR默认reports/sdk-dual串行时写events.jsonlxdist 下每个 worker 写events-gw0.jsonl、events-gw1.jsonl等。事件类型包括preflight_passed/failed、sandbox_created、sandbox_cleanup/sandbox_kept、test_result失败的test_result事件包含错误信息、尽力而为的sandbox_info以及有界 SDK 操作 trace密钥与敏感值脱敏、大值截断、文件内容只以长度表示。需要标准 HTML/JUnit 报告时显式传入 pytest-html 与 pytest-junitxml 选项即可。小结REFERENCE.md是 CubeSandbox SDK 兼容性 E2E 工作的速查参考它用领域映射约束用例归属用模块 marker 模板统一用例头部用优先级与能力 marker 表达执行成本与后端支持边界用编写/审查双清单保证契约质量用一套可复制的执行命令串起收集、定向、分级、双后端与调试场景。结合 case-authoring.md、framework-design.md 与 conftest.py 的实现读者可以在此基础上稳定地产出为正确缺陷而失败、跨后端可移植、成本与优先级匹配的高质量 E2E 用例。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考