Appearance

Globals ​

These global helper functions exist primarily to improve your developer experience.

All helper functions use the bashunit:: namespace prefix to prevent naming collisions with your own code.

bashunit::log ​

Write into the BASHUNIT_DEV_LOG a log message. The log line records the source file and line number for easier debugging.

See: Dev log

bash
bashunit::log "hello" "world" # default level: info
bashunit::log "info" "hello" "world"
bashunit::log "debug" "hello" "world"
bashunit::log "warning" "hello" "world"
bashunit::log "critical" "hello" "world"
bashunit::log "error" "hello" "world"

Internal messages from bashunit include the [INTERNAL] prefix so you can easily spot them. You can enable them with BASHUNIT_INTERNAL_LOG=true|false.

bashunit::current_dir ​

bashunit::current_dir: Gets the current directory name.

bashunit::current_filename ​

bashunit::current_filename: Gets the current filename.

bashunit::caller_filename ​

bashunit::caller_filename: Gets the caller filename.

bashunit::caller_line ​

bashunit::caller_line: Gets the line number of the caller.

Useful inside custom assertions to report the line that triggered the failure.

bashunit::current_timestamp ​

bashunit::current_timestamp: Gets the current timestamp.

bashunit::random_str ​

bashunit::random_str <?length>: generate a random string

bashunit::temp_file ​

bashunit::temp_file <?prefix>: creates a temporal file

The file is automatically deleted when bashunit completes.

bashunit::temp_dir ​

bashunit::temp_dir <?prefix>: creates a temporal directory

The directory is automatically deleted when bashunit completes.

bashunit::is_command_available ​

bashunit::is_command_available <command>: Checks if a command is available in PATH.

Returns 0 when the command is found, 1 otherwise.

bash
if bashunit::is_command_available jq; then
  # jq-based assertions
fi

bashunit::print_line ​

bashunit::print_line <?length> <?char>: Prints a horizontal separator.

Defaults to 70 characters of -. Both arguments are optional.

bash
bashunit::print_line          # 70 dashes
bashunit::print_line 40 '='   # 40 equals signs

Conditional skips ​

These mark the test skipped and end it, so no && return is needed. See Skipping and incomplete tests.

  • bashunit::skip_if <condition> [reason] — skip when the condition succeeds.
  • bashunit::skip_unless <condition> [reason] — skip when it fails.
  • bashunit::skip_unless_command <cmd> [cmd...] — skip when a command is missing.
  • bashunit::skip_on <windows|macos|linux> [reason] — skip on that platform.

Custom assertion helpers ​

These helpers are intended for building custom assertions.

  • bashunit::assert_that <expected> <actual> <cmd> [args...] — Run cmd and mark the assertion passed or failed accordingly, in a single call.
  • bashunit::assert_once <?label> <?actual> — Declare that the calling custom assertion counts and reports once, whatever it asserts internally.
  • bashunit::assertion_passed — Mark the current assertion as passed.
  • bashunit::assertion_failed <expected> <actual> <?failure_condition_message> <?label> — Mark the current assertion as failed and print a failure report. label names the assertion in that report, defaulting to the test function name.
  • bashunit::fail <?message> — Fail the current test with an optional message.

See Custom asserts for full examples.

Test doubles ​

The bashunit::spy, bashunit::mock, and bashunit::unmock helpers are documented in Test doubles.