feat: add set_test_title

Author: Chemaclass

bashunit

@@ -49,6 +49,7 @@ source "$BASHUNIT_ROOT_DIR/src/colors.sh"
 source "$BASHUNIT_ROOT_DIR/src/console_header.sh"
 source "$BASHUNIT_ROOT_DIR/src/console_results.sh"
 source "$BASHUNIT_ROOT_DIR/src/helpers.sh"
+source "$BASHUNIT_ROOT_DIR/src/test_title.sh"
 source "$BASHUNIT_ROOT_DIR/src/upgrade.sh"
 source "$BASHUNIT_ROOT_DIR/src/assertions.sh"
 source "$BASHUNIT_ROOT_DIR/src/reports.sh"

docs/test-files.md

@@ -35,6 +35,24 @@ test_getFunctionsToRun_with_filter_should_return_matching_functions() { ... }
 You're free to use any of Bash's syntax options to define these functions.
 :::
 
+## Custom test titles
+
+By default, **bashunit** derives the name shown in reports from the test function name.
+If you need a more descriptive title, you can override it inside the test using `set_test_title`:
+
+::: code-group
+```bash [Example]
+function test_handles_invalid_input() {
+  set_test_title "🔥 handles invalid input with 💣"
+  # test logic...
+}
+```
+:::
+
+The provided title is used only for display purposes. The original function name is still
+used internally, and custom titles are reset automatically after each test, so there's
+no need for manual cleanup. Setting a new title again will replace the previous one for the same test.
+
 ## `set_up` function
 
 The `set_up` auxiliary function is called, if it is present in the test file, before each test function in the test file is executed.

src/helpers.sh

@@ -11,6 +11,13 @@ function helper::normalize_test_function_name() {
   local original_fn_name="${1-}"
   local interpolated_fn_name="${2-}"
 
+  local custom_title
+  custom_title="$(state::get_test_title)"
+  if [[ -n "$custom_title" ]]; then
+    echo "$custom_title"
+    return
+  fi
+
   if [[ -n "${interpolated_fn_name-}" ]]; then
     original_fn_name="$interpolated_fn_name"
   fi

src/runner.sh

@@ -201,6 +201,8 @@ function runner::run_test() {
     export BASHUNIT_CURRENT_TEST_ID="${sanitized_fn_name}_$$"
   fi
 
+  state::reset_test_title
+
   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)"
@@ -291,21 +293,38 @@ function runner::run_test() {
   local total_assertions="$(state::calculate_total_assertions "$test_execution_result")"
   local test_exit_code="$(state::get_test_exit_code)"
 
+  local encoded_test_title
+  encoded_test_title="${test_execution_result##*##TEST_TITLE=}"
+  encoded_test_title="${encoded_test_title%%##*}"
+  local test_title=""
+  if [[ -n "$encoded_test_title" ]]; then
+    if command -v base64 >/dev/null; then
+      test_title="$(echo "$encoded_test_title" | base64 -d)"
+    else
+      test_title="$(echo "$encoded_test_title" | openssl enc -d -base64)"
+    fi
+  fi
+
+  state::set_test_title "$test_title"
+  local label
+  label="$(helper::normalize_test_function_name "$fn_name" "$interpolated_fn_name")"
+  state::reset_test_title
+
   if [[ -n $runtime_error || $test_exit_code -ne 0 ]]; then
     state::add_tests_failed
-    console_results::print_error_test "$fn_name" "$runtime_error"
-    reports::add_test_failed "$test_file" "$fn_name" "$duration" "$total_assertions"
+    console_results::print_error_test "$label" "$runtime_error"
+    reports::add_test_failed "$test_file" "$label" "$duration" "$total_assertions"
     runner::write_failure_result_output "$test_file" "$fn_name" "$runtime_error"
-    internal_log "Test error" "$fn_name" "$runtime_error"
+    internal_log "Test error" "$label" "$runtime_error"
     return
   fi
 
   if [[ "$current_assertions_failed" != "$(state::get_assertions_failed)" ]]; then
     state::add_tests_failed
-    reports::add_test_failed "$test_file" "$fn_name" "$duration" "$total_assertions"
+    reports::add_test_failed "$test_file" "$label" "$duration" "$total_assertions"
     runner::write_failure_result_output "$test_file" "$fn_name" "$subshell_output"
 
-    internal_log "Test failed" "$fn_name"
+    internal_log "Test failed" "$label"
 
     if env::is_stop_on_failure_enabled; then
       if parallel::is_enabled; then
@@ -319,36 +338,34 @@ function runner::run_test() {
 
   if [[ "$current_assertions_snapshot" != "$(state::get_assertions_snapshot)" ]]; then
     state::add_tests_snapshot
-    console_results::print_snapshot_test "$fn_name"
-    reports::add_test_snapshot "$test_file" "$fn_name" "$duration" "$total_assertions"
-    internal_log "Test snapshot" "$fn_name"
+    console_results::print_snapshot_test "$label"
+    reports::add_test_snapshot "$test_file" "$label" "$duration" "$total_assertions"
+    internal_log "Test snapshot" "$label"
     return
   fi
 
   if [[ "$current_assertions_incomplete" != "$(state::get_assertions_incomplete)" ]]; then
     state::add_tests_incomplete
-    reports::add_test_incomplete "$test_file" "$fn_name" "$duration" "$total_assertions"
-    internal_log "Test incomplete" "$fn_name"
+    reports::add_test_incomplete "$test_file" "$label" "$duration" "$total_assertions"
+    internal_log "Test incomplete" "$label"
     return
   fi
 
   if [[ "$current_assertions_skipped" != "$(state::get_assertions_skipped)" ]]; then
     state::add_tests_skipped
-    reports::add_test_skipped "$test_file" "$fn_name" "$duration" "$total_assertions"
-    internal_log "Test skipped" "$fn_name"
+    reports::add_test_skipped "$test_file" "$label" "$duration" "$total_assertions"
+    internal_log "Test skipped" "$label"
     return
   fi
 
-  local label="$(helper::normalize_test_function_name "$fn_name" "$interpolated_fn_name")"
-
   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" "$fn_name" "$duration" "$total_assertions"
-  internal_log "Test passed" "$fn_name"
+  reports::add_test_passed "$test_file" "$label" "$duration" "$total_assertions"
+  internal_log "Test passed" "$label"
 }
 
 function runner::decode_subshell_output() {

src/state.sh

@@ -14,6 +14,7 @@ _DUPLICATED_FUNCTION_NAMES=""
 _FILE_WITH_DUPLICATED_FUNCTION_NAMES=""
 _DUPLICATED_TEST_FUNCTIONS_FOUND=false
 _TEST_OUTPUT=""
+_TEST_TITLE=""
 _TEST_EXIT_CODE=0
 
 function state::get_tests_passed() {
@@ -132,6 +133,18 @@ function state::set_test_exit_code() {
   _TEST_EXIT_CODE="$1"
 }
 
+function state::get_test_title() {
+  echo "$_TEST_TITLE"
+}
+
+function state::set_test_title() {
+  _TEST_TITLE="$1"
+}
+
+function state::reset_test_title() {
+  _TEST_TITLE=""
+}
+
 function state::set_duplicated_functions_merged() {
   state::set_duplicated_test_functions_found
   state::set_file_with_duplicated_function_names "$1"
@@ -145,17 +158,21 @@ function state::initialize_assertions_count() {
     _ASSERTIONS_INCOMPLETE=0
     _ASSERTIONS_SNAPSHOT=0
     _TEST_OUTPUT=""
+    _TEST_TITLE=""
 }
 
 function state::export_subshell_context() {
   local encoded_test_output
+  local encoded_test_title
 
   if base64 --help 2>&1 | grep -q -- "-w"; then
     # Alpine requires the -w 0 option to avoid wrapping
     encoded_test_output=$(echo -n "$_TEST_OUTPUT" | base64 -w 0)
+    encoded_test_title=$(echo -n "$_TEST_TITLE" | base64 -w 0)
   else
     # macOS and others: default base64 without wrapping
     encoded_test_output=$(echo -n "$_TEST_OUTPUT" | base64)
+    encoded_test_title=$(echo -n "$_TEST_TITLE" | base64)
   fi
 
   cat <<EOF
@@ -165,6 +182,7 @@ function state::export_subshell_context() {
 ##ASSERTIONS_INCOMPLETE=$_ASSERTIONS_INCOMPLETE\
 ##ASSERTIONS_SNAPSHOT=$_ASSERTIONS_SNAPSHOT\
 ##TEST_EXIT_CODE=$_TEST_EXIT_CODE\
+##TEST_TITLE=$encoded_test_title\
 ##TEST_OUTPUT=$encoded_test_output\
 ##
 EOF

src/test_title.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+function set_test_title() {
+  state::set_test_title "$1"
+}

tests/acceptance/bashunit_custom_title_test.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+function set_up_before_script() {
+  TEST_ENV_FILE="tests/acceptance/fixtures/.env.default"
+}
+
+function test_bashunit_resets_custom_title_between_tests() {
+  local test_file=./tests/acceptance/fixtures/test_custom_title.sh
+  local output
+  output="$(./bashunit --no-parallel --env "$TEST_ENV_FILE" "$test_file")"
+  assert_successful_code "$output"
+  assert_contains "🔥 handles invalid input with 💣" "$output"
+  assert_contains "Default title" "$output"
+}

tests/acceptance/fixtures/test_custom_title.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+function test_custom_title() {
+  set_test_title "🔥 handles invalid input with 💣"
+  assert_true true
+}
+
+function test_default_title() {
+  assert_true true
+}

tests/unit/helpers_test.sh

@@ -32,6 +32,11 @@ function test_normalize_test_function_name_camel_case() {
   assert_same "SomeLogic" "$(helper::normalize_test_function_name "testSomeLogic")"
 }
 
+function test_normalize_test_function_name_custom_title() {
+  set_test_title "🔥 handles invalid input with 💣"
+  assert_same "🔥 handles invalid input with 💣" "$(helper::normalize_test_function_name "test_handles_invalid_input")"
+}
+
 function test_get_functions_to_run_no_filter_should_return_all_functions() {
   local functions=("prefix_function1" "prefix_function2" "other_function" "prefix_function3")
 

tests/unit/state_test.sh

@@ -255,6 +255,7 @@ function test_initialize_assertions_count() {
 ##ASSERTIONS_INCOMPLETE=0\
 ##ASSERTIONS_SNAPSHOT=0\
 ##TEST_EXIT_CODE=0\
+##TEST_TITLE=\
 ##TEST_OUTPUT=\
 ##"\
     "$export_assertions_count"
@@ -284,6 +285,7 @@ function test_export_assertions_count() {
 ##ASSERTIONS_INCOMPLETE=12\
 ##ASSERTIONS_SNAPSHOT=33\
 ##TEST_EXIT_CODE=1\
+##TEST_TITLE=\
 ##TEST_OUTPUT=$(echo -n "something" | base64)##"\
     "$export_assertions_count"
 }