Bump version to 0.3.0

This allows checking if a stub was called even after it's been restored
to it's original. Called state is only reset when a new stub is created
for the same command.

.travis.yml

@@ -1,2 +1,2 @@
 language: node_js
-script: make test
+script: INVARIANT=1 make test

Makefile

@@ -5,7 +5,7 @@ prepare:
 	test -f "test/assert.sh" || ( \
 		echo "fetching assert.sh..." && \
 		curl -s -L -o test/assert.sh \
-			https://raw.github.com/lehmannro/assert.sh/master/assert.sh \
+			https://raw.github.com/lehmannro/assert.sh/v1.0.2/assert.sh \
 	)
 
 .SILENT:

README.md

@@ -40,18 +40,47 @@ restore my-name-is
 my-name-is Edward Elric #=> My name is Edward Elric.
 ```
 
+Asserting stub has been called:
+
+```bash
+source "stub.sh"
+my-uname() { uname; }
+stub_and_echo uname "FooBar"
+stub_called uname # return value of 1 (error)
+my-uname            #=> FooBar
+stub_called uname # return value of 0 (success)
+restore uname
+```
+
+Asserting stub has been called X times:
+
+```bash
+source "stub.sh"
+my-uname() { uname; }
+stub_and_echo uname "FooBar"
+stub_called_times uname   #=> 0
+stub_called_times uname 2 # return value of 1 (error)
+my-uname                  #=> FooBar
+stub_called_times uname   #=> 1
+stub_called_times uname 2 # return value of 1 (error)
+my-uname                  #=> FooBar
+stub_called_times uname   #=> 2
+stub_called_times uname 2 # return value of 0 (success)
+restore uname
+```
+
 
 ## Function Reference
 
 - `stub`: Basic stubbing command. Will echo a default message to STDOUT.
   Arguments:
     - `$1`: Name of command to stub
-    - `$2`: When set to "STDERR", echo to STDERR instead of STDOUT.
+    - `$2`: When set to "STDERR", echo to STDERR instead of STDOUT (optional).
 - `stub_and_echo`: Stub given command and echo a custom string to STDOUT.
   Arguments:
     - `$1`: Name of command to stub.
     - `$2`: String to echo when stub is called.
-    - `$3`: When set to "STDERR", echo to STDERR instead of STDOUT.
+    - `$3`: When set to "STDERR", echo to STDERR instead of STDOUT (optional).
 - `stub_and_eval`: Stub given command and execute custom commands via eval.
   Arguments:
     - `$1`: Name of command to stub.
@@ -59,6 +88,29 @@ my-name-is Edward Elric #=> My name is Edward Elric.
 - `restore`: Restores use of original binary/function that was stubbed.
   Arguments:
     - `$1`: Name of command to restore.
+- `stub_called`: Check if given stub has been called. Gives a `0` return value
+  when true, and `1` when false.
+    - `$1`: Name of stub to check.
+- `stub_called_times`: Find out how many times a stub has been called, or
+  given a second argument it validates if stub was called exactly X times.
+    - `$1`: Name of stub to check.
+    - `$2`: Exact number of times stub should have been called (optional).
+- `stub_called_at_least_times`: Validate that stub has been called at least X
+  number of times.
+    - `$1`: Name of stub to check.
+    - `$2`: Minimum number of times stub should have been called.
+- `stub_called_at_most_times`: Validate that stub has been called no more than
+  X number of times.
+    - `$1`: Name of stub to check.
+    - `$2`: Maximum number of times stub should have been called.
+
+
+## Todo
+
+- Add a `stub_called_with` function that validates the stub has been called
+  with specific arguments.
+- Add a `stub_called_with_times` function that validates the stub has been
+  called with specific arguments a specific number of times.
 
 
 ## License

stub.sh

@@ -1,5 +1,5 @@
 # !/usr/bin/env bash
-# stub.sh 0.2.0 - stubbing helpers for simplifying bash script tests.
+# stub.sh 0.3.0 - stubbing helpers for simplifying bash script tests.
 # Copyright (c) 2014 Jim Myhrberg.
 #
 # https://github.com/jimeh/stub.sh
@@ -24,14 +24,15 @@
 #
 
 
-# Stub given command, echoing a default stub message.
+# Public: Stub given command, echoing a default stub message.
 #
 # Arguments:
 #   - $1: Name of command to stub.
 #   - $2: When set to "STDERR", echo to STDERR instead of STDOUT.
 #         When set to "null", all output is redirected to /dev/null.
 #
-#
+# Echoes nothing.
+# Returns nothing.
 stub() {
   local redirect="null"
   if [ "$2" == "stdout" ] || [ "$2" == "STDOUT" ]; then redirect=""; fi
@@ -41,7 +42,7 @@ stub() {
 }
 
 
-# Stub given command, and echo given string.
+# Public: Stub given command, and echo given string.
 #
 # Arguments:
 #   - $1: Name of command to stub.
@@ -49,6 +50,8 @@ stub() {
 #   - $3: When set to "STDERR", echo to STDERR instead of STDOUT.
 #         When set to "null", all output is redirected to /dev/null.
 #
+# Echoes nothing.
+# Returns nothing.
 stub_and_echo() {
   local redirect=""
   if [ "$3" == "stderr" ] || [ "$3" == "STDERR" ]; then redirect=" 1>&2"; fi
@@ -58,15 +61,23 @@ stub_and_echo() {
 }
 
 
-# Stub given command, and execute given string with eval.
+# Public: Stub given command, and execute given string with eval.
 #
 # Arguments:
 #   - $1: Name of command to stub.
 #   - $2: String to eval when stub is called.
 #
+# Echoes nothing.
+# Returns nothing.
 stub_and_eval() {
   local cmd="$1"
 
+  # Setup empty list of called stubs.
+  if [ -z "$STUB_CALLED_STUBS" ]; then STUB_CALLED_STUBS=(); fi
+
+  # Setup empty list of active stubs.
+  if [ -z "$STUB_ACTIVE_STUBS" ]; then STUB_ACTIVE_STUBS=(); fi
+
   # If stubbing a function, store non-stubbed copy of it required for restore.
   if [ -n "$(command -v "$cmd")" ]; then
     if [ -z "$(command -v "non_stubbed_${cmd}")" ]; then
@@ -78,35 +89,129 @@ stub_and_eval() {
     fi
   fi
 
-  # Use a function to keep track of if the command is stubbed, as variable
-  # names doesn't support the "-" character, while function names do.
-  eval "$(echo -e "${cmd}_is_stubbed() {\n  return 0\n}")"
+  # Keep track of what is currently stubbed to ensure restore only acts on
+  # actual stubs.
+  if [[ " ${STUB_ACTIVE_STUBS[@]} " != *" $1 "* ]]; then
+    STUB_ACTIVE_STUBS+=("$cmd")
+  fi
+
+  # Remove stub from list of called stubs, as we are now creating a new stub
+  # which hasn't been called yet.
+  STUB_CALLED_STUBS=(${STUB_CALLED_STUBS[@]/$cmd/})
 
   # Create the stub.
-  eval "$(echo -e "${cmd}() {\n  $2\n}")"
+  eval "$(echo -e "${cmd}() {\n  __stub_call \"${cmd}\"\n  $2\n}")"
 }
 
 
-# Restore the original command/function that was stubbed.
+# Public: Find out if stub has been called. Returns 0 if yes, 1 if no.
+#
+# Arguments:
+#   - $1: Name of stubbed command.
+#
+# Echoes nothing.
+# Returns 0 (success) is stub has been called, 1 (error) otherwise.
+stub_called() {
+  if [[ " ${STUB_CALLED_STUBS[@]} " != *" $1 "* ]]; then
+    return 1
+  fi
+}
+
+
+# Public: Find out how many times a stub has been called.
+#
+# Arguments:
+#   - $1: Name of stubbed command.
+#   - $2: When specified, will check if stub was called exactly the given
+#         number of times (optional).
+#
+# Examples:
+#   stub_called_times "uname"   # Echoes "2" if stub has been called twice.
+#   stub_called_times "uname" 2 # Returns value of 0 (success).
+#   stub_called_times "uname" 3 # Returns value of 1 (error).
+#
+# Echoes number of times stub has been called if $2 is not given, otherwise
+# echoes nothing.
+# Returns 0 (success) if $2 is not given, or if it is given and it matches the
+# number of times the stub has been called. Otherwise 1 (error) is returned if
+# it doesn't match..
+stub_called_times() {
+  local count=0
+
+  for called in ${STUB_CALLED_STUBS[@]}; do
+    if [ "$called" == "$1" ]; then
+      ((count++))
+    fi
+  done
+
+  if [ -n "$2" ]; then
+    if [ "$2" != "$count" ]; then
+      return 1
+    fi
+  else
+    echo $count
+  fi
+}
+
+
+# Public: Find out of stub has been called at least the given number of times.
+#
+# Arguments:
+#   - $1: Name of stubbed command.
+#   - $2: Minimum required number of times stub has been called.
+#
+# Echoes nothing.
+# Returns 0 (success) if stub has been called at least the given number of
+# times, otherwise 1 (error) is returned.
+stub_called_at_least_times() {
+  if [ "$(stub_called_times "$1")" -lt "$2" ]; then
+    return 1
+  fi
+}
+
+
+# Public: Find out of stub has been called no more than the given number of
+# times.
+#
+# Arguments:
+#   - $1: Name of stubbed command.
+#   - $2: Minimum required number of times stub has been called.
+#
+# Echoes nothing.
+# Returns 0 (success) if stub has been called no more than the given number of
+# times, otherwise 1 (error) is returned.
+stub_called_at_most_times() {
+  if [ "$(stub_called_times "$1")" -gt "$2" ]; then
+    return 1
+  fi
+}
+
+
+# Public: Restore the original command/function that was stubbed.
 #
 # Arguments:
 #   - $1: Name of command to restore.
 #
+# Echoes nothing.
+# Returns nothing.
 restore() {
   local cmd="$1"
 
   # Don't do anything if the command isn't currently stubbed.
-  if [[ "$(type "${cmd}_is_stubbed" 2>&1)" == *"not found"* ]]; then
-    return 0;
+  if [[ " ${STUB_ACTIVE_STUBS[@]} " != *" $1 "* ]]; then
+    return 0
   fi
 
   # Remove stub functions.
-  unset -f "${cmd}_is_stubbed"
   unset -f "$cmd"
 
+  # Remove stub from list of active stubs.
+  STUB_ACTIVE_STUBS=(${STUB_ACTIVE_STUBS[@]/$cmd/})
+
   # If stub was for a function, restore the original function.
   if type "non_stubbed_${cmd}" &>/dev/null; then
-    if [[ "$(type "non_stubbed_${cmd}" | head -1)" == *"is a function" ]]; then
+    local original_type="$(type "non_stubbed_${cmd}" | head -1)"
+    if [[ "$original_type" == *"is a function" ]]; then
       local source="$(type "non_stubbed_$cmd" | tail -n +2)"
       source="${source/non_stubbed_${cmd}/$cmd}"
       eval "$source"
@@ -114,3 +219,14 @@ restore() {
     fi
   fi
 }
+
+
+#
+# Internal functions
+#
+
+# Private: Used to keep track of which stubs have been called and how many
+# times.
+__stub_call() {
+  STUB_CALLED_STUBS+=("$1")
+}

test/stub_called-test.sh

@@ -0,0 +1,44 @@
+#! /usr/bin/env bash
+source "test-helper.sh"
+
+#
+# stub_called() tests.
+#
+
+# Returns 1 when stub doesn't exist.
+assert_raises 'stub_called "uname"' 1
+
+# Returns 1 when stub hasn't been called.
+stub "uname"
+assert_raises 'stub_called "uname"' 1
+restore "uname"
+
+# Returns 0 when stub has been called.
+stub "uname"
+uname
+assert_raises 'stub_called "uname"' 0
+restore "uname"
+
+# Stub called state is reset by creating a new stub, not by restore.
+stub "uname"
+uname
+restore "uname"
+assert_raises 'stub_called "uname"' 0
+stub "uname"
+assert_raises 'stub_called "uname"' 1
+restore "uname"
+
+# Recreating a stub only resets called state of recreated stub.
+stub "uname"
+stub "top"
+uname
+top
+stub "uname"
+assert_raises 'stub_called "uname"' 1
+assert_raises 'stub_called "top"' 0
+restore "uname"
+restore "top"
+
+
+# End of tests.
+assert_end "stub_called()"

test/stub_called_at_least_times-test.sh

@@ -0,0 +1,32 @@
+#! /usr/bin/env bash
+source "test-helper.sh"
+
+#
+# stub_called_at_least_times() tests.
+#
+
+# Setup
+stub "uname"
+uname
+uname
+
+# Returns 0 when stub called at least given number of times.
+assert_raises 'stub_called_at_least_times "uname" 0' 0
+assert_raises 'stub_called_at_least_times "uname" 1' 0
+assert_raises 'stub_called_at_least_times "uname" 2' 0
+
+# Returns 1 when stub has been called less than given number of times.
+assert_raises 'stub_called_at_least_times "uname" 3' 1
+assert_raises 'stub_called_at_least_times "uname" 4' 1
+assert_raises 'stub_called_at_least_times "uname" 5' 1
+
+# Behaves as if stub has not been called when the stub doesn't exist.
+assert_raises 'stub_called_at_least_times "top" 0' 0
+assert_raises 'stub_called_at_least_times "top" 1' 1
+
+# Teardown
+restore "uname"
+
+
+# End of tests.
+assert_end "stub_called_at_least_times()"

test/stub_called_at_most_times-test.sh

@@ -0,0 +1,33 @@
+#! /usr/bin/env bash
+source "test-helper.sh"
+
+#
+# stub_called_at_most_times() tests.
+#
+
+# Setup
+stub "uname"
+uname
+uname
+uname
+
+# Returns 0 when stub called no more than given number of times.
+assert_raises 'stub_called_at_most_times "uname" 5' 0
+assert_raises 'stub_called_at_most_times "uname" 4' 0
+assert_raises 'stub_called_at_most_times "uname" 3' 0
+
+# Returns 1 when stub has been called more than given number of times.
+assert_raises 'stub_called_at_most_times "uname" 2' 1
+assert_raises 'stub_called_at_most_times "uname" 1' 1
+assert_raises 'stub_called_at_most_times "uname" 0' 1
+
+# Behaves as if stub has not been called when the stub doesn't exist.
+assert_raises 'stub_called_at_most_times "top" 0' 0
+assert_raises 'stub_called_at_most_times "top" 1' 0
+
+# Teardown
+restore "uname"
+
+
+# End of tests.
+assert_end "stub_called_at_most_times()"

test/stub_called_times-test.sh

@@ -0,0 +1,42 @@
+#! /usr/bin/env bash
+source "test-helper.sh"
+
+#
+# stub_called_times() tests.
+#
+
+# Echoes 0 if the command isn't stubed.
+assert 'stub_called_times "top"' "0"
+
+# Echoes the number of times a stub was called.
+stub "uname"
+assert 'stub_called_times "uname"' "0"
+uname
+assert 'stub_called_times "uname"' "1"
+uname
+assert 'stub_called_times "uname"' "2"
+uname
+assert 'stub_called_times "uname"' "3"
+restore "uname"
+
+# Echoes 0 after a called stub has been recreated.
+stub "uname"
+uname
+assert 'stub_called_times "uname"' "1"
+restore "uname"
+assert 'stub_called_times "uname"' "1"
+stub "uname"
+assert 'stub_called_times "uname"' "0"
+restore "uname"
+
+# When given a second argument, asserts stub called X number of times.
+stub "uname"
+uname
+assert_raises 'stub_called_times "uname" 1' 0
+assert 'stub_called_times "uname" 1' ""
+assert_raises 'stub_called_times "uname" 3' 1
+assert 'stub_called_times "uname" 3' ""
+restore "uname"
+
+# End of tests.
+assert_end "stub_called_times()"