bake-test

Reusable Bake tasks for running Rust tests and testing downstream repositories against local Cargo workspace packages.

Motivation

Rust provides a good test runner through Cargo, but it does not provide a shared way to prepare project resources or exercise selected downstream crates. This package gives Rust projects a consistent bake test, bake test:coverage, and bake test:external interface while keeping Cargo and cargo-llvm-cov as the test runners.

Usage

Add the task crate to the private bake/ package:

cargo bake --regenerate
cargo add --manifest-path bake/Cargo.toml bake-test
cargo bake --regenerate

Then run the workspace tests:

cargo bake test
cargo bake test:coverage
cargo bake test:external

The coverage task runs documentation tests and requires 100% measured source-region coverage for the selected workspace test configuration. Regions inside unreachable!() calls are excluded automatically. It reports uncovered source locations when the gate fails. Install cargo-llvm-cov first; see the Rust Testing guide for feature selection and architecture notes. Use --package name to limit a workspace run to one package.

As a last resort, a package can exclude from the gate a file whose code cannot run in CI, such as raw device or platform calls. List each file in the package's Cargo.toml with a reason:

[[package.metadata.bake.test.coverage.exclude]]
path = "src/xr.rs"
reason = "Raw OpenXR runtime calls; needs a headset runtime."

The coverage summary always lists each excluded file with its reason and size. See Excluding files for the rules.

Configure downstream repositories in the root Cargo.toml:

[[workspace.metadata.bake.test.external]]
repository = "https://github.com/socketry/downstream-project"
branch = "main"

See the Rust Testing guide for the test:before hook, checkout reuse, Cargo patching, and canonical GitHub Actions workflows.

Releasing

Prepare a release with cargo bake cargo:release:patch (or minor, major, or bump --version X.Y.Z) from a clean checkout of main; it bumps the version, commits with the Release: vVERSION trailer, validates the candidate, and opens the pull request. After review and merge, GitHub Actions publishes the release when the configured crates-io environment approves it. Follow the shared Releasing skill for the standard process.

Releases

See releases.md for the full release history.

v0.3.7

• Add a license job to the canonical test.yml, which runs license:check on the pull request's head commit with its full history, and require it in the test-result aggregate, so a missing or stale license header fails the pull request that introduces it rather than changing sources in a release.

v0.3.6

• Add a minimum-rust job to the canonical test.yml, which reads rust-version from the root Cargo.toml and checks every publishable package with that toolchain, and require it in the test-result aggregate.

v0.3.5

• Let a package exclude specific files from the coverage gate under [[package.metadata.bake.test.coverage.exclude]], each with a required reason. The task rejects missing reasons, missing files, and duplicate entries, and always lists each excluded file with its reason and size in regions and lines.

See Also

• Bake
• Bake Cargo

Contributing

Please open an issue or pull request on GitHub.

Agent Context

Run cargo bake agent:context:install to install shared context and skills. Read .agents/context/index.md to find relevant guides, follow agents.md if present, and apply skills under .agents/skills/. The installer preserves repository-owned agents.md; it does not create or regenerate that file.