企业官网建设流程全解析

• 云原生
• 微服务

本指南围绕 Spin 仓库中的 test-codegen-macro 声明式过程宏展开，讲解它如何基于tests/runtime-tests/tests的目录结构自动生成一批#[test]测试函数，从而让开发者在新增一个运行时测试时只需添加测试目录与spin.toml清单，而无需手写对应的测试函数。读完本文，你将掌握该宏的输入语法（ignore列表）、生成逻辑（snake_case 命名、extern-dependencies-testsfeature 门控）、它与运行时测试协议（200/500 +error.txt）的配合方式，以及如何在 Spin 的测试套件中扩展新的运行时测试用例。

一、背景：Spin 运行时测试与"测试函数重复编写"问题

Spin 是一个构建与运行 WebAssembly serverless 应用的开源开发者工具。在其测试体系中，有一类专门验证"运行时行为"的测试，即 runtime tests。根据 tests/runtime-tests/README.md 的说明，运行时测试旨在验证"一个有效的 Spin 清单（spin.toml）与若干符合 Spin 规范的 WebAssembly 二进制组合起来，能够按预期运行或在预期情况下失败"，它不属于完整端到端集成测试，因此不关心 CLI 参数、导致 Spin 无法启动 HTTP 服务器的失败场景等。

在 tests/runtime-tests/tests 目录下，每个子目录代表一个运行时测试用例（如http-no-trailing-slash、internal-http、outbound-mysql、wasi-key-value等），每个子目录至少包含一个spin.toml清单，可选包含error.txt（预期失败时的错误匹配文本）和services（所需外部服务列表）。

问题随之而来：如果每个测试目录都要在测试代码中手写一个对应的#[test] fn xxx() { ... }，那么新增一个运行时测试时就必须同时改两处——添加目录 + 添加函数，二者极易失步。test-codegen-macro 正是为了解决这一重复劳动而存在的。

二、宏的核心职责：从目录结构生成测试函数

README 对宏的定位描述得很精炼："A macro for automatically producing#[test]annotated functions based on file directory structure. This is used by the runtime tests so that when adding a runtime test, you're not required to also add a test function corresponding to that runtime test."——即"基于文件目录结构自动生成带#[test]注解的函数；它被运行时测试使用，这样当你新增一个运行时测试时，无需再添加与该运行时测试对应的测试函数"。

该宏是一个声明式过程宏（#[proc_macro]），入口为 crates/test-codegen-macro/src/lib.rs 中的codegen_runtime_tests：

/// This macro generates the `#[test]` functions for the runtime tests. #[proc_macro] pub fn codegen_runtime_tests(input: TokenStream) -> TokenStream {

它在编译期完成以下工作：

1. 通过env!("CARGO_MANIFEST_DIR")定位宏所在 crate 的清单目录，再拼接../../tests/runtime-tests/tests，得到运行时测试目录的绝对路径（见 lib.rs）。
2. 用std::fs::read_dir遍历该目录下每一个子目录（非目录项会被跳过，见 lib.rs）。
3. 对每个子目录：
   • 检查目录下是否存在services文件（entry.path().join("services").exists()），据此决定是否添加#[cfg(feature = "extern-dependencies-tests")]属性（见 lib.rs）；
   • 检查该测试名是否出现在ignore列表中，若是则添加#[ignore]属性；
   • 将目录名通过to_snake_case()（来自heckcrate）转换为 Rust 标识符作为测试函数名（见 lib.rs）；
   • 生成一个调用run(PathBuf::from(测试目录绝对路径).join(目录名))的#[test]函数。
4. 把所有生成的函数拼接成一个TokenStream返回（quote::quote!(#(#tests)*)）。

每个测试目录生成的代码形如：

#[test] fn outbound_mysql() { run(::std::path::PathBuf::from("/.../tests/runtime-tests/tests").join("outbound-mysql")) }

其中run函数由宏的调用方（测试模块）提供，负责真正启动运行时并执行测试，详见下文第三节。

三、宏的调用方式：ignore列表与run回调

该宏的唯一公开入口在 tests/runtime.rs，这是 Spin 根测试套件（cargo test）中运行全部运行时测试的模块：

/// Run the tests found in `tests/runtime-tests` directory. mod runtime_tests { use std::path::PathBuf; use testing_framework::runtimes::in_process_spin::InProcessSpin; // The macro inspects the tests directory and // generates individual tests for each one. test_codegen_macro::codegen_runtime_tests!( ignore: [ // This test is flaky. Often gets "Connection reset by peer" errors. // https://github.com/spinframework/spin/issues/2265 "outbound-postgres", "outbound-postgres-variable-permission" ] ); fn run(test_path: PathBuf) { let config = runtime_tests::RuntimeTestConfig { test_path, runtime_config: (), on_error: testing_framework::OnTestError::Panic, }; runtime_tests::RuntimeTest::<InProcessSpin>::bootstrap(config) .expect("failed to bootstrap runtime tests tests") .run(); } ... }

从这段真实调用代码可以看出宏的输入契约：

• 语法：调用形式为codegen_runtime_tests!(ignore: ["name1", "name2", ...])，即一个名为ignore的具名字段，值为字符串数组；
• 解析约束：宏内部的ignores函数（lib.rs）对输入做了严格校验——成员必须是命名成员且名字必须为ignore，表达式必须是字符串数组，否则直接panic!("codegen_runtime_tests!() requires ...")。这保证了宏输入的唯一合法形态；
• ignore语义：命中列表的测试会带上#[ignore]，在默认cargo test中会被跳过（可用于标记 flaky 或有外部依赖的用例）。上例中outbound-postgres与outbound-postgres-variable-permission就因偶发 "Connection reset by peer" 而被忽略；
• run约定：宏生成的每个#[test] fn xxx()都会调用模块作用域内的run(test_path: PathBuf)。在 tests/runtime.rs 中，run通过RuntimeTest::<InProcessSpin>::bootstrap(config).run()以进程内（in-process）方式启动一个 Spin 运行时实例并执行该用例，错误处理策略为OnTestError::Panic（即测试失败直接 panic，作为#[test]失败上报）。

注意宏依赖项：heck（用于 snake_case 转换）、quote（生成 Rust 代码）、syn（解析宏输入），见 Cargo.toml；[lib]段声明proc-macro = true，且关闭了 doctest 与单元测试（doctest = false、test = false）。

四、与运行时测试协议的配合：测试用例如何被"跑起来"

宏只负责生成#[test]壳子，真正的执行逻辑在runtime-testscrate 中。理解这一点，才能明白"新增一个测试 = 新增一个目录"的完整含义。

4.1 测试目录的约定

根据 tests/runtime-tests/README.md，一个运行时测试目录必须包含：

• spin.toml清单（必选）：它实际是一个支持插值模板的清单，测试运行器支持两类占位符：
  • %{source=组件名}：引用 tests/test-components 中预构建好的 Spin 兼容 WebAssembly 组件，例如%{source=sqlite}会使用名为sqlite的测试组件；
  • %{port=端口号}：引用某个服务暴露的 guest 端口，测试运行器会查找暴露该端口的服务并替换为随机分配的主机端口。
• error.txt（可选）：当该应用预期失败时存在。协议要求：测试运行器向/发起 GET 请求，组件应返回 200（一切正常）或 500（出错）；若存在error.txt，则应用必须返回 500 且响应体包含error.txt中的文本。
• services（可选）：列出测试所需的外部服务名，一行一个。required_services（src/lib.rs）读取该文件并交给ServicesConfig启动依赖服务；目录下存在services与否，正是宏决定是否添加extern-dependencies-testsfeature 门控的依据。

4.2 测试执行与通过条件

RuntimeTest::run（src/lib.rs）对每个用例发起GET /请求，其判定逻辑与 README 完全一致：

• 返回200→ 通过；
• 返回500且响应体非空 → 读取error.txt，若响应体包含其内容则通过，否则失败并附带 stderr；
• 返回其他状态码或空响应体 → 失败。

测试期间，copy_manifest（src/lib.rs）会把测试目录的spin.toml模板拷贝到临时目录并完成占位符替换（组件路径通过test_components::path解析）。因此一个典型的测试目录（如 outbound-mysql/spin.toml）长这样：

spin_manifest_version = 2 [application] name = "outbound-mysql" authors = ["Fermyon Engineering <engineering@fermyon.com>"] version = "0.1.0" [[trigger.http]] route = "/" component = "test" [component.test] source = "%{source=outbound-mysql}" allowed_outbound_hosts = ["mysql://localhost:%{port=3306}"] environment = { DB_URL = "mysql://spin:spin@localhost:%{port=3306}/spin_dev" }

这里%{source=outbound-mysql}指向测试组件，%{port=3306}则由服务编排层解析为实际可用端口——这就是宏背后"运行时测试"生态的全貌。而同样场景的负向用例 outbound-mysql-no-permission/spin.toml 不声明allowed_outbound_hosts，配合目录下的error.txt即可断言权限拒绝行为。

4.3 另一种运行方式：独立二进制

除了通过cargo test走宏生成路径外，tests/runtime-tests/src/main.rs 还提供了独立二进制：cargo run可接受两个可选参数（spin二进制路径与测试目录路径，均有默认值），并以OnTestError::Log（打印日志而非 panic）的方式调用RuntimeTest::<SpinCli>::run_all遍历执行。

五、设计价值与扩展思路

从实现与调用点可以看出，该宏的收益与约束都非常清晰：

• 收益：单一事实来源。测试目录即测试声明，tests/runtime-tests/tests下每新增一个目录（只要包含合法spin.toml），宏在下次编译时就会自动为其生成#[test]函数，彻底消除了"目录存在但忘记注册测试函数"这类低级遗漏；同时ignore列表提供了声明式的跳过机制，services探测让"需要外部服务的用例"自动带上 feature 门控。
• 约束：命名映射规则。测试函数名由目录名经to_snake_case()派生，因此目录命名应遵循 Snake Case 风格（如outbound-mysql→outbound_mysql），以避免生成非法或不可读的标识符；宏也不支持除ignore外的其他配置项（如自定义 feature 名、自定义 run 路径），需要扩展时需修改宏本身。
• 适用边界（从源码结构可以推断）：该宏强耦合于"CARGO_MANIFEST_DIR向上两级 +tests/runtime-tests/tests"这个相对布局，若移动test-codegen-macrocrate 或运行时测试目录的位置，路径需要同步调整；它只适合"目录结构驱动测试生成"这一场景，通用性有限，但在 Spin 仓库中已被 tests/runtime.rs 稳定使用，是理解 Spin 测试分层（单元测试 / 运行时测试 / 一致性测试并存）的关键一环。

六、小结

• 宏：codegen_runtime_tests 遍历tests/runtime-tests/tests子目录，为每个目录生成调用run(PathBuf)的#[test]函数，按需附加#[ignore]与#[cfg(feature = "extern-dependencies-tests")]；
• 输入契约：仅支持ignore: ["...", ...]具名字段，由syn严格解析；
• 真实调用：见 tests/runtime.rs，run通过RuntimeTest::<InProcessSpin>引导测试；
• 测试协议：GET /返回 200 即通过，返回 500 且响应体包含error.txt内容即按预期失败，详见 tests/runtime-tests/README.md 与 src/lib.rs。

对希望为 Spin 贡献新运行时测试的开发者来说，工作流被大幅简化：在 tests/runtime-tests/tests 下新增目录并写好spin.toml（必要时附带error.txt、services），宏会在下一次cargo test编译时自动完成测试函数的生成与注册。

• 云原生
• 微服务