Merge branch 'main' into codex/add-assert_match_snapshot_ignore_colors

 Conflicts:
	CHANGELOG.md

Author: Chemaclass

.github/workflows/tests.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Run tests
         shell: bash
         run: |
-          ./bashunit tests/${{ matrix.test_chunk }}/*_test.sh
+          ./bashunit --parallel tests/${{ matrix.test_chunk }}/*_test.sh
 
   alpine:
     name: "On alpine-latest"

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 - Fix asserts on test doubles in subshell
 - Allow interpolating arguments in data providers output
+- Deprecate `# data_provider` in favor of `# @data_provider`
+- Allow `assert_have_been_called_with` to check arguments of specific calls
+- Enable parallel tests on Windows
+- Add `assert_not_called`
+- Improve `find_total_tests` performance
 - Added `assert_match_snapshot_ignore_colors`
 
 ## [0.19.1](https://github.com/TypedDevs/bashunit/compare/0.19.0...0.19.1) - 2025-05-23

adrs/adr-004-metadata-prefix.md

@@ -0,0 +1,37 @@
+# Title: Prefix metadata comments with @
+
+* Status: accepted
+* Authors: @Chemaclass
+* Date: 2025-05-29
+
+
+## Context and Problem Statement
+
+Data providers are defined via a special comment `# data_provider`. We want to
+clearly differentiate these meta comments from ordinary comments.
+
+## Considered Options
+
+* Keep using `# data_provider` as is.
+* Introduce an `@` prefix for special comments while supporting the old syntax.
+
+## Decision Outcome
+
+We decided to prefix the metadata provider directives with `@`,
+eg: using `# @data_provider provider_name`.
+
+> The previous form without the prefix is still supported for backward compatibility but is now deprecated.
+
+### Positive Consequences
+
+* Highlights special bashunit directives clearly.
+* Allows future directives to consistently use the `@` prefix.
+
+### Negative Consequences
+
+* Projects must eventually update old comments to the new syntax.
+
+## Technical Details
+
+`helper::get_provider_data` now matches both `# @data_provider` and the old
+`# data_provider` when locating provider functions.

docs/blog/2024-09-01-release-0-15.md

@@ -51,7 +51,7 @@ BASHUNIT_REPORT_HTML=
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2

docs/command-line.md

@@ -130,9 +130,9 @@ Creates a report XML file that follows the JUnit XML format and contains informa
 bashunit provides an option to run each test in a separate child process, allowing you to parallelize the test execution and potentially speed up the testing process. When running in parallel mode, the execution order of tests is randomized.
 
 ::: warning
-Parallel mode is currently only supported on **macOS** and **Ubuntu**. On other
-systems (like Alpine Linux or Windows) the option is automatically disabled due
-to inconsistent results. In those environments consider using `--no-parallel`.
+Parallel mode is supported on **macOS**, **Ubuntu**, and **Windows**. On other
+systems (like Alpine Linux) the option is automatically disabled due to
+inconsistent results. In those environments consider using `--no-parallel`.
 :::
 
 ::: code-group

docs/data-providers.md

@@ -13,9 +13,12 @@ Each run is treated as a separate test, so it can pass or fail independently. Pl
 
 A data provider function is specified as follows:
 
+> **Note**: The previous `# data_provider` syntax is still supported but
+> deprecated. Prefer using the `@` prefix going forward.
+
 ::: code-group
 ```bash [Example]
-# data_provider provider_function_name
+# @data_provider provider_function_name
 function test_my_test_case() {
   ...
 }
@@ -32,7 +35,7 @@ argument position.
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider fizz_numbers
+# @data_provider fizz_numbers
 function test_returns_fizz_when_multiple_of_::1::_like_::2::_given() {
   # ...
 }
@@ -53,7 +56,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directories_exists() {
   local dir1=$1
   local dir2=$2
@@ -78,7 +81,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local directory=$1
 
@@ -103,7 +106,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2

docs/test-doubles.md

@@ -2,6 +2,11 @@
 
 When creating tests, you might need to override existing function to be able to write isolated tests from external behaviour. To accomplish this, you can use mocks. You can also check that a function was called with certain arguments or even a number of times with a spy.
 
+Temporary files created by spies are isolated per test run, so they work reliably when executing tests in parallel.
+
+Spies record their calls in temporary files scoped to each test run.
+This avoids clashes between processes and allows spies to work reliably when tests execute in parallel using `BASHUNIT_PARALLEL_RUN`.
+
 ## mock
 > `mock "function" "body"`
 
@@ -97,26 +102,30 @@ function test_failure() {
 :::
 
 ## assert_have_been_called_with
-> `assert_have_been_called_with "expected" "spy"`
+> `assert_have_been_called_with "expected" "spy" [call_index]`
 
-Reports an error if `callable` is not called with `expected`.
+Reports an error if `spy` is not called with `expected`. When `call_index` is
+provided, the assertion checks the arguments of that specific call (starting at
+1). Without `call_index` it checks the last invocation.
 
 ::: code-group
 ```bash [Example]
 function test_success() {
   spy ps
 
-  ps foo bar
+  ps foo
+  ps bar
 
-  assert_have_been_called_with "foo bar" ps
+  assert_have_been_called_with "foo" ps 1
+  assert_have_been_called_with "bar" ps 2
 }
 
 function test_failure() {
   spy ps
 
-  ps bar foo
+  ps bar
 
-  assert_have_been_called_with "foo bar" ps
+  assert_have_been_called_with "foo" ps 1
 }
 ```
 :::
@@ -147,3 +156,26 @@ function test_failure() {
 }
 ```
 :::
+
+## assert_not_called
+> `assert_not_called "spy"`
+
+Reports an error if `spy` has been executed at least once.
+
+::: code-group
+```bash [Example]
+function test_success() {
+  spy ps
+
+  assert_not_called ps
+}
+
+function test_failure() {
+  spy ps
+
+  ps
+
+  assert_not_called ps
+}
+```
+:::

src/globals.sh

@@ -40,17 +40,29 @@ function random_str() {
 function temp_file() {
   local prefix=${1:-bashunit}
   mkdir -p /tmp/bashunit/tmp && chmod -R 777 /tmp/bashunit/tmp
-  mktemp /tmp/bashunit/tmp/"$prefix".XXXXXXX
+  local test_prefix=""
+  if [[ -n "${BASHUNIT_CURRENT_TEST_ID:-}" ]]; then
+    test_prefix="${BASHUNIT_CURRENT_TEST_ID}_"
+  fi
+  mktemp /tmp/bashunit/tmp/"${test_prefix}${prefix}".XXXXXXX
 }
 
 function temp_dir() {
   local prefix=${1:-bashunit}
   mkdir -p /tmp/bashunit/tmp && chmod -R 777 /tmp/bashunit/tmp
-  mktemp -d /tmp/bashunit/tmp/"$prefix".XXXXXXX
+  local test_prefix=""
+  if [[ -n "${BASHUNIT_CURRENT_TEST_ID:-}" ]]; then
+    test_prefix="${BASHUNIT_CURRENT_TEST_ID}_"
+  fi
+  mktemp -d /tmp/bashunit/tmp/"${test_prefix}${prefix}".XXXXXXX
 }
 
 function cleanup_temp_files() {
-  rm -rf /tmp/bashunit/tmp/*
+  if [[ -n "${BASHUNIT_CURRENT_TEST_ID:-}" ]]; then
+    rm -rf /tmp/bashunit/tmp/"${BASHUNIT_CURRENT_TEST_ID}"_*
+  else
+    rm -rf /tmp/bashunit/tmp/*
+  fi
 }
 
 # shellcheck disable=SC2145

src/helpers.sh

@@ -158,9 +158,9 @@ function helper::get_provider_data() {
   fi
 
   data_provider_function=$(\
-    grep -B 1 "function $function_name()" "$script" |\
-    grep "# data_provider " |\
-    sed -E -e 's/\ *# data_provider (.*)$/\1/g'\
+    grep -B 2 "function $function_name()" "$script" |\
+    grep -E "# *@?data_provider " |\
+    sed -E -e 's/\ *# *@?data_provider (.*)$/\1/g'\
     || true
   )
 
@@ -190,19 +190,18 @@ function helpers::get_latest_tag() {
 function helpers::find_total_tests() {
     local filter=${1:-}
     local files=("${@:2}")
-    local total_count=0
-
-    for file in "${files[@]}"; do
-        local count
-        if [[ -n "$filter" ]]; then
-            count=$(grep -r -E "^\s*function\s+test.*$filter" "$file" --include=\*.sh 2>/dev/null | wc -l)
-        else
-            count=$(grep -r -E '^\s*function\s+test' "$file" --include=\*.sh 2>/dev/null | wc -l)
-        fi
-        total_count=$((total_count + count))
-    done
-
-    echo "$total_count"
+
+    if [[ ${#files[@]} -eq 0 ]]; then
+        echo 0
+        return
+    fi
+
+    local pattern='^\s*function\s+test'
+    if [[ -n "$filter" ]]; then
+        pattern+=".*$filter"
+    fi
+
+    grep -r -E "$pattern" --include="*.sh" "${files[@]}" 2>/dev/null | wc -l | xargs
 }
 
 function helper::load_test_files() {

src/main.sh

@@ -20,8 +20,8 @@ function main::exec_tests() {
   trap '[[ $? -eq $EXIT_CODE_STOP_ON_FAILURE ]] && main::handle_stop_on_failure_sync' EXIT
 
   if env::is_parallel_run_enabled && ! parallel::is_enabled; then
-    printf "%sWarning: Parallel tests are working only for macOS and Ubuntu.\n" "${_COLOR_INCOMPLETE}"
-    printf "For other OS (Linux/Alpine, Windows), --parallel is not enabled due to inconsistent results,\n"
+    printf "%sWarning: Parallel tests are supported on macOS, Ubuntu and Windows.\n" "${_COLOR_INCOMPLETE}"
+    printf "For other OS (like Alpine), --parallel is not enabled due to inconsistent results,\n"
     printf "particularly involving race conditions.%s " "${_COLOR_DEFAULT}"
     printf "%sFallback using --no-parallel%s\n" "${_COLOR_SKIPPED}" "${_COLOR_DEFAULT}"
   fi