From fbf902b2c69ab2b21e3c4af068db23d6e4ee791b Mon Sep 17 00:00:00 2001
From: Chris Koeritz <fred@gruntose.com>
Date: Wed, 23 Sep 2020 11:01:26 -0400
Subject: [PATCH] added more example assertions and shunit docs in blank

blank test is now our self-documenting test that describes how to use shunit.  it has an example of every major assert and fail method now.
---
 testkit/examples/blank_test.sh | 98 ++++++++++++++++++++++++++++++++--
 1 file changed, 93 insertions(+), 5 deletions(-)

diff --git a/testkit/examples/blank_test.sh b/testkit/examples/blank_test.sh
index 239cbe73..aa77ac3e 100644
--- a/testkit/examples/blank_test.sh
+++ b/testkit/examples/blank_test.sh
@@ -1,14 +1,15 @@
 #!/bin/bash
 
-# Test: X
-# Author: Y
+# Test: Blank
+# Author: Fill ItIn
 
 export WORKDIR="$( \cd "$(\dirname "$0")" && \pwd )"  # obtain the script's working directory.
 cd "$WORKDIR"
 
-# this needs to be relative to where the test will actually reside; the ../../../../../etc
-# should get to the top of the tools and tests hierarchy.
-source "../prepare_tools.sh" "../prepare_tools.sh"
+# this needs to be relative to where the test will actually reside; the .. components below
+# need to get to the top of the tools and tests hierarchy.
+relative_depth=".."
+source "$relative_depth/prepare_tools.sh" "$relative_depth/prepare_tools.sh"
 if [ -z "$TEST_TEMP" ]; then
   echo The TestKit could not be automatically located.
   exit 1
@@ -54,6 +55,93 @@ testDoAnotherThing()
   assertNotEquals "an explicit failure should be seen" 0 $?
 }
 
+testShunitExamples()
+{
+  echo running through shunit tests available.
+
+  # values must be the same.
+  assertEquals "equals test" 5 5
+
+  # similar test, different name.
+  assertSame "same test" oof oof
+
+  # values must not be the same.
+  assertNotEquals "not equals test" 3 5
+
+  # a parallel not same test.
+  assertNotSame "not same test" orp 3
+  
+  # value must have no content (or not be defined).
+  assertNull "empty null test" ""
+  assertNull "undefined null test" "$variableDoesntExistOrShouldntSinceWeDidntDefineIt"
+
+  # value must have content.
+  assertNotNull "not null test" "sugarwater"
+
+  # value must be true, which in bash means equal to zero.
+  assertTrue "true test simple" 0
+  # this shows how true return value can be tested.
+  true
+  assertTrue "true test return value" $?
+
+  # value must be false, or non-zero.
+  assertFalse "false test simple" 13
+  # shows how false return value can be tested.
+  false
+  assertFalse "false test" $?
+}
+
+testShowSkipping()
+{
+  # the failures below are intentionally skipped, so as to avoid the failure
+  # results in our full output.
+  # this shows two things; how to skip the rest of the tests if needed,
+  # and how to cause a test failure without using an assertion.
+  
+  # show if we're skipping already.
+  isSkipping
+  if [ $? -eq 0 ]; then
+    echo we are skipping tests.
+  else
+    echo we are not skipping tests.
+  fi
+
+  # start skipping tests.
+  startSkipping
+
+  # show that we're skipping.
+  isSkipping
+  if [ $? -eq 0 ]; then
+    echo we are skipping tests.
+  else
+    echo we are not skipping tests.
+  fi
+
+  # can be used to set a test failed state, without using an assertion.
+  # this might be used if there is complex logic and one doesn't feel
+  # like boiling that down to a single variable to test on.
+  fail "one of the tests above failed"
+
+  # indicates a failure because two values were not the same.
+  failNotSame "values should have been the same" toyBoat oatBoy
+
+  # indicates a failure when two values should have been different.
+  failSame "values should not have been the same" 3 3
+
+  # stop skipping tests again.
+  endSkipping
+
+  # show that we're no longer skipping.
+  isSkipping
+  if [ $? -eq 0 ]; then
+    echo we are skipping tests.
+  else
+    echo we are not skipping tests.
+  fi
+
+  assertSame "shunit is cool" cool cool
+}
+
 oneTimeTearDown() {
   # cleaning up after test, if needed.
   true
-- 
2.34.1