Add mutation testing with cargo-mutants

.github/workflows/mutation-testing.yml

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+name: mutation-testing
+'on':
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE.txt'
+      - '.gitignore'
+concurrency:
+  group: ${{ github.ref }}-mutants
+  cancel-in-progress: true
+jobs:
+  mutants:
+    timeout-minutes: 60
+    runs-on: ubuntu-24.04
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-mutants
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-mutants
+      - name: Run mutation tests
+        run: cargo mutants --no-shuffle --shard 1/4
+      - name: Upload mutants.out directory
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutants-report
+          path: mutants.out/

.gitignore

@@ -7,3 +7,4 @@ bin/
 node_modules/
 target/
 tmp/
+mutants.out/

README.md

@@ -106,6 +106,15 @@ last version by `rustup update stable`, and then:
 cargo test -vv
 ```
 
+We also use mutation testing to validate the quality of our tests using [cargo-mutants](https://mutants.rs/):
+
+```bash
+cargo install cargo-mutants
+cargo mutants
+```
+
+This tests whether our test suite can detect intentional bugs introduced by the mutation testing tool.
+
 If everything goes well, fork repository, make changes, send us a
 [pull request](https://www.yegor256.com/2014/04/15/github-guidelines.html).
 We will review your changes and apply them to the `master` branch shortly,

mutants.toml

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+# Configuration for cargo-mutants mutation testing
+# This tool creates small modifications to source code to test if our test suite
+# can detect the changes, helping validate test quality.
+# See https://mutants.rs/configuration.html for full documentation
+
+# Exclude files that don't need mutation testing
+exclude_globs = [
+    # Documentation and examples
+    "examples/*",
+    "benches/*",
+    # Test files themselves
+    "tests/*",
+    # Build scripts and tooling
+    "rebuild_benchmark.sh",
+]
+
+# Timeout for each test run (in seconds) 
+# Conservative timeout for CI environment
+timeout = 120
+
+# Skip functions that are likely to have trivial mutations
+skip_mutants = [
+    # Skip simple getter functions that are unlikely to have meaningful mutations
+    "*::capacity",
+    "*::len", 
+    "*::is_empty",
+    # Skip basic iterator size hint functions
+    "*::size_hint",
+    # Skip debug/display implementations
+    "*::fmt",
+]
+
+# Test command to run for each mutant
+# Use the same basic test command as CI
+test_tool = "cargo"