youki Rust OCI 集成测试(contest)框架详解:从运行到编写自定义用例
youki Rust OCI 集成测试(contest)框架详解:从运行到编写自定义用例
youki(README.md)是一个用 Rust 编写、兼容 OCI 规范的容器运行时。本文围绕 docs/src/developer/e2e/rust_oci_test.md 文档,深入讲解 youki 自研的低层容器运行时集成测试体系 contest:包括它的定位与架构、一行命令的运行方式、基于测试框架的四步式用例编写流程,并配合源码佐证其底层实现原理。读完本文,你将能够在 youki 仓库中定位测试代码、运行整套或部分测试,并独立编写、注册一个新的 contest 测试用例。
一、contest:验证低层运行时行为的原始集成测试
1.1 定位:从运行时外部与内部双重视角验证
youki 的集成测试体系分为两条线:基于 OCI runtime-tools 的 test-oci 与本文主角 contest(全称 Rust OCI 集成测试,见 justfile)。rust_oci_test.md 明确指出:
This is youki's original integration to verify the behavior of the low-level container runtime.
也就是说,contest 是 youki 自有的、用于验证低层容器运行时行为的集成测试,它关注的是 OCI 规范中描述的各种限制与约束(readonly 路径、设备、cgroup、seccomp、namespace、生命周期等)是否被运行时真实地施加到了容器进程上。测试套件分为两大类,对应两种验证视角(对应实现见 test_utils.rs):
- 容器外验证(test_outside_container):从宿主机侧创建、启动、查询状态、kill、删除容器,验证运行时对外部命令(create/start/state/kill/delete)的响应正确性,其作用类似 OCI runtime-tools 中的
RuntimeOutsideValidate; - 容器内验证(test_inside_container):把测试用的
runtimetest二进制自动部署进容器,让验证逻辑在容器进程内部运行,从“被约束方”的视角确认约束是否真的生效,类似 OCI runtime-tools 中的RuntimeInsideValidate。
1.2 架构概览:TestManager → TestGroup → Test 的分层管控
contest 的架构可以用下图概括:TestManager 统一管理多个 TestGroup,每个 TestGroup 内注册若干 TestCase;每个用例执行时,框架会为该用例创建独立的测试容器,并在容器内自动部署 runtimetest 执行验证逻辑。
该架构在代码中对应三个核心抽象(位于 tests/contest/test_framework/):
| 抽象 | 职责 | 源码位置 |
|---|---|---|
TestManager |
持有全部测试组,支持并行调度、筛选运行与清理回调 | test_manager.rs |
TestGroup |
测试组,提供命名空间并控制组内用例的并行/串行 | test_group.rs |
Test / ConditionalTest |
单个用例,后者带 can_run() 环境预检 |
test.rs、conditional_test.rs |
三个层次通过 Testable / TestableGroup trait 解耦(定义见 testable.rs),使用者既可以基于内置结构快速编写用例,也可以自定义结构实现 trait 来获得精细的串行控制——例如容器生命周期测试(create 必须先于 start)就是通过自定义 ContainerLifecycle 结构实现的(见 container_lifecycle.rs)。
二、如何运行 contest 测试
2.1 一条命令:just test-contest
仓库使用 just 作为任务运行器(配方定义在 justfile):
just test-contest
该配方展开后的实际动作是:
sudo /data/.../scripts/contest.sh /data/.../youki
即先构建 release 版 youki 与 contest,再以 sudo 调用 scripts/contest.sh 执行整套测试。注意需要 root 权限:因为测试要创建容器、操作 cgroup、挂载 rootfs 等。
contest.sh 的核心逻辑(scripts/contest.sh):
- 若仓库根目录不存在
bundle.tar.gz,则按uname -m选择架构对应的 bundle 压缩包(如bundle-aarch64.tar.gz),否则回退到默认的 x86_64 bundle; - 以
contest run --runtime <runtime> --runtimetest <root>/runtimetest调用测试二进制; - 全部输出写入
test.log,最后统计not ok行数,若存在失败则以非零状态退出。
2.2 手动运行与筛选
contest 二进制支持 run 与 list 两个子命令(main.rs):
--runtime <PATH>:必选,指定被测试的运行时可执行文件(youki 或 runc 等);--runtimetest <PATH>:必选,指定runtimetest二进制路径;-t/--tests:可选,筛选要运行的测试组/用例,格式为group1::test1,test3 group2 group3::test5(组内用逗号分隔用例、组间用空格分隔)。
例如仅运行 example 组中的 hello world 用例:
sudo ./contest run --runtime ./youki --runtimetest ./runtimetest -t example::hello_world
列出全部测试组:
./contest list
还可借助 justfile 中的 contest-list 配方(justfile)。此外,scripts/contest.sh 支持把 RUNTIME_KIND=runc 环境变量注入来对 runc 运行同一套测试(见 support.rs 与 justfile),用于交叉验证。
2.3 测试结果语义
TestManager 打印结果时使用 TAP 风格输出(test_manager.rs):每个用例打印 N / M : 名称 : ok/not ok/skipped,TestResult 三态定义在 testable.rs:
Passed:通过;Skipped(String):环境不支持而跳过(例如宿主内核未启用某些 cgroup 控制器时,相关用例应跳过而非失败);Failed(Error):失败,携带错误原因。
三、如何编写一个 contest 测试用例
原文档以 hello_world 示例为主线,给出四步流程。下面结合完整源码逐一展开。示例完整代码位于 hello_world.rs。
第一步:构造待验证的 OCI Runtime Spec
框架会自动把 runtimetest 放进容器,因此你只需在 Spec 中把进程命令写成 runtimetest <测试名>,让验证逻辑在容器内执行:
use oci_spec::runtime::{ProcessBuilder, Spec, SpecBuilder};
fn create_spec() -> Result<Spec> {
SpecBuilder::default()
.process(
ProcessBuilder::default()
.args(
["runtimetest", "hello_world"]
.iter()
.map(|s| s.to_string())
.collect::<Vec<String>>(),
)
.build()?,
)
.build()
.context("failed to create spec")
}
代码中 runtimetest 就是 argv0],hello_world 是第一个参数。runtimetest 的 main 会读取第一个参数,并分派到 [main.rs 中对应的验证函数。Spec 构建使用 oci-spec crate 的 builder 模式,可链式追加 root、mounts、linux(namespaces/cgroups/seccomp 等)字段,构成你希望验证的约束组合。
第二步:编写返回 TestResult 的测试函数
use test_framework::{TestResult, test_result};
use crate::utils::test_inside_container;
use crate::utils::test_utils::CreateOptions;
fn example_test() -> TestResult {
let spec = test_result!(create_spec());
test_inside_container(&spec, &CreateOptions::default(), &|_| Ok(()))
}
这里的关键是 test_inside_container(test_utils.rs),它完成了整个"容器内验证"流程:
prepare_bundle():在临时目录中解压 bundle 压缩包、生成默认config.json(support.rs),bundle 目录随TempDir析构自动清理;set_config():把你构造的 Spec 保存为 bundle 的config.json;- 将
runtimetest二进制复制到 rootfs 的/bin/runtimetest,并把 Spec 另存到 rootfs 的/config.json——这正是 runtimetest 读取 spec 的路径(main.rs); - 执行
create→ 短暂等待 →start→ 收集容器输出; - 检查容器 stderr:只要 stderr 非空即判失败(runtimetest 的验证函数全部通过
eprintln!上报错误),stdout 非空则打印警告; - 查询状态确认容器已
stopped,随后清理。
test_result! 宏把 Result<T, E> 转换为 TestResult:成功即 Passed,失败即 Failed(err)(定义见 testable.rs)。
提示:对于不需要容器内验证、只验证运行时外部行为的用例,可直接使用
test_outside_container(test_utils.rs),它一次性完成建 bundle、create、取 state、kill、delete。
第三步:创建 TestGroup 并注册用例
use test_framework::{Test, TestGroup};
pub fn get_example_test() -> TestGroup {
let mut test_group = TestGroup::new("example");
let test1 = Test::new("hello world", Box::new(example_test));
test_group.add(vec![Box::new(test1)]);
test_group
}
TestGroup::new("example"):创建名为example的测试组,默认parallel = true,即组内用例可并行执行(test_group.rs);- 若用例间存在状态依赖,可用
set_nonparallel()关闭并行; Test::new(name, Box<Fn() -> TestResult>):注册单个用例(test.rs);- 组内用例以
BTreeMap按名称存放,同名用例会相互覆盖。
如需条件执行,可改用 ConditionalTest::new(name, check_fn, test_fn)——check_fn 返回 false 时用例被跳过而非失败(conditional_test.rs)。
第四步:把 TestGroup 注册到 TestManager
在 main.rs 中,获取测试组实例并加入 TestManager:
let mut tm = TestManager::new();
let example = get_example_test();
tm.add_test_group(Box::new(example));
TestManager::add_test_group 以组名为 key 存入 BTreeMap(test_manager.rs)。整个 main 会注册数十个测试组,覆盖 cgroups(cpu/memory/pids)、seccomp、hooks、生命周期、exec、update、checkpoint/restore 等场景,并注册一个 cgroup v2 清理回调 cgroups::cleanup_v2(main.rs),确保测试后系统恢复原状。
第五步:编写容器内的验证逻辑(runtimetest 侧)
Spec 中指定的 runtimetest hello_world 由 runtimetest/src/main.rs 分派:
fn main() {
let spec = get_spec();
let args: Vec<String> = env::args().collect();
let execute_test = match args.get(1) {
Some(execute_test) => execute_test.to_string(),
None => return eprintln!("error due to execute test name not found"),
};
match &*execute_test {
"hello_world" => tests::hello_world(&spec),
// 其余用例分支:readonly_paths、masked_paths、seccomp、sysctl、devices ...
_ => eprintln!("error due to unexpected execute test name: {execute_test}"),
}
}
对应的验证函数在 tests.rs:
pub fn hello_world(_spec: &Spec) {
println!("Hello world");
}
可见 hello_world 本身只是"容器能跑起来"的冒烟测试:只要容器进程正常启动并执行 runtimetest,用例即通过。真正的约束验证(例如 readonly paths 检查只读语义、devices 校验设备类型与主次设备号、seccomp 验证 getcwd 被 EPERM 拒绝等)遵循同样的模式:读取 /config.json 中的 Spec,逐项在容器内自检,不一致时 eprintln! 输出错误。
四、runtimetest:必须在容器内可运行的静态链接二进制
runtimetest 是 contest 体系的执行核心,runtimetest.md 对它做了专门说明。它提供的是一个在容器进程内部运行的二进制,用于验证运行时施加到容器上的限制是否真的被遵守;它逐个运行测试,失败项打印到 stderr。
4.1 为什么必须静态链接
容器的 rootfs 内通常没有 /lib64/ld-linux-x86-64.so 等动态加载器。如果 runtimetest 按默认方式动态链接,编译产物会带有程序解释器 /lib64/ld-linux-x86-64.so.2,进入容器后因找不到动态加载器而无法启动。因此 runtimetest 必须静态链接到 crt0。
4.2 独立工作区避免双重编译
runtimetest 最初放在 youki 全部 crate 的公共工作区中,但很快暴露出编译效率问题(runtimetest.md):
- 除 runtimetest 外的所有包都以动态链接编译;
- runtimetest 需要静态链接;
- 而 runtimetest 依赖
oci-spec、nix等与工作区其他包共用的 crate,导致这些依赖及其传递依赖要分别以动态/静态方式各编译一次,开发期编译耗时严重。
解决方法是把 runtimetest 从公共工作区剥离成独立 crate(runtimetest/Cargo.toml),让它拥有独立的 target/ 目录存放静态编译产物;公共工作区保留自己的 target/。这样增量开发时只需重编发生变更的 crate(runtimetest 或集成测试),依赖无需重复编译。
4.3 如何判断二进制能否在容器内运行
方法一:检查程序解释器
readelf -l path/to/binary | grep "program interpreter"
输出 [Requesting program interpreter: /lib64/ld-linux-x86-64.so.2] 表示动态链接、不可在容器内运行;无任何输出则表示无需解释器,可在容器内运行。
方法二:使用 file 命令
file path/to/binary
- 输出含
dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2→ 不可在容器内运行; - 输出
statically linked(且无 interpreter 字段)→ 可在容器内运行。
五、从示例到实战:仓库中真实用例的写法参考
contest 目录下已经沉淀了大量覆盖不同 OCI 特性的用例,是编写新用例的最佳范本。几个典型代表:
- cgroup v2 CPU 限额:update/cpu.rs 中通过
LinuxCpuBuilder构造period/quota/shares,配合test_outside_container调用运行时的update命令,再读取 cgroup 文件校验;文件头部还专门注释了 cpu.shares → cgroup v2 cpu.weight 的换算公式与 libcgroups 实现(crates/libcgroups/src/v2/cpu.rs)的对应关系; - 容器生命周期:container_lifecycle.rs 自定义
TestableGroup,把create → start → state → kill → delete强制为串行步骤,同时用 RAII 的NetnsGuard管理外部网络命名空间的创建与回收; - namespace 类型:ns_itype_test.rs 等用例验证运行时对 OCI namespaces 声明的处理;
- seccomp:seccomp/mod.rs 配合容器内验证函数
validate_seccomp(tests.rs)验证getcwd系统调用按策略被拒绝(EPERM)。
在新增用例时,建议遵循 contest/README.md 中总结的工作流:新建 src/tests/<名称>/ 目录 → 编写环境预检(can_run,避免在不支持的宿主机上误报失败)→ 用 builder 构造 Spec → 编写测试函数并导出 get_xxx_test() → 在 mod.rs 中 pub use → 在 main.rs 中 import 并注册到 TestManager → 先单独跑、再整组跑、最后对 runc 交叉验证 → 确认测试后系统状态已还原。
六、常见陷阱与注意事项
- create 后必须
wait而非wait_with_output:运行时进程会 fork 出容器进程并持续运行等待start,若对 create 直接wait_with_output会挂起;用 Ctrl+C 中断会导致 /tmp、cgroup 目录残留(contest/README.md); - kill/state 命令必须 wait:这些命令异步操作目录,若不等待其完成,
TempDir析构删除临时目录时会产生竞态,导致目录被重建等诡异问题; - 区分"跳过"与"失败":宿主内核缺少某 cgroup 控制器时应让用例
Skipped,而不是Failed; - 静态链接验证:新增验证逻辑后,务必用上文
readelf/file方法确认 runtimetest 产物仍是静态链接,否则测试会在容器内因找不到解释器而失败。
结语
contest 是 youki 生态中"自证合规"的关键一环:它以 OCI 规范为纲,以自研 test_framework 为骨架,以静态链接的 runtimetest 为容器内探针,将"运行时是否正确施加约束"变成可批量、可筛选、可并行执行的确定性检查。理解了本文的架构、运行方式与四步编写流程,你就可以在 tests/contest/ 目录下为新的 OCI 特性快速补充验证用例,并借助 just test-contest 或 contest run -t 精确回归。
