From 03b9479558f9539de4ab4c2de6798971b064d183 Mon Sep 17 00:00:00 2001
From: James Hegedus <jthegedus@hey.com>
Date: Sun, 19 Feb 2023 22:36:31 +1100
Subject: [PATCH] ci: enable Bats test file-level parallel execution (#1461)

---
 .github/workflows/tests.yml |  8 ++++----
 docs/contribute/core.md     | 14 +++++++++++++-
 scripts/test.bash           | 19 +++++++++++++++++++
 3 files changed, 36 insertions(+), 5 deletions(-)
 create mode 100755 scripts/test.bash

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 75b5e745..c83cdc2d 100644
--- a/.github/workflows/tests.yml
+++ b/.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 }}
 
diff --git a/docs/contribute/core.md b/docs/contribute/core.md
index 371cf68a..76201e2d 100644
--- a/docs/contribute/core.md
+++ b/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:
 
diff --git a/scripts/test.bash b/scripts/test.bash
new file mode 100755
index 00000000..5e361fdd
--- /dev/null
+++ b/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}"