shUnit2 - Function reference

In

General Info

Asserts

Command Description
assertEquals [MESSAGE] EXPECTED ACTUAL Compares Strings and Integer values, the message must be “quoted”
assertNotEquals [MESSAGE] UNEXPECTED ACTUAL Compares Strings and Integer values, the message must be “quoted”
assertSame [MESSAGE] EXPECTED ACTUAL Functionally equivalent to assertEquals
assertNotSame [MESSAGE] UNEXPECTED ACTUAL Functionally equivalent to assertNotEquals
assertContains [MESSAGE] CONTAINER CONTENT Container contains content
assertNotContains [MESSAGE] CONTAINER CONTENT Container does not contain content
assertNull [MESSAGE] VALUE Value is null, or in shell terms, a zero-length string
assertNotNull [MESSAGE] VALUE Value is not null, or in shell terms, a non-empty string
assertTrue [MESSAGE] CONDITION Shell test condition is true
assertFalse [MESSAGE] CONDITION Shell test condition is false
  • Examples:
    • Testing for the ability to read a file can also be done.
      1
      assertTrue 'test failed' "[ -r /some/non-existant/file' ]"
    • Testing using and (-a), or (-o)
      1
      assertTrue 'test failed' '[ 1 -eq 1 -a 2 -eq 2 ]'

Failures

Command Description
fail [MESSAGE] Fails immediately. The message must be quoted
failNotEquals [MESSAGE] UNEXPECTED ACTUAL Fails immediately, reporting that the unexpected and actual values are not equal to one another
failSame [MESSAGE] EXPECTED ACTUAL Fails immediately, reporting that the expected and actual values are the same
failNotSame [message] EXPECTED ACTUAL Fails inmediately, reporting that the expected and actual values are not the same
failFound [message] CONTENT Fails immediately, reporting that the content was found
failNotFound [message] CONTENT Fails the test immediately, reporting that the content was not found

Setup/Teardown

Command Description
oneTimeSetUp Setup common environment
oneTimeTearDown Clean up the environment after all tests
setUp Reset the environment before each test
tearDown Clean up the environment after each test

Skipping

Command Description
startSkipping Forces the remaining assert and fail functions to be “skipped”
endSkipping Returns calls to the assert and fail functions to their default behavior, i.e. they will be called
isSkipping Returns the current state of skipping. It can be compared against ${SHUNIT_TRUE} or ${SHUNIT_FALSE} if desired

Suites

Command Description
suite

  • If this function exists, it will be called when shunit2 is sourced
  • IIf not, shUnit2 will search the parent script for all functions beginning with the word test, and they will be added dynamically to the test suite

    		•
    suite_addTest name

  • This function adds a function named name to the list of tests scheduled for execution as part of this test suite
  • This function should only be called from within the suite() function

    		•

    Advanced

    Constants

    • Predefined

      Constant Value
      SHUNIT_TRUE Standard shell true value (the integer value 0)
      SHUNIT_FALSE Standard shell false value (the integer value 1)
      SHUNIT_ERROR The integer value 2
      SHUNIT_TMPDIR Path to temporary directory that will be automatically cleaned up upon exit of shUnit2
      SHUNIT_VERSION The version of shUnit2 you are running

    • User defined

      Constant Value
      SHUNIT_CMD_EXPR Override which expr command is used. By default expr is used, except on BSD systems where gexpr is used
      SHUNIT_COLOR Enable colorized output. Options are ‘auto’, ‘always’, or ‘none’, with ‘auto’ being the default
      SHUNIT_PARENT The filename of the shell script containing the tests. This is needed specifically for Zsh support
      SHUNIT_TEST_PREFIX Define this variable to add a prefix in front of each test name that is output in the test report

    Error handling

    • The constants values SHUNIT_TRUE, SHUNIT_FALSE, and SHUNIT_ERROR are returned from nearly every function to indicate the success or failure of the function
    • The variable flags_error is filled with a detailed error message if any function returns with a SHUNIT_ERROR value

    Test skipping

    • File
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      # file: examples/math.inc.

      add_generic() {
        num_a=$1
        num_b=$2

        expr $1 + $2
      }

      add_bash() {
        num_a=$1
        num_b=$2

        echo $(($1 + $2))
      }
    • Test file
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      #! /bin/sh
      # file: examples/math_test.sh

      testAdding() {
        result=`add_generic 1 2`
        assertEquals \
            "the result of '${result}' was wrong" \
            3 "${result}"

        # Disable non-generic tests.
        [ -z "${BASH_VERSION:-}" ] && startSkipping

        result=`add_bash 1 2`
        assertEquals \
            "the result of '${result}' was wrong" \
            3 "${result}"
      }

      oneTimeSetUp() {
        # Load include to test.
        . ./math.inc
      }

      # Load and run shUnit2.
      . ./shunit2

    Run specific test

    • Simply run script

      1
      test-script.sh -- testOne testTwo otherFunction

    • Clarifying, with shunit2 call

      1
      shunit2 test-script.sh testOne testTwo otherFunction