Validate example GitHub workflows (#269)

Split out example workflow yaml into `examples/workflow`. Run the actionlint validator on all workflows, and fix some nits. Fixes #266
sourcefrog · Feb 2, 2024 · 8517801 · 8517801
2 parents 8438973 + af04d6d
commit 8517801
Show file tree

Hide file tree

Showing 7 changed files with 126 additions and 82 deletions.
diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml
@@ -0,0 +1,30 @@
+name: actionlint
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/*.yml"
+      - "examples/workflows/*.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/*.yml"
+      - "examples/workflows/*.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  action-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check workflow files
+        shell: bash
+        run: |
+          bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
+          # shellcheck disable=SC2046
+          ./actionlint -color $(find .github/workflows examples/workflows -name '*.yml' -type f ! -name release.yml -print)
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -117,7 +117,7 @@ jobs:
           name: cargo-mutants-linux
       - name: Install cargo-mutants binary
         run: |
-          install cargo-mutants $HOME/.cargo/bin/
+          install cargo-mutants ~/.cargo/bin/
       - name: Mutants in-diff
         # Normally this would have --in-place, but for the sake of exercising more cases, it does not.
         run: >
@@ -153,7 +153,7 @@ jobs:
           name: cargo-mutants-linux
       - name: Install cargo-mutants binary
         run: |
-          install cargo-mutants $HOME/.cargo/bin/
+          install cargo-mutants ~/.cargo/bin/
       - name: Mutants
         # Skip baselines because this action depends on the tests
         run: >

diff --git a/README.md b/README.md
@@ -48,6 +48,10 @@ To generate mutants in only one file:
 cargo mutants -f src/something.rs
 ```
 
+## Integration with CI
+
+The [manual includes instructions and examples for automatically testing mutants in CI](https://mutants.rs/ci.html), including incremental testing of pull requests and full testing of the development branch.
+
 ## Help advance cargo-mutants
 
 If you use cargo-mutants or just like the idea you can help it get better:

diff --git a/book/src/ci.md b/book/src/ci.md
@@ -21,44 +21,5 @@ The recommended way to install cargo-mutants is using [install-action](https://g
 Here is an example of a GitHub Actions workflow that runs mutation tests and uploads the results as an artifact. This will fail if it finds any uncaught mutants.
 
 ```yml
-name: cargo-mutants
-
-env:
-  CARGO_TERM_COLOR: always
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    # Only test PR if it changes something that's likely to affect the results, because
-    # mutant tests can take a long time. Adjust these paths to suit your project.
-    paths:
-      - ".cargo/**"
-      - ".github/workflows/mutants.yml"
-      - "Cargo.*"
-      - "src/**"
-      - "testdata/**"
-      - "tests/**"
-
-jobs:
-  cargo-mutants:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - uses: taiki-e/install-action@v2
-        name: Install cargo-mutants using install-action
-        with:
-          tool: cargo-mutants
-      - name: Run mutant tests
-        run: cargo mutants -vV --in-place
-      - name: Archive results
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: mutants-out
-          path: mutants.out
+{{#include ../../examples/workflows/basic.yml}}
 ```
diff --git a/book/src/pr-diff.md b/book/src/pr-diff.md
@@ -5,44 +5,5 @@ You can use `--in-diff` to test only the code that has changed in a pull request
 For example, you can use the following workflow to test only the code that has changed in a pull request:
 
 ```yaml
-name: Tests
-
-permissions:
-  contents: read
-
-env:
-  CARGO_TERM_COLOR: always
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-jobs:
-  incremental-mutants:
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Relative diff
-        run: |
-          git branch -av
-          git diff origin/${{ github.base_ref }}.. | tee git.diff
-      - uses: Swatinem/rust-cache@v2
-      - uses: taiki-e/install-action@v2
-        name: Install cargo-mutants using install-action
-        with:
-          tool: cargo-mutants
-      - name: Mutants
-        run: |
-          cargo mutants --no-shuffle -j 2 -vV --in-diff git.diff
-      - name: Archive mutants.out
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: mutants-incremental.out
-          path: mutants.out
+{{#include ../../examples/workflows/in-diff.yml}}
 ```
diff --git a/examples/workflows/basic.yml b/examples/workflows/basic.yml
@@ -0,0 +1,42 @@
+# Example of how to configure a GitHub Actions workflow to run `cargo mutants`
+# on every push to main and every pull request that changes the code.
+
+# You could run this standalone or merge it into a workflow that runs other tests.
+
+name: cargo-mutants
+
+env:
+  CARGO_TERM_COLOR: always
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    # Only test PR if it changes something that's likely to affect the results, because
+    # mutant tests can take a long time. Adjust these paths to suit your project.
+    paths:
+      - ".cargo/mutants.toml"
+      - ".github/workflows/tests.yml"
+      - "Cargo.*"
+      - "src/**"
+      - "testdata/**"
+      - "tests/**"
+
+jobs:
+  cargo-mutants:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-mutants
+      - run: cargo mutants -vV --in-place
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutants-out
+          path: mutants.out
diff --git a/examples/workflows/in-diff.yml b/examples/workflows/in-diff.yml
@@ -0,0 +1,46 @@
+# An example of how to run cargo-mutants on only the sections of code that have changed in a pull request,
+# using the `--in-diff` feature of cargo-mutants.
+#
+# This can give much faster feedback on pull requests, but can miss some problems that
+# would be found by running mutants on the whole codebase.
+
+name: Tests
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  incremental-mutants:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Relative diff
+        run: |
+          git branch -av
+          git diff origin/${{ github.base_ref }}.. | tee git.diff
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@v2
+        name: Install cargo-mutants using install-action
+        with:
+          tool: cargo-mutants
+      - name: Mutants
+        run: |
+          cargo mutants --no-shuffle -vV --in-diff git.diff
+      - name: Archive mutants.out
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutants-incremental.out
+          path: mutants.out