bats/help: Implement in-process stub, restore

While trying to trigger an error condition for an in-process function
from `lib/bats/assertion-test-helpers` as part of #156, I encountered
the need to use the `hash` builtin for altering the path for a `PATH`
command before and after the `run` command.

Author: mbland

lib/bats/helpers

@@ -295,16 +295,54 @@ split_bats_output_into_lines() {
 # The script is written as `$BATS_TEST_BINDIR/$cmd_name`. `$BATS_TEST_BINDIR` is
 # added to `PATH` and exported if it isn't already present.
 #
+# You may need to call `restore_program_in_path` immediately after `run` to
+# avoid side-effects in the rest of your test program, especially when using the
+# `--in-process` option.
+#
+# Options:
+#   --in-process  Set this when calling `run` on an in-process function
+#
 # Arguments:
 #   cmd_name:  Name of the command from PATH to stub
 #   ...:       Lines comprising the stub script
 stub_program_in_path() {
   local bindir_pattern="^${BATS_TEST_BINDIR}:"
+  local in_process
+
+  if [[ "$1" == '--in-process' ]]; then
+    in_process='true'
+    shift
+  fi
 
   if [[ ! "$PATH" =~ $bindir_pattern ]]; then
     export PATH="$BATS_TEST_BINDIR:$PATH"
   fi
   create_bats_test_script "${BATS_TEST_BINDIR#$BATS_TEST_ROOTDIR/}/$1" "${@:2}"
+
+  if [[ -n "$in_process" ]]; then
+    hash "$1"
+  fi
+}
+
+# Removes a stub program from `PATH`
+#
+# This will return an error if the stub doesn't exist, to help avoid errors
+# when the `cmd_name` arguments to `stub_program_in_path` and this function
+# don't match.
+#
+# Arguments:
+#   cmd_name:  Name of the command from PATH to stub
+#
+# Returns:
+#   Zero if the stub program exists and is removed, nonzero otherwise
+restore_program_in_path() {
+  if [[ -e "$BATS_TEST_BINDIR/$1" ]]; then
+    rm -f "$BATS_TEST_BINDIR/$1"
+    hash "$1"
+  else
+    printf "Bats test stub program doesn't exist: %s\n" "$1"
+    return 1
+  fi
 }
 
 # --------------------------------

tests/bats-helpers.bats

@@ -236,7 +236,7 @@ __check_dirs_exist() {
   assert_lines_equal '' '' 'foo' '' 'bar' '' 'baz'
 }
 
-@test "$SUITE: stub_program_in_path" {
+@test "$SUITE: stub_program_in_path for testing external program" {
   local bats_bindir_pattern="^${BATS_TEST_BINDIR}:"
   fail_if matches "$bats_bindir_pattern" "$PATH"
 
@@ -246,3 +246,20 @@ __check_dirs_exist() {
   run git Hello, World!
   assert_success 'Hello, World!'
 }
+
+@test "$SUITE: {stub,restore}_program_in_path for testing in-process function" {
+  local orig_path="$(command -v mkdir)"
+
+  stub_program_in_path --in-process 'mkdir' 'echo "$@"'
+  run command -v mkdir
+  assert_success "$BATS_TEST_BINDIR/mkdir"
+
+  restore_program_in_path 'mkdir'
+  run command -v mkdir
+  assert_success "$orig_path"
+}
+
+@test "$SUITE: restore_program_in_path fails when stub doesn't exist" {
+  run restore_program_in_path 'foobar'
+  assert_failure "Bats test stub program doesn't exist: foobar"
+}