fix: setup and teardown functions when errors

Author: Chemaclass

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Add two-way synchronization policy between `AGENTS.md` and `copilot-instructions.md` with automatic validation in task templates and PR checklist
 - Add tasks storage policy clarifying `.tasks/` (versioned) vs `.task/` (private scratch, git-ignored)
 - Include `set_test_title` helper in the single-file library
+- Fix lifecycle hooks capture-and-report flow errors
 
 ## [0.24.0](https://github.com/TypedDevs/bashunit/compare/0.23.0...0.24.0) - 2025-09-14
 

docs/test-files.md

@@ -85,6 +85,8 @@ function tear_down() {
 The `set_up_before_script` auxiliary function is called, if it is present in the test file, only once before all tests functions in the test file begin.
 This is useful for global setup that applies to all test functions in the script, such as loading shared resources.
 
+If any command inside `set_up_before_script` fails, bashunit now halts the file immediately and reports the error (including the failing command and location) before any test functions run. This ensures misconfigured environments or missing dependencies surface clearly during setup.
+
 ::: code-group
 ```bash [Example]
 function set_up_before_script() {
@@ -99,6 +101,8 @@ The `tear_down_after_script` auxiliary function is called, if it is present in t
 This auxiliary function is similar to how `set_up_before_script` works but at the end of the tests.
 It provides a hook for any cleanup that should occur after all tests have run, such as deleting temporary files or releasing resources.
 
+Failures inside `tear_down_after_script` are also surfaced as dedicated errors after the final test output so cleanup problems (for example, missing tools or permissions) are visible in the run summary.
+
 ::: code-group
 ```bash [Example]
 function tear_down_after_script() {

src/helpers.sh

@@ -137,9 +137,14 @@ function helper::get_functions_to_run() {
 # @param $1 string Eg: "do_something"
 #
 function helper::execute_function_if_exists() {
-  if [[ "$(type -t "$1")" == "function" ]]; then
-    "$1" 2>/dev/null
+  local fn_name="$1"
+
+  if [[ "$(type -t "$fn_name")" == "function" ]]; then
+    "$fn_name"
+    return $?
   fi
+
+  return 0
 }
 
 #

src/runner.sh

@@ -17,13 +17,19 @@ function runner::load_test_files() {
     internal_log "Loading file" "$test_file"
     # shellcheck source=/dev/null
     source "$test_file"
-    runner::run_set_up_before_script
+    if ! runner::run_set_up_before_script "$test_file"; then
+      runner::clean_set_up_and_tear_down_after_script
+      if ! parallel::is_enabled; then
+        cleanup_script_temp_files
+      fi
+      continue
+    fi
     if parallel::is_enabled; then
       runner::call_test_functions "$test_file" "$filter" 2>/dev/null &
     else
       runner::call_test_functions "$test_file" "$filter"
     fi
-    runner::run_tear_down_after_script
+    runner::run_tear_down_after_script "$test_file"
     runner::clean_set_up_and_tear_down_after_script
     if ! parallel::is_enabled; then
       cleanup_script_temp_files
@@ -57,9 +63,13 @@ function runner::load_bench_files() {
     export BASHUNIT_CURRENT_SCRIPT_ID="$(helper::generate_id "${test_file}")"
     # shellcheck source=/dev/null
     source "$bench_file"
-    runner::run_set_up_before_script
+    if ! runner::run_set_up_before_script "$bench_file"; then
+      runner::clean_set_up_and_tear_down_after_script
+      cleanup_script_temp_files
+      continue
+    fi
     runner::call_bench_functions "$bench_file" "$filter"
-    runner::run_tear_down_after_script
+    runner::run_tear_down_after_script "$bench_file"
     runner::clean_set_up_and_tear_down_after_script
     cleanup_script_temp_files
   done
@@ -555,14 +565,73 @@ function runner::write_failure_result_output() {
   echo -e "$test_nr) $test_file:$line_number\n$error_msg" >> "$FAILURES_OUTPUT_PATH"
 }
 
+function runner::record_file_hook_failure() {
+  local hook_name="$1"
+  local test_file="$2"
+  local hook_output="$3"
+  local status="$4"
+  local render_header="${5:-false}"
+
+  if [[ "$render_header" == true ]]; then
+    runner::render_running_file_header "$test_file"
+  fi
+
+  if [[ -z "$hook_output" ]]; then
+    hook_output="Hook '$hook_name' failed with exit code $status"
+  fi
+
+  state::add_tests_failed
+  console_results::print_error_test "$hook_name" "$hook_output"
+  reports::add_test_failed "$test_file" "$(helper::normalize_test_function_name "$hook_name")" 0 0
+  runner::write_failure_result_output "$test_file" "$hook_name" "$hook_output"
+
+  return "$status"
+}
+
+function runner::execute_file_hook() {
+  local hook_name="$1"
+  local test_file="$2"
+  local render_header="${3:-false}"
+
+  if [[ "$(type -t "$hook_name")" != "function" ]]; then
+    return 0
+  fi
+
+  local hook_output=""
+  local status=0
+  local hook_output_file
+  hook_output_file=$(temp_file "${hook_name}_output")
+
+  {
+    "$hook_name"
+  } >"$hook_output_file" 2>&1 || status=$?
+
+  if [[ -f "$hook_output_file" ]]; then
+    hook_output=$(cat "$hook_output_file")
+    rm -f "$hook_output_file"
+  fi
+
+  if [[ $status -ne 0 ]]; then
+    runner::record_file_hook_failure "$hook_name" "$test_file" "$hook_output" "$status" "$render_header"
+    return $status
+  fi
+
+  if [[ -n "$hook_output" ]]; then
+    printf "%s\n" "$hook_output"
+  fi
+
+  return 0
+}
+
 function runner::run_set_up() {
   internal_log "run_set_up"
   helper::execute_function_if_exists 'set_up'
 }
 
 function runner::run_set_up_before_script() {
+  local test_file="$1"
   internal_log "run_set_up_before_script"
-  helper::execute_function_if_exists 'set_up_before_script'
+  runner::execute_file_hook 'set_up_before_script' "$test_file" true
 }
 
 function runner::run_tear_down() {
@@ -577,8 +646,9 @@ function runner::clear_mocks() {
 }
 
 function runner::run_tear_down_after_script() {
+  local test_file="$1"
   internal_log "run_tear_down_after_script"
-  helper::execute_function_if_exists 'tear_down_after_script'
+  runner::execute_file_hook 'tear_down_after_script' "$test_file"
 }
 
 function runner::clean_set_up_and_tear_down_after_script() {

tests/acceptance/bashunit_setup_before_script_error_test.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+function set_up_before_script() {
+  TEST_ENV_FILE="tests/acceptance/fixtures/.env.default"
+}
+
+function strip_ansi() {
+  sed -E 's/\x1B\[[0-9;]*[A-Za-z]//g'
+}
+
+function test_bashunit_when_set_up_before_script_errors() {
+  local test_file=./tests/acceptance/fixtures/test_bashunit_when_setup_before_script_errors.sh
+  local fixture=$test_file
+
+  local header_line="Running $fixture"
+  local error_line="✗ Error: Set up before script"
+  local message_line="    $fixture: line 4: invalid_function_name: command not found"
+  local tests_summary="Tests:      1 failed, 1 total"
+  local assertions_summary="Assertions: 0 failed, 0 total"
+
+  local actual_raw
+  set +e
+  actual_raw="$(./bashunit --no-parallel --detailed --env "$TEST_ENV_FILE" "$test_file")"
+  set -e
+
+  local actual
+  actual="$(printf "%s" "$actual_raw" | strip_ansi)"
+
+  assert_contains "$header_line" "$actual"
+  assert_contains "$error_line" "$actual"
+  assert_contains "$message_line" "$actual"
+  assert_contains "$tests_summary" "$actual"
+  assert_contains "$assertions_summary" "$actual"
+  assert_general_error "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" "$test_file")"
+}

tests/acceptance/bashunit_teardown_after_script_error_test.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+function set_up_before_script() {
+  TEST_ENV_FILE="tests/acceptance/fixtures/.env.default"
+}
+
+function strip_ansi() {
+  sed -E 's/\x1B\[[0-9;]*[A-Za-z]//g'
+}
+
+function test_bashunit_when_tear_down_after_script_errors() {
+  local test_file=./tests/acceptance/fixtures/test_bashunit_when_teardown_after_script_errors.sh
+  local fixture=$test_file
+
+  local header_line="Running $fixture"
+  local error_line="✗ Error: Tear down after script"
+  local message_line="    $fixture: line 4: missing_cleanup_command: command not found"
+  local tests_summary="Tests:      1 passed, 1 failed, 2 total"
+  local assertions_summary="Assertions: 0 passed, 0 failed, 0 total"
+
+  local actual_raw
+  set +e
+  actual_raw="$(./bashunit --no-parallel --detailed --env "$TEST_ENV_FILE" "$test_file")"
+  set -e
+
+  local actual
+  actual="$(printf "%s" "$actual_raw" | strip_ansi)"
+
+  assert_contains "$header_line" "$actual"
+  assert_contains "$error_line" "$actual"
+  assert_contains "$message_line" "$actual"
+  assert_contains "$tests_summary" "$actual"
+  assert_contains "$assertions_summary" "$actual"
+  assert_general_error "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" "$test_file")"
+}

tests/acceptance/fixtures/test_bashunit_when_setup_before_script_errors.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+function set_up_before_script() {
+  invalid_function_name arg1
+}
+
+function test_dummy() {
+  :
+}

tests/acceptance/fixtures/test_bashunit_when_teardown_after_script_errors.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+function tear_down_after_script() {
+  missing_cleanup_command
+}
+
+function test_sample() {
+  :
+}