Merge branch 'main' into codex/add-assert_match_snapshot_ignore_colors

Author: Chemaclass

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Fix asserts on test doubles in subshell
+- Allow interpolating arguments in data providers output
 - Added `assert_match_snapshot_ignore_colors`
 
 ## [0.19.1](https://github.com/TypedDevs/bashunit/compare/0.19.0...0.19.1) - 2025-05-23

docs/command-line.md

@@ -129,6 +129,12 @@ 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`.
+:::
+
 ::: code-group
 ```bash [Example]
 ./bashunit ./tests --parallel

docs/configuration.md

@@ -68,6 +68,11 @@ BASHUNIT_SIMPLE_OUTPUT=false
 
 Runs the tests in child processes with randomized execution, which may improve overall testing speed, especially for larger test suites.
 
+::: warning
+Parallel execution is supported only on **macOS** and **Ubuntu**. On other
+systems bashunit forces sequential execution to avoid inconsistent results.
+:::
+
 Similar as using `-p|--parallel` option on the [command line](/command-line#parallel).
 
 

docs/data-providers.md

@@ -24,6 +24,31 @@ function test_my_test_case() {
 
 The provider function can echo a single value like `"one"` or multiple values `"one" "two" "three"`.
 
+## Interpolating arguments in test names
+
+You can reference the values provided by a data provider directly in the test
+function name using placeholders like `::1::`, `::2::`, ... matching the
+argument position.
+
+::: code-group
+```bash [example_test.sh]
+# data_provider fizz_numbers
+function test_returns_fizz_when_multiple_of_::1::_like_::2::_given() {
+  # ...
+}
+
+function fizz_numbers() {
+  echo 3 4
+  echo 3 6
+}
+```
+```[Output]
+Running example_test.sh
+✓ Passed: Returns fizz when multiple of '3' like '4' given
+✓ Passed: Returns fizz when multiple of '3' like '6' given
+```
+:::
+
 ## Multiple args in one call
 
 ::: code-group

docs/test-doubles.md

@@ -37,6 +37,22 @@ EOF
   assert_same "13525 pts/7    00:00:01 bash" "$(code)"
 }
 ```
+
+:::
+Mocked functions are also available inside subshells:
+
+::: code-group
+```bash [Example]
+function test_example() {
+  mock date echo "2024-05-01"
+
+  function run() {
+    date
+  }
+
+  assert_same "2024-05-01" "$(run)"
+}
+```
 :::
 
 ## spy

src/helpers.sh

@@ -8,14 +8,20 @@ declare -r BASHUNIT_GIT_REPO="https://github.com/TypedDevs/bashunit"
 # @return string Eg: "Some logic camelCase"
 #
 function helper::normalize_test_function_name() {
-  local original_function_name="${1-}"
+  local original_fn_name="${1-}"
+  local interpolated_fn_name="${2-}"
+
+  if [[ -n "${interpolated_fn_name-}" ]]; then
+    original_fn_name="$interpolated_fn_name"
+  fi
+
   local result
 
   # Remove the first "test_" prefix, if present
-  result="${original_function_name#test_}"
+  result="${original_fn_name#test_}"
   # If no "test_" was removed (e.g., "testFoo"), remove the "test" prefix
-  if [[ "$result" == "$original_function_name" ]]; then
-    result="${original_function_name#test}"
+  if [[ "$result" == "$original_fn_name" ]]; then
+    result="${original_fn_name#test}"
   fi
   # Replace underscores with spaces
   result="${result//_/ }"
@@ -25,6 +31,29 @@ function helper::normalize_test_function_name() {
   echo "$result"
 }
 
+function helper::escape_single_quotes() {
+  local value="$1"
+  # shellcheck disable=SC1003
+  echo "${value//\'/'\'\\''\'}"
+}
+
+function helper::interpolate_function_name() {
+  local function_name="$1"
+  shift
+  local args=("$@")
+  local result="$function_name"
+
+  for ((i=0; i<${#args[@]}; i++)); do
+    local placeholder="::$((i+1))::"
+    # shellcheck disable=SC2155
+    local value="$(helper::escape_single_quotes "${args[$i]}")"
+    value="'$value'"
+    result="${result//${placeholder}/${value}}"
+  done
+
+  echo "$result"
+}
+
 function helper::check_duplicate_functions() {
   local script="$1"
 

src/runner.sh

@@ -50,11 +50,11 @@ function runner::spinner() {
 
 function runner::functions_for_script() {
   local script="$1"
-  local all_function_names="$2"
+  local all_fn_names="$2"
 
   # Filter the names down to the ones defined in the script, sort them by line number
   shopt -s extdebug
-  for f in $all_function_names; do
+  for f in $all_fn_names; do
     declare -F "$f" | grep "$script"
   done | sort -k2 -n | awk '{print $1}'
   shopt -u extdebug
@@ -65,8 +65,8 @@ function runner::call_test_functions() {
   local filter="$2"
   local prefix="test"
   # Use declare -F to list all function names
-  local all_function_names=$(declare -F | awk '{print $3}')
-  local filtered_functions=$(helper::get_functions_to_run "$prefix" "$filter" "$all_function_names")
+  local all_fn_names=$(declare -F | awk '{print $3}')
+  local filtered_functions=$(helper::get_functions_to_run "$prefix" "$filter" "$all_fn_names")
   # shellcheck disable=SC2207
   local functions_to_run=($(runner::functions_for_script "$script" "$filtered_functions"))
 
@@ -77,33 +77,33 @@ function runner::call_test_functions() {
   runner::render_running_file_header
   helper::check_duplicate_functions "$script" || true
 
-  for function_name in "${functions_to_run[@]}"; do
+  for fn_name in "${functions_to_run[@]}"; do
     if parallel::is_enabled && parallel::must_stop_on_failure; then
       break
     fi
 
     local provider_data=()
     while IFS=" " read -r line; do
       provider_data+=("$line")
-    done <<< "$(helper::get_provider_data "$function_name" "$script")"
+    done <<< "$(helper::get_provider_data "$fn_name" "$script")"
 
     # No data provider found
     if [[ "${#provider_data[@]}" -eq 0 ]]; then
-      runner::run_test "$script" "$function_name"
-      unset function_name
+      runner::run_test "$script" "$fn_name"
+      unset fn_name
       continue
     fi
 
     # Execute the test function for each line of data
     for data in "${provider_data[@]}"; do
       IFS=" " read -r -a args <<< "$data"
       if [ "${#args[@]}" -gt 1 ]; then
-        runner::run_test "$script" "$function_name" "${args[@]}"
+        runner::run_test "$script" "$fn_name" "${args[@]}"
       else
-        runner::run_test "$script" "$function_name" "$data"
+        runner::run_test "$script" "$fn_name" "$data"
       fi
     done
-    unset function_name
+    unset fn_name
   done
 
   if ! env::is_simple_output_enabled; then
@@ -133,8 +133,10 @@ function runner::run_test() {
 
   local test_file="$1"
   shift
-  local function_name="$1"
+  local fn_name="$1"
   shift
+
+  local interpolated_fn_name="$(helper::interpolate_function_name "$fn_name" "$@")"
   local current_assertions_failed="$(state::get_assertions_failed)"
   local current_assertions_snapshot="$(state::get_assertions_snapshot)"
   local current_assertions_incomplete="$(state::get_assertions_incomplete)"
@@ -157,7 +159,7 @@ function runner::run_test() {
 
     # 2>&1: Redirects the std-error (FD 2) to the std-output (FD 1).
     # points to the original std-output.
-    "$function_name" "$@" 2>&1
+    "$fn_name" "$@" 2>&1
 
   )
 
@@ -175,7 +177,7 @@ function runner::run_test() {
 
     printf '%*s\n' "$TERMINAL_WIDTH" '' | tr ' ' '='
     printf "%s\n" "File:     $test_file"
-    printf "%s\n" "Function: $function_name"
+    printf "%s\n" "Function: $fn_name"
     printf "%s\n" "Duration: $duration ms"
     local raw_text=${test_execution_result%%##ASSERTIONS_*}
     [[ -n $raw_text ]] && printf "%s" "Raw text: ${test_execution_result%%##ASSERTIONS_*}"
@@ -216,22 +218,22 @@ function runner::run_test() {
     fi
   done
 
-  runner::parse_result "$function_name" "$test_execution_result" "$@"
+  runner::parse_result "$fn_name" "$test_execution_result" "$@"
 
   local total_assertions="$(state::calculate_total_assertions "$test_execution_result")"
   local test_exit_code="$(state::get_test_exit_code)"
 
   if [[ -n $runtime_error || $test_exit_code -ne 0 ]]; then
     state::add_tests_failed
-    console_results::print_error_test "$function_name" "$runtime_error"
-    reports::add_test_failed "$test_file" "$function_name" "$duration" "$total_assertions"
+    console_results::print_error_test "$fn_name" "$runtime_error"
+    reports::add_test_failed "$test_file" "$fn_name" "$duration" "$total_assertions"
     runner::write_failure_result_output "$test_file" "$runtime_error"
     return
   fi
 
   if [[ "$current_assertions_failed" != "$(state::get_assertions_failed)" ]]; then
     state::add_tests_failed
-    reports::add_test_failed "$test_file" "$function_name" "$duration" "$total_assertions"
+    reports::add_test_failed "$test_file" "$fn_name" "$duration" "$total_assertions"
     runner::write_failure_result_output "$test_file" "$subshell_output"
 
     if env::is_stop_on_failure_enabled; then
@@ -246,28 +248,32 @@ function runner::run_test() {
 
   if [[ "$current_assertions_snapshot" != "$(state::get_assertions_snapshot)" ]]; then
     state::add_tests_snapshot
-    console_results::print_snapshot_test "$function_name"
-    reports::add_test_snapshot "$test_file" "$function_name" "$duration" "$total_assertions"
+    console_results::print_snapshot_test "$fn_name"
+    reports::add_test_snapshot "$test_file" "$fn_name" "$duration" "$total_assertions"
     return
   fi
 
   if [[ "$current_assertions_incomplete" != "$(state::get_assertions_incomplete)" ]]; then
     state::add_tests_incomplete
-    reports::add_test_incomplete "$test_file" "$function_name" "$duration" "$total_assertions"
+    reports::add_test_incomplete "$test_file" "$fn_name" "$duration" "$total_assertions"
     return
   fi
 
   if [[ "$current_assertions_skipped" != "$(state::get_assertions_skipped)" ]]; then
     state::add_tests_skipped
-    reports::add_test_skipped "$test_file" "$function_name" "$duration" "$total_assertions"
+    reports::add_test_skipped "$test_file" "$fn_name" "$duration" "$total_assertions"
     return
   fi
 
-  local label="$(helper::normalize_test_function_name "$function_name")"
+  local label="$(helper::normalize_test_function_name "$fn_name" "$interpolated_fn_name")"
 
-  console_results::print_successful_test "${label}" "$duration" "$@"
+  if [[ "$fn_name" == "$interpolated_fn_name" ]]; then
+    console_results::print_successful_test "${label}" "$duration" "$@"
+  else
+    console_results::print_successful_test "${label}" "$duration"
+  fi
   state::add_tests_passed
-  reports::add_test_passed "$test_file" "$function_name" "$duration" "$total_assertions"
+  reports::add_test_passed "$test_file" "$fn_name" "$duration" "$total_assertions"
 }
 
 function runner::decode_subshell_output() {
@@ -285,21 +291,21 @@ function runner::decode_subshell_output() {
 }
 
 function runner::parse_result() {
-  local function_name=$1
+  local fn_name=$1
   shift
   local execution_result=$1
   shift
   local args=("$@")
 
   if parallel::is_enabled; then
-    runner::parse_result_parallel "$function_name" "$execution_result" "${args[@]}"
+    runner::parse_result_parallel "$fn_name" "$execution_result" "${args[@]}"
   else
-    runner::parse_result_sync "$function_name" "$execution_result"
+    runner::parse_result_sync "$fn_name" "$execution_result"
   fi
 }
 
 function runner::parse_result_parallel() {
-  local function_name=$1
+  local fn_name=$1
   shift
   local execution_result=$1
   shift
@@ -310,9 +316,9 @@ function runner::parse_result_parallel() {
 
   local test_result_file=$(echo "${args[@]}" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-|-$//')
   if [[ -z "$test_result_file" ]]; then
-    test_result_file="${function_name}.$$.result"
+    test_result_file="${fn_name}.$$.result"
   else
-    test_result_file="${function_name}-${test_result_file}.$$.result"
+    test_result_file="${fn_name}-${test_result_file}.$$.result"
   fi
 
   local unique_test_result_file="${test_suite_dir}/${test_result_file}"
@@ -323,15 +329,15 @@ function runner::parse_result_parallel() {
     count=$((count + 1))
   done
 
-  log "debug" "[PARA]" "function_name:$function_name" "execution_result:$execution_result"
+  log "debug" "[PARA]" "fn_name:$fn_name" "execution_result:$execution_result"
 
-  runner::parse_result_sync "$function_name" "$execution_result"
+  runner::parse_result_sync "$fn_name" "$execution_result"
 
   echo "$execution_result" > "$unique_test_result_file"
 }
 
 function runner::parse_result_sync() {
-  local function_name=$1
+  local fn_name=$1
   local execution_result=$2
 
   local assertions_failed=$(\
@@ -370,7 +376,7 @@ function runner::parse_result_sync() {
     sed -E -e 's/.*##TEST_EXIT_CODE=([0-9]*)##.*/\1/g'\
   )
 
-  log "debug" "[SYNC]" "function_name:$function_name" "execution_result:$execution_result"
+  log "debug" "[SYNC]" "fn_name:$fn_name" "execution_result:$execution_result"
 
   ((_ASSERTIONS_PASSED += assertions_passed)) || true
   ((_ASSERTIONS_FAILED += assertions_failed)) || true

tests/functional/doubles_test.sh

@@ -13,18 +13,6 @@ function test_mock_ps_when_executing_a_sourced_function() {
   assert_match_snapshot "$(top_mem)"
 }
 
-function test_spy_commands_called_once_when_executing_a_script() {
-  spy ps
-  spy awk
-  spy head
-
-  bash ./tests/functional/fixtures/doubles_script.sh
-
-  assert_have_been_called_times 1 ps
-  assert_have_been_called_times 1 awk
-  assert_have_been_called_times 1 head
-}
-
 function test_spy_commands_called_once_when_executing_a_sourced_function() {
 
   source ./tests/functional/fixtures/doubles_function.sh