🎓 A1Learner
🔍
0 of 45 lessons completed

Bash Assert Helpers

Assert helpers are small functions that compare an expected value with an actual value. Each helper prints one fixed line that names the check and its result.

An equality helper prints one line per check

The helper compares the expected value with the computed value. The passing check prints PASS and the wrong one prints FAIL with both values.

assert_eq() {
  if [ "$1" = "$2" ]; then
    echo "PASS: $3"
  else
    echo "FAIL: $3 (expected $1, got $2)"
  fi
}
assert_eq 5 "$((2 + 3))" "addition"
assert_eq 4 "$((2 + 3))" "wrong sum"

A contains helper checks a piece of text

The helper uses a case pattern to test whether the text holds the expected piece. The missing piece prints a FAIL line naming it.

assert_contains() {
  case "$2" in
    *"$1"*) echo "PASS: $3" ;;
    *) echo "FAIL: $3 (missing $1)" ;;
  esac
}
assert_contains "hello" "hello world" "greeting"
assert_contains "bye" "hello world" "farewell"

A file helper checks existence first

The helper tests the file before any test reads it. The created file passes and the absent file fails.

assert_file() {
  if [ -f "$1" ]; then
    echo "PASS: $2"
  else
    echo "FAIL: $2 (missing $1)"
  fi
}
printf 'data
' > report.txt
assert_file report.txt "report exists"
assert_file missing.txt "missing file"

Example

passed=0
failed=0
assert_eq() {
  if [ "$1" = "$2" ]; then
    echo "PASS: $3"
    passed=$((passed + 1))
  else
    echo "FAIL: $3 (expected $1, got $2)"
    failed=$((failed + 1))
  fi
}
assert_contains() {
  case "$2" in
    *"$1"*) echo "PASS: $3"; passed=$((passed + 1)) ;;
    *) echo "FAIL: $3 (missing $1)"; failed=$((failed + 1)) ;;
  esac
}
assert_file() {
  if [ -f "$1" ]; then
    echo "PASS: $2"
    passed=$((passed + 1))
  else
    echo "FAIL: $2 (missing $1)"
    failed=$((failed + 1))
  fi
}
printf 'hello world
' > note.txt
content=$(cat note.txt)
assert_eq 5 "$((2 + 3))" "addition"
assert_eq 6 "$((2 * 4))" "product"
assert_contains "hello" "$content" "note greeting"
assert_file note.txt "note exists"
echo "$passed passed, $failed failed"

Key points

  • assert_eq: compare two values and print PASS or FAIL with the check name.
  • One line per check: each helper prints exactly one result line, so output stays readable.
  • Expected first: put the expected value before the actual value, so failures read clearly.
  • assert_contains: check that a longer string holds a shorter expected piece.
  • assert_file: check that a file exists before any test reads it.
  • Failure detail: a FAIL line shows both the expected and the actual value.
  • Honest limit: helpers report failures, but the runner still decides whether to stop.

In this example, three helpers share two counters for passes and failures. Each helper prints one PASS or FAIL line and adds one to the matching counter. The suite runs four checks: a sum, a product, a piece of text, and a file. The final line sums the results: three passes and one failure.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

What does a good assert helper print for each check?