Appearance

Skipping and incomplete tests ​

There may be various scenarios where the "passed" and "failed" outcomes for a test are not sufficient. To address these situations, the following functions are available for your use.

bashunit::skip ​

bashunit::skip "[reason]"

Not all tests can be run in every environment; when such situations arise, you can mark a test as skipped.

It reports that the test has been skipped, including the [reason] if one was specified.

Skipping tests will not cause bashunit to exit with an error code; however, it will indicate that some tests were skipped in the final output.

bash
function test_skipped() {
  if [[ $OS != "GEOS" ]]; then
    bashunit::skip && return
  fi

  assert_empty "not reached"
}

function test_skipped_with_reason() {
  if [[ $OS != "GEOS" ]]; then
    bashunit::skip "Not running under Commodore" && return
  fi

  assert_empty "not reached"
}
↷ Skipped: Skipped
↷ Skipped: Skipped with reason
    Not running under Commodore

Tests:      2 skipped, 2 total
Assertions: 2 skipped, 2 total
Some tests skipped

Conditional skips ​

bashunit::skip marks the test skipped but does not stop it, which is why every example above ends in && return. The four helpers below do both: they mark the test skipped and end it right there.

bashunit::skip_if <condition> "[reason]"bashunit::skip_unless <condition> "[reason]"bashunit::skip_unless_command <command> [<command>…]bashunit::skip_on <windows|macos|linux> "[reason]"

The condition of skip_if/skip_unless is evaluated as a shell command, so it may carry arguments. skip_unless_command takes any number of commands and reports requires <command> for the first one missing. skip_on accepts windows, macos or linux; any other name is a usage error rather than a test that silently never skips.

bash
function test_file_permissions() {
  bashunit::skip_on windows "Git Bash fakes POSIX permissions"

  assert_file_permissions 644 "$file"
}

function test_decimal_math() {
  bashunit::skip_unless_command bc

  assert_equals "4.0" "$(calculate "1.5 + 2.5")"
}

function test_only_locally() {
  bashunit::skip_if "[ -n \"${CI:-}\" ]" "too slow for CI"

  assert_successful_code "$(long_running_job)"
}
↷ Skipped: File permissions
    Git Bash fakes POSIX permissions
↷ Skipped: Decimal math
    requires bc

Tests:      2 skipped, 1 passed, 3 total

TIP

Called from inside a test's own $(...) subshell, these helpers end that subshell only — the same as any exit. Call them from the test body.

Do not add && return here

bashunit::skip only marks the test — execution continues, which is why it is written bashunit::skip "reason" && return. The conditional skips stop the test themselves, so they need no return, and adding one breaks them:

bash
bashunit::skip_if "[ 1 -eq 2 ]" "not met" && return   # ✗ ends the test even though
                                                      #   the condition did not hold
assert_same 1 1                                       #   never runs

When the condition does not hold, skip_if returns 0, so && return fires and the test finishes having asserted nothing. It is reported as risky rather than passing, which is the only hint you get.

bashunit::todo ​

bashunit::todo "[pending]"

You may come up with a test that you'd like to implement later. Instead of leaving the test implementation empty —which would mark the test as complete— you can flag it as incomplete.

Reports that the test is incomplete as it is under development, including any [pending] to do details if specified.

Incomplete tests will not cause bashunit to exit with an error code; however, it will indicate that some tests were incomplete in the final output.

bash
function test_incomplete() {
  bashunit::todo
}

function test_incomplete_with_pending_details() {
  bashunit::todo "Detailed description of what needs to be done"
}
✒ Incomplete: Incomplete
✒ Incomplete: Incomplete with pending details
    Detailed description of what needs to be done

Tests:      2 incomplete, 2 total
Assertions: 2 incomplete, 2 total
Some tests incomplete