ci: enable Bats test file-level parallel execution (#1461)

.github/workflows/tests.yml

@@ -61,7 +61,7 @@ jobs:
         run: |
           sudo add-apt-repository -y ppa:fish-shell/nightly-master
           sudo apt-get update
-          sudo apt-get -y install fish curl
+          sudo apt-get -y install fish curl parallel
 
           # Create $HOME/bin
           mkdir -p "$HOME/bin"
@@ -87,7 +87,7 @@ jobs:
           echo "$HOME/bats-core/bin" >>"$GITHUB_PATH"
 
       - name: Run tests
-        run: bats test
+        run: scripts/test.bash
         env:
           GITHUB_API_TOKEN: ${{ github.token }}
 
@@ -104,7 +104,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install test dependencies
-        run: brew install coreutils fish elvish nushell
+        run: brew install coreutils parallel fish elvish nushell
 
       - name: Install bats
         run: |
@@ -112,7 +112,7 @@ jobs:
           echo "$HOME/bats-core/bin" >>"$GITHUB_PATH"
 
       - name: Run tests
-        run: bats test
+        run: scripts/test.bash
         env:
           GITHUB_API_TOKEN: ${{ github.token }}
 

docs/contribute/core.md

@@ -93,7 +93,19 @@ It is possible to configure IDEs to use this file. For example, when using VSCod
 
 ## Bats Testing
 
-It is **strongly encouraged** to examine the existing test suite and the [bats-core documentation](https://bats-core.readthedocs.io/en/stable/index.html) before writing tests.
+Execute tests locally with:
+
+```shell
+./scripts/test.bash
+```
+
+Before writing tests **please read**:
+
+- existing tests in `test/`
+- [bats-core documentation](https://bats-core.readthedocs.io/en/stable/index.html)
+- existing Bats settings used in `scripts/test.bash`
+
+### Bats Tips
 
 Bats debugging can be difficult at times. Using the TAP output with `-t` flag will enable you to print outputs with the special file descriptor `>&3` during test execution, simplifying debugging. As an example:
 

scripts/test.bash

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+test_directory="test"
+bats_options=(--timing --print-output-on-failure)
+
+if command -v parallel >/dev/null; then
+  # enable parallel jobs
+  bats_options=("${bats_options[@]}" --jobs 2 --no-parallelize-within-files)
+elif [[ -n "${CI-}" ]]; then
+  printf "* %s\n" "GNU parallel should be installed in the CI environment. Please install and rerun the test suite."
+  exit 1
+else
+  printf "* %s\n" "For faster test execution, install GNU parallel."
+fi
+
+printf "* %s\n" "Running Bats in directory '${test_directory}' with options:" "${bats_options[@]}"
+bats "${bats_options[@]}" "${test_directory}"