Merge remote-tracking branch 'origin/main' into binops

.github/workflows/deploy-book.yml → .github/workflows/book.yml

@@ -1,28 +1,56 @@
-name: Deploy book
+name: Book
 on:
   push:
     branches:
       - main
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/workflows/book.yml
+      - book/**
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow one concurrent deployment
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
-
 jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: beta
+      - uses: Swatinem/rust-cache@v2
+      - name: Install mdbook and mdbook-linkcheck
+        uses: taiki-e/install-action@v2
+        with:
+          tool: mdbook, mdbook-linkcheck
+      - name: Build mdbook
+        run: |
+          mdbook build book
+      - name: Archive book output
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: book
+          path: book/book
+
   deploy:
-    if: github.repository == 'sourcefrog/cargo-mutants'
+    if:
+      github.repository == 'sourcefrog/cargo-mutants' && github.ref_name ==
+      'main'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+    concurrency: # Allow one concurrent deployment
+      group: "pages"
+      cancel-in-progress: true
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

.github/workflows/tests.yml

@@ -8,6 +8,14 @@ on:
     branches:
       - main
   pull_request:
+    paths:
+      - ".cargo/**"
+      - ".github/workflows/tests.yml"
+      - "Cargo.*"
+      - "mutants_attrs/**"
+      - "src/**"
+      - "testdata/**"
+      - "tests/**"
 
 # see https://matklad.github.io/2021/09/04/fast-rust-builds.html
 env:
@@ -42,6 +50,10 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - name: rustfmt
         run: cargo fmt --all -- --check
+      - uses: taiki-e/install-action@v2
+        name: Install nextest using install-action
+        with:
+          tool: nextest
       - name: Build
         run: cargo build --all-targets
       - name: Test
@@ -70,6 +82,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: [release-binary]
     if: github.event_name == 'pull_request'
+    strategy:
+      matrix:
+        test_tool: [cargo, nextest]
     steps:
       - uses: actions/checkout@v3
         with:
@@ -82,16 +97,21 @@ jobs:
         with:
           toolchain: beta
       - uses: Swatinem/rust-cache@v2
-      - name: Download release binary
+      - uses: taiki-e/install-action@v2
+        name: Install nextest using install-action
+        with:
+          tool: nextest
+      - name: Download cargo-mutants binary
         uses: actions/download-artifact@v3
         with:
           name: cargo-mutants-linux
-      - name: Install binary artifact
+      - name: Install cargo-mutants binary
         run: |
           install cargo-mutants $HOME/.cargo/bin/
-      - name: Mutants
-        run: |
-          cargo mutants --no-shuffle -vV --in-diff git.diff
+      - name: Mutants in-diff
+        run: >
+          cargo mutants --no-shuffle -vV --in-diff git.diff --test-tool
+          ${{matrix.test_tool}}
       - name: Archive mutants.out
         uses: actions/upload-artifact@v3
         if: always()
@@ -105,47 +125,31 @@ jobs:
     strategy:
       matrix:
         shard: [0, 1, 2, 3, 4, 5, 6, 7]
+        test_tool: [cargo, nextest]
     steps:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: beta
       - uses: Swatinem/rust-cache@v2
-      - name: Download release binary
+      - uses: taiki-e/install-action@v2
+        name: Install nextest using install-action
+        with:
+          tool: nextest
+      - name: Download cargo-mutants binary
         uses: actions/download-artifact@v3
         with:
           name: cargo-mutants-linux
-      - name: Install binary artifact
+      - name: Install cargo-mutants binary
         run: |
           install cargo-mutants $HOME/.cargo/bin/
       - name: Mutants
-        run: |
+        run: >
           cargo mutants --no-shuffle -vV --shard ${{ matrix.shard }}/8
+          --test-tool ${{ matrix.test_tool }}
       - name: Archive mutants.out
         uses: actions/upload-artifact@v3
         if: always()
         with:
           name: mutants.out
           path: mutants.out
-
-  book:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: beta
-      - uses: Swatinem/rust-cache@v2
-      - name: Install mdbook and mdbook-linkcheck
-        uses: taiki-e/install-action@v2
-        with:
-          tool: mdbook, mdbook-linkcheck
-      - name: Build mdbook
-        run: |
-          mdbook build book
-      - name: Archive book output
-        uses: actions/upload-artifact@v3
-        if: always()
-        with:
-          name: book
-          path: book/book

CONTRIBUTING.md

@@ -33,7 +33,13 @@ Please run `cargo fmt` and `cargo clippy`. These are checked in CI.
 
 ## Testing
 
-Of course, please add tests for new features or bug fixes, and see the _Testing_ section of [the design doc](DESIGN.md).
+Of course, please add tests for new features or bug fixes. See also the _Testing_ section of [the design doc](DESIGN.md).
+
+### Running the tests
+
+cargo-mutants tests require [`cargo-nextest`](https://nexte.st/) to be installed, so that they can exercise `--test-tool=nextest`.
+
+cargo-mutants tests can be run under either `cargo test` or `cargo nextest run`.
 
 ### Test naming
 

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "cargo-mutants"
-version = "23.12.2"
+version = "24.1.0"
 edition = "2021"
 authors = ["Martin Pool"]
 license = "MIT"
-description = "Find inadequately-tested code that can be removed without any tests failing."
+description = "Inject bugs and see if your tests catch them"
 repository = "https://github.com/sourcefrog/cargo-mutants"
 homepage = "https://mutants.rs/"
 categories = ["development-tools::testing"]
@@ -60,6 +60,7 @@ quote = "1.0"
 regex = "1.10"
 serde_json = "1"
 similar = "2.0"
+strum = { version = "0.25", features = ["derive"] }
 subprocess = "0.2.8"
 tempfile = "3.2"
 time = "0.3"
@@ -72,7 +73,6 @@ whoami = "1.2"
 [dependencies.nutmeg]
 version = "0.1.4"
 # git = "https://github.com/sourcefrog/nutmeg.git"
-# branch = "const-new"
 
 [dependencies.proc-macro2]
 features = ["span-locations"]

DESIGN.md

@@ -194,6 +194,18 @@ Cargo-mutants is primarily tested on its public interface, which is the command
 
 `cargo-mutants` runs as a subprocess of the test process so that we get the most realistic view of its behavior. In some cases it is run via the `cargo` command to test that this level of indirection works properly.
 
+### Test performance
+
+Since cargo-mutants itself runs the test suite of the program under test many times there is a risk that the test suite can get slow. Aside from slowing down developers and CI, this has a multiplicative effect on the time to run `cargo mutants` on itself.
+
+To manage test time:
+
+* Although key behaviour should be tested through integration tests that run the CLI, it's OK to handle additional cases with unit tests that run much faster.
+
+* Whenever reasonable, CLI tests can only list mutants with `--list` rather than actually testing all of them: we have just a small set of tests that check that the mutants that are listed are actually run.
+
+* Use relatively small testdata trees that are sufficient to test the right behavior.
+
 ### `testdata` trees
 
 The primary means of testing is Rust source trees under `testdata`: you can copy an existing tree and modify it to show the new behavior that you want to test.
@@ -214,7 +226,11 @@ Many features can be tested adequately by only looking at the list of mutants pr
 
 ### Unit tests
 
-Although we primarily want to test the public interface (which is the command line), unit tests can be added in a `mod test {}` within the source tree for any behavior that is inconvenient to exercise from the command line.
+Although we primarily want to test the public interface (which is the command line), unit tests can be added in a `mod test {}` within the source tree for any behavior that is inconvenient or overly slow to exercise from the command line.
+
+### Nextest tests
+
+cargo-mutants tests require `nextest` to be installed.
 
 ## UI Style
 

NEWS.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 24.1.0
+
+- New! `cargo mutants --test-tool nextest`, or `test_tool = "nextest"` in `.cargo/mutants.toml` runs tests under [Nextest](https://nexte.st/). Some trees have tests that only work under Nextest, and this allows them to be tested. In other cases Nextest may be significantly faster, because it will exit soon after the first test failure.
+
 - Fixed: Fixed spurious "Patch input contains repeated filenames" error when `--in-diff` is given a patch that deletes multiple files.
 
 - New: Mutate `+, -, *, /, %, &, ^, |, <<, >>` binary ops, and their corresponding assignment ops like `+=`.

README.md

@@ -22,12 +22,18 @@ the tests might be insufficient.
 
 **The main documentation is the user guide at <https://mutants.rs/>.**
 
+## Prerequisites
+
+cargo-mutants can help on trees with non-flaky tests that run under `cargo test` or [`cargo nextest run`](https://nexte.st/).
+
 ## Install
 
 ```sh
 cargo install --locked cargo-mutants
 ```
 
+You can also install using [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) or from binaries attached to GitHub releases.
+
 ## Quick start
 
 From within a Rust source directory, just run
@@ -42,8 +48,6 @@ To generate mutants in only one file:
 cargo mutants -f src/something.rs
 ```
 
-**For more, see the user guide is at <https://mutants.rs/>.**
-
 ## Help advance cargo-mutants
 
 If you use cargo-mutants or just like the idea you can help it get better:
@@ -53,18 +57,20 @@ If you use cargo-mutants or just like the idea you can help it get better:
 
 ## Project status
 
-As of October 2023 this is an actively-maintained spare time project. I expect to make [releases](https://github.com/sourcefrog/cargo-mutants/releases) about every one or two months.
+As of January 2024 this is an actively-maintained spare time project. I expect to make [releases](https://github.com/sourcefrog/cargo-mutants/releases) about every one or two months.
 
 It's very usable at it is and there's room for lots more future improvement,
 especially in adding new types of mutation.
 
+This software is provided as-is with no warranty of any kind.
+
 ## Further reading
 
 See also:
 
-- [cargo-mutants manual](https://mutants.rs/)
-- [How cargo-mutants compares to other techniques and tools](https://github.com/sourcefrog/cargo-mutants/wiki/Compared).
-- [Design notes](DESIGN.md)
-- [Contributing](CONTRIBUTING.md)
-- [Release notes](NEWS.md)
-- [Discussions](https://github.com/sourcefrog/cargo-mutants/discussions)
+* [cargo-mutants manual](https://mutants.rs/)
+* [How cargo-mutants compares to other techniques and tools](https://github.com/sourcefrog/cargo-mutants/wiki/Compared).
+* [Design notes](DESIGN.md)
+* [Contributing](CONTRIBUTING.md)
+* [Release notes](NEWS.md)
+* [Discussions](https://github.com/sourcefrog/cargo-mutants/discussions)

book/src/SUMMARY.md

@@ -16,6 +16,7 @@
   - [Workspaces and packages](workspaces.md)
   - [Passing options to Cargo](cargo-args.md)
   - [Build directories](build-dirs.md)
+  - [Using nextest](nextest.md)
 - [Generating mutants](mutants.md)
   - [Error values](error-values.md)
 - [Improving performance](performance.md)