企业官网建设流程全解析

AppFlowy 如何运行 Rust 单元测试并用 grcov 生成覆盖率报告

【免费下载链接】AppFlowyBring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.项目地址: https://gitcode.com/GitHub_Trending/ap/AppFlowy

AppFlowy 的后端逻辑以 Rust workspace 形式位于frontend/rust-lib目录下，日常开发中需要反复运行它的单元测试，并在提交前检查改动对测试覆盖率的冲击。这篇文章给出在 AppFlowy 仓库中完成这两个动作的完整路径：先用 cargo-make 任务或直接的cargo test命令运行 rust-lib 单元测试，再用覆盖率插桩 +grcov生成 HTML 或 lcov 报告。所有命令与任务定义均出自 frontend/scripts/makefile/tests.toml，任务入口为 frontend/Makefile.toml。

准备条件

• Rust 工具链：仓库通过 frontend/rust-toolchain.toml 固定了channel = "1.85"，并声明clippy、rustfmt组件。rustup 会在进入对应目录时自动选择该工具链，无需手动切换版本。
• cargo-make：所有任务以Makefile.toml形式组织，需要在frontend/目录下用cargo make调用。
• grcov（仅覆盖率部分需要）：tests.toml 中的check_grcov任务会检查grcov是否在 PATH 中（任务先把$HOME/.cargo/bin加入 PATH）。检查失败时脚本给出的安装建议是：

cargo install grcov rustup component add llvm-tools-preview

第二条是“可能需要”的组件（文档原文提示 “You may also need to install 'llvm-tools-preview'”），安装后若仍找不到grcov，按任务输出提示确认它是否已加入 PATH。

运行 rust-lib 单元测试

仓库提供两种等价方式。

方式一：cargo-make 任务（推荐）。在frontend/目录下执行：

cargo make rust_unit_test

rust_unit_test只串联了rust_lib_unit_test这一个任务，其实际执行内容是：

cd rust-lib RUST_LOG=info DISABLE_CI_TEST_LOG="true" RUST_BACKTRACE=1 cargo test --no-default-features

即关闭默认 feature、开启 backtrace 后对整个 rust-lib workspace 跑一遍测试。其中DISABLE_CI_TEST_LOG="true"按任务定义原样保留，用于在 CI 环境中抑制测试日志；如需单步调试，把RUST_LOG=info改为文档开头注释示例中的RUST_LOG="debug"即可。

方式二：直接跑 cargo 命令。不经过 cargo-make 时，等价于手动执行上面代码块中的三行命令（注意在rust-lib/目录内运行，--no-default-features参数需保留，否则 workspace 的默认 feature 组合可能与任务定义不一致）。

测试成功的判断依据就是cargo test本身的退出码与输出：全部用例通过则进程正常结束，出现失败用例时RUST_BACKTRACE=1会给出堆栈。文档没有额外的成功日志约定，不要依赖特定输出文本判断结果。

用 grcov 生成覆盖率报告

覆盖率流程分三步，对应 tests.toml 中的三个任务，都应在frontend/目录下逐个调用：

第 1 步：检查 grcov 可用

cargo make check_grcov

输出Found 'grcov' executable.表示可以继续；否则任务会打印安装命令并以非零码退出。

第 2 步：带插桩运行覆盖率测试

cargo make run_rustlib_coverage_tests

该任务在rust-lib/下执行：

CARGO_INCREMENTAL=0 \ RUSTFLAGS='-C instrument-coverage' \ LLVM_PROFILE_FILE='prof-%p-%m.profraw' \ cargo test --no-default-features

RUSTFLAGS='-C instrument-coverage'打开 LLVM 覆盖率插桩，LLVM_PROFILE_FILE指定运行时生成的.profraw文件名模板，CARGO_INCREMENTAL=0关闭增量编译。这三项必须原样保留，grcov 依赖它们产出的 profile 文件。此步会在rust-lib/下产生.profraw文件。

第 3 步：生成 grcov 报告

cargo make get_rustlib_grcov_report

任务在rust-lib/下执行：

grcov . \ --binary-path target/debug/deps \ --source-dir . \ --output-type html \ --branch \ --ignore-not-existing \ --log-level WARN \ --output-path target/coverage-html

完成后任务会打印--- Done! Generated HTML report under 'target/coverage-html' for rustlib.（脚本固定输出，非测试结果）。

结果验证：检查frontend/rust-lib/target/coverage-html目录是否生成 HTML 报告，打开其中的入口页面即可按文件查看行覆盖与分支覆盖（--branch参数启用了分支覆盖统计）。

可选分支：lcov 报告

如果下游工具需要 lcov 格式（例如接入已有 CI 覆盖率采集），把第 3 步换成：

cargo make get_rustlib_lcov_report

该任务只把 grcov 的--output-type换为lcov、--output-path换为target/coverage.lcov，其余参数不变，产物是rust-lib/target/coverage.lcov。它和 HTML 报告二选一即可，不需要都跑。

可选分支：清理 profraw 文件

覆盖率测试结束后，.profraw文件会残留在rust-lib/下。clean_profraw_files任务会删除rust-lib/**与rust-lib/build-tool/**下的全部.profraw文件——注意它会无条件删除匹配文件，只应在确认覆盖率流程已完成后执行：

cargo make clean_profraw_files

关于批量入口rust_unit_test_with_coverage的说明

tests.toml 中还有一个总入口任务rust_unit_test_with_coverage，它按序串联了check_grcov、appflowy-flutter-deps-tools（安装 Flutter 依赖工具链）、run_rustlib_coverage_tests、run_sharedlib_coverage_tests、get_lcov_report、clean_profraw_files。不建议把它作为本文场景的默认入口，原因有二：

1. appflowy-flutter-deps-tools安装的是 Flutter 侧构建依赖，与 rust-lib 覆盖率任务无关，属于额外独立步骤；
2. run_sharedlib_coverage_tests要求进入frontend/的上级相对路径../shared-lib目录执行测试，而当前仓库frontend/下不存在shared-lib目录，该步骤在现有代码树上无法完成。

因此本文主路径采用上面的单任务命令（cargo make支持按任务名筛选执行），它们共同完成“rust-lib 单元测试 + grcov 覆盖率报告”这一目标。

边界与限制

• 上述流程只覆盖frontend/rust-lib这个 workspace；Dart 侧测试（flutter test --coverage）走的是 tests.toml 中的dart_unit_test系列任务，不属于本文范围。
• 云端相关测试有独立入口supabase_unit_test（cargo test supabase_ --features "cloud_test"），需要云端测试环境，不要混入本地覆盖率流程。
• grcov 的 HTML 报告基于target/debug/deps下的二进制与第 2 步产生的 profile 文件，若中途执行过cargo clean，需要重新跑第 2、3 步才能得到与新二进制对应的报告。

【免费下载链接】AppFlowyBring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.项目地址: https://gitcode.com/GitHub_Trending/ap/AppFlowy