Add assert_contains() as a new assertion

README.md

@@ -98,6 +98,31 @@ If either value is longer than one line both are displayed in
 *multi-line* format.
 
 
+### `assert_contains`
+
+Fail and display details if the expected value is not contained
+in the provided array. Details include both values.
+
+```bash
+@test 'assert_contains()' {
+  local items=(one two three)
+  assert_contains "four" "${items[@]}"
+}
+```
+
+On failure, the expected and array values are displayed.
+
+```
+-- item was not found in the array --
+expected : four
+actual   : one two three
+--
+```
+
+If either value is longer than one line both are displayed in
+*multi-line* format.
+
+
 ### `assert_success`
 
 Fail if `$status` is not 0.

src/assert.bash

@@ -92,6 +92,34 @@ assert_equal() {
   fi
 }
 
+# Fail and display details if the expected value is not contained
+# in the provided array. Details include both values.
+#
+# Globals:
+#   none
+# Arguments:
+#   $1 - expected value
+#   ${@:2} - array of values to search
+# Returns:
+#   0 - value is found in array
+#   1 - otherwise
+# Outputs:
+#   STDERR - details, on failure
+assert_contains() {
+  local item
+  for item in "${@:2}"; do
+    if [[ "$item" == "$1" ]]; then
+      return 0
+    fi
+  done
+
+  batslib_print_kv_single_or_multi 8 \
+        'expected' "$1" \
+        'actual'   "$(echo ${@:2})" \
+      | batslib_decorate 'item was not found in the array' \
+      | fail
+}
+
 # Fail and display details if `$status' is not 0. Details include
 # `$status' and `$output'.
 #

test/50-assert-20-contains.bats

@@ -0,0 +1,31 @@
+#!/usr/bin/env bats
+
+load test_helper
+
+@test 'assert_contains() <item> <items>: returns 0 if <item> is in <items>' {
+  local items=(one two three)
+  run assert_contains two "${items[@]}"
+
+  [ "$status" -eq 0 ]
+  [ "${#lines[@]}" -eq 0 ]
+}
+
+@test 'assert_contains() <item> <items>: returns 0 if <item> containing spaces is in <items>' {
+  local items=("one two" three)
+  run assert_contains "one two" "${items[@]}"
+
+  [ "$status" -eq 0 ]
+  [ "${#lines[@]}" -eq 0 ]
+}
+
+@test 'assert_contains() <item> <items>: returns 1 and displays details if <item> is not in <items>' {
+  local items=(one two three)
+  run assert_contains four "${items[@]}"
+
+  [ "$status" -eq 1 ]
+  [ "${#lines[@]}" -eq 4 ]
+  [ "${lines[0]}" == '-- item was not found in the array --' ]
+  [ "${lines[1]}" == 'expected : four' ]
+  [ "${lines[2]}" == 'actual   : one two three' ]
+  [ "${lines[3]}" == '--' ]
+}