Skip to content

README.md

Latest commit

 

History

History
121 lines (86 loc) · 3.05 KB

README.md

File metadata and controls

121 lines (86 loc) · 3.05 KB

Rust Mutation Testing Extension

This extension provides rust_mutation_test, a rule that mutation-tests a rust_library by compiling and running tests against automatically-mutated source variants.

Primary API docs are in defs.bzl and generated site docs (rust_mutation.md in the rules_rust docs book).

Overview

rust_mutation_test:

  1. Reads crate metadata from the target rust_library.
  2. Builds rustc arguments via rules_rust's canonical compile wiring (collect_inputs + construct_arguments).
  3. Enumerates mutants with cargo-mutants JSON output.
  4. Stages crate sources and compile-time input files.
  5. Runs a baseline compile+test.
  6. Runs compile+test for each mutant.
  7. Reports mutants as CAUGHT or SURVIVED.

Status meanings:

  • CAUGHT: mutant fails to compile or tests fail.
  • SURVIVED: mutant compiles and tests pass.
  • Baseline/infrastructure failures fail the Bazel test immediately.

Current behavior:

  • By default, any survived mutant fails the Bazel target.
  • Set allow_survivors = True to report survivors without failing the target.
  • If mutation generation produces zero mutants, the Bazel target succeeds and prints No mutations generated..

Setup

Bzlmod

bazel_dep(name = "rules_rust_mutation", version = "{SEE_RELEASE_NOTES}")

WORKSPACE

load("@rules_rust_mutation//:repositories.bzl", "rust_mutation_dependencies")

rust_mutation_dependencies()

Usage

load("@rules_rust//rust:defs.bzl", "rust_library")
load("@rules_rust_mutation//:defs.bzl", "rust_mutation_test")

rust_library(
    name = "my_lib",
    srcs = ["lib.rs"],
    edition = "2021",
)

rust_mutation_test(
    name = "my_lib_mutation_test",
    crate = ":my_lib",
)

Run:

bazel test //:my_lib_mutation_test --test_output=all

cargo-mutants Compatibility

Mutation enumeration uses cargo mutants --list --json --diff --Zmutate-file ....

Configuration

mutants_config = "path/to/mutants.toml" is forwarded as cargo mutants --config <path>.

allow_survivors = True changes survivor handling:

  • Default (False): if any mutant survives, the Bazel test fails.
  • True: survivors are still reported, but the Bazel test exits successfully.

Tooling Model

  • This extension builds a hermetic cargo-mutants binary from source.
  • cargo-mutants internally invokes Cargo; the runner provides Cargo from the active Rust toolchain.
  • Rustc params are generated by a dedicated writer action that materializes canonical rustc flags into a runfiles-compatible params file consumed by the runtime runner.

Output Example

Running baseline compile+test...
Generated 5 mutants
  mutant_0_src/lib.rs_binop - CAUGHT
  mutant_1_src/lib.rs_binop - SURVIVED

Mutation Testing Summary
========================
Total: 5  Caught: 4 (80%)  Survived: 1 (20%)

For survivors, a unified diff is printed for each surviving mutant.

Local Development

  • Run extension-local tests from this repository root.
  • Useful targets:
    • //:clippy
    • //private:runner_unit_test
    • //test:all