postgres_lsp 测试宏 pgls_test_macros 深度解析用gen_tests!按文件批量自动生成 Rust 测试【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lsp导读本文聚焦 postgres_lsp 仓库中crates/pgls_test_macros这一轻量级过程宏 crate它提供了一个名为gen_tests!的声明式宏能够根据 glob 匹配到的 SQL 测试文件自动批量生成#[test]测试函数配合可选的.expected.sql文件与快照断言让每个测试样例一个文件的数据驱动测试范式落地为几行代码。读完本文你将掌握该宏的完整用法、参数约定、生成结果形态与全部已知坑点并透过 src/lib.rs 的源码理解其底层实现原理以及它在 pgls_analyser 规则测试 中的真实生产级用法。一、它是什么为文件驱动的测试而生的过程宏pgls_test_macros 是 postgres_lsp 工作区见根目录 Cargo.toml 中的 workspace 依赖声明下的一个纯过程宏 crateCargo.toml中通过[lib] proc-macro true将其声明为过程宏库。它的使命非常聚焦以文件为测试用例的载体自动生成调用你指定测试函数的#[test]代码。这一设计思路与项目自身的测试组织方式高度契合——在crates/pgls_analyser/tests/specs/、crates/pgls_pretty_print/tests/等目录下项目维护了大量以.sql为后缀的测试样例文件如crates/pgls_analyser/tests/specs/safety/下即有 128 个.sql文件与一一对应的.snap快照。每新增一个 SQL 样例即自动新增一个测试用例无需手写重复的样板代码。二、基本用法两行代码批量生成测试原文档给出了最核心的用法向宏传入一个 glob 模式和一个测试函数路径宏会为每一个匹配的文件生成一个独立的#[test]。2.1 目录结构约定假设你的 crate 中有如下文件结构crate/ |-- src/ |-- tests/ |-- queries/ |-- test.sql |-- test.expected.sql |-- querytest.rs2.2 宏调用// crate/tests/querytest.rs tests_macros::gen_tests!{ tests/queries/*.sql, crate::run_test // use crate:: if the linter complains. } fn run_test( test_path: str, // absolute path on the machine expected_path: str, // absolute path of .expected file test_dir: str // absolute path of the test files parent ) { // your logic }需要注意的几点约定glob 模式必须以 crate 根目录为起点宏内部会以CARGO_MANIFEST_DIR为基准解析例如tests/queries/*.sql测试函数接收三个str参数test_path测试文件绝对路径、expected_path对应.expected文件绝对路径即使文件不存在也会传入、test_dir测试文件所在目录的绝对路径原文档特意提示若 linter 报错请在函数路径前加上crate::前缀例如crate::run_test。2.3 自动生成的测试代码给定crate/tests/queries/some_test_abc.sql宏展开后等价于生成如下测试该文件结构复现自 README#[test] pub fn some_test_abc() { let test_file crate/tests/queries/some_test_abc.sql; let test_expected_file crate/tests/queries/some_test_abc.expected.sql; let parent crate/tests/queries; run_test(test_file, test_expected_file, parent); }glob 匹配到的每一个文件都会生成一个这样的测试函数测试名取自文件名去除扩展名。你可以选择两种断言策略结果型断言在测试文件旁放置一个.expected.文件如test.expected.sql其路径会被传入测试函数由你在函数体内完成输出比对快照断言不依赖.expected文件直接在测试函数内结合insta等快照库生成.snap快照见后文 pgls_analyser 的实例。三、源码级实现原理宏内部做了什么理解了用法之后我们深入 src/lib.rs 一探实现细节。整个宏的入口是pub fn gen_testslib.rs它先解析输入参数再调用Arguments::generate()生成 TokenStream。整个流程可分为四步3.1 参数解析两个必需参数Arguments结构体lib.rs通过syn::parse::Parse解析宏输入struct Arguments { pattern: syn::ExprLit, // glob 模式必须是字符串字面量 test_function: syn::Path, // 测试函数路径 }解析逻辑要求输入严格为字符串字面量, 路径的二元组形式逗号分隔顺序固定。3.2 文件收集glob 遍历与过滤Arguments::get_filepaths()lib.rs完成文件枚举通过std::env::var(CARGO_MANIFEST_DIR)获取 crate 根目录这就是glob 必须以 crate 根为起点的原因若环境变量缺失会报错 Cannot find CARGO_MANIFEST_DIR. Are you using cargo?使用依赖 globwalk构建GlobWalkerBuilder遍历文件跳过所有以.expected.sql结尾的文件避免把期望文件本身当作测试用例仅保留元数据中is_file()的条目。3.3 变量推导测试名、路径与 expected 路径Variables的TryFromPathBuf实现lib.rs负责从每个文件路径推导出四个变量test_name取file_stem()文件名去扩展名ext断言扩展名必须为sql否则 panicExpected .sql extension but received: {ext}——这正是 Pitfalls 中所有匹配文件必须是 .sql的源码出处test_dir父目录绝对路径test_expected_fullpath把扩展名去掉再拼回.expected.sql即test.sql→test.expected.sql。注意这个路径是构造出来的并不检查文件是否真实存在所以即使没有.expected文件也会照常传入路径。3.4 模块树组织按目录层级生成嵌套modTestModuleslib.rs是一个递归树结构按路径的目录部分逐级插入foo/bar/testA.sql会被插入foo→bar两级模块最终print()时递归地用mod #name { ... }包裹子模块并追加测试项。因此当 glob 跨多个子目录时生成的测试天然具有mod层级隔离例如crates/pgls_analyser/tests/specs/safety/下的规则测试会自动归入对应的specs::safety模块树。四、仓库内的真实使用案例pgls_analyser 规则测试宏最完整的实践样本在 crates/pgls_analyser/tests/rules_tests.rs只需两行宏调用便覆盖了tests/specs/**/*.sql下全部规则测试样例pgls_test_macros::gen_tests! { tests/specs/**/*.sql, crate::rule_test }随后rule_test(full_path: static str, _: str, _: str)rules_tests.rs承担了真实的断言逻辑展示了.expected之外的另一种搭配方式通过parse_test_path从路径中拆出(group, rule, fname)三元组例如specs/safety/no-primary-key/xxx.sql→(safety, no-primary-key, xxx.sql)以此构造RuleFilter只启用对应的单条规则读取 SQL 文本用pgls_statement_splitter::split切分语句、pgls_query::parse解析 AST喂给Analyser::run拿到诊断结果一方面用insta::with_settings!将快照路径指向测试文件所在目录并assert_snapshot!生成.snap快照这正是crates/pgls_analyser/tests/specs/safety/下 128 个.snap文件的由来另一方面用Expectation::from_file解析 SQL 文件中的-- expect_no_diagnostics/-- expect_category注释做结果型断言校验各类诊断的数量。这套宏生成用例 函数内双断言的模式是把 README 中的.expected.方案与快照方案结合使用的进阶范例读者可直接照搬。五、已知坑点与规避方法Pitfalls 完整清单原文档明确列出的陷阱在此逐一展开并补充源码层面的解释坑点说明规避方式文件名撞 Rust 关键字若测试文件名为fn.sql、match.sql等 Rust 关键字生成的pub fn fn()属于非法语法编译直接失败避免用 Rust 关键字命名测试文件非 snake_case 文件名的 lint 报错测试函数名直接取自文件名MyTest.sql会生成pub fn MyTest()触发 non_snake_case 警告测试文件统一使用snake_case命名glob 只能匹配.sql文件源码中assert_eq!(ext, sql, ...)会在生成期 paniclib.rs所有匹配文件保持.sql后缀.expected.sql路径总会传入即使文件不存在expected_path参数也照常给出由测试函数自行决定如何处理在测试函数内做文件存在性判断或干脆采用快照断言自动包裹mod tests { .. }宏默认会把生成的测试包进mod tests若同一文件需要多次生成会冲突多次生成时手动包裹外部模块mod some_test { tests_macros::gen_tests! { .. } }不要放在 crate 根目录源码对路径取.parent()时expect(Do not put tests in root directory.)测试文件必须位于至少一层子目录下测试文件放在tests/下的子目录中glob 需以 crate 根为起点路径基于CARGO_MANIFEST_DIR解析tests/queries/*.sql表示 crate 根下的tests/queries/始终从 crate 根写相对 glob六、如何运行宏在编译期完成全部展开运行时无需任何额外步骤直接使用常规命令即可cargo test # 运行工作区内全部测试 cargo test -p pgls_analyser # 仅运行 analyser crate含宏生成的规则测试新增一个 SQL 测试样例只需往匹配目录丢一个文件及可选的.expected.sql重新运行cargo test即自动生效无需修改任何 Rust 源码。七、总结何时该用这类文件驱动测试宏pgls_test_macros 的价值在于把用例数量与代码量解耦测试内容沉淀为数据SQL 文件测试逻辑收敛为单一函数测试用例注册交给宏自动完成。对 postgres_lsp 这类拥有大量 SQL 样例分析规则、格式化、语句切分、快照等模块的解析器/LSP 项目尤其适用对普通 Rust 项目当你面临几十上百个同构输入需要逐一断言的场景时也可以参考本 crate 的实现src/lib.rs或直接引入该宏来组织你的数据驱动测试。进一步探索宏的实现源码位于 crates/pgls_test_macros/src/lib.rs依赖声明见 crates/pgls_test_macros/Cargo.toml最完整的生产级使用范例见 crates/pgls_analyser/tests/rules_tests.rs 及其配套的crates/pgls_analyser/tests/specs/目录128 组.sql.snap测试对。【免费下载链接】postgres_lspA Language Server for Postgres项目地址: https://gitcode.com/GitHub_Trending/po/postgres_lsp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考