Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nextrevision/testdummy

A Shell Script Testing Framework
https://github.com/nextrevision/testdummy

Last synced: 19 days ago
JSON representation

A Shell Script Testing Framework

Awesome Lists containing this project

README 

        
testdummy

=========



[![Circle CI](https://circleci.com/gh/nextrevision/testdummy.svg?style=svg)](https://circleci.com/gh/nextrevision/testdummy)



A shell script testing framework



## Installation



    curl --silent -o testdummy https://raw.githubusercontent.com/nextrevision/testdummy/master/testdummy

    chmod +x testdummy



## Usage



    usage: ./testdummy [args] testfile



    -h|--help     Help

    -d|--debug    Enabled debug logging

    -v|--verbose  Enables verbose logging

    --nocolor     Disable color output

    --version     Prints the version and exits



## Examples



Take a look at the example script and testfile in `examples/`. It can be

run with the following command:



    ./testdummy examples/myscript-test.sh

    

Results in the following output:



    test functions

        test main function with no args                    [PASS]

        test main function args                            [PASS]

        test error function                                [PASS]

        test usage function                                [PASS]



    test runtime execution

        test myscript with no args                         [PASS]

        test myscript with args                            [PASS]



    failing functions

        test myscript with args failure                    [FAIL]

        test myscript mode                                 [FAIL]

    -------------------------------------------------------------

    Tests:    8  |  Passed:    6  |  Failed:    2  |  Time:    0s



## Writing Tests



Tests can be stored in any file, so long as that file can be read by the user

executing the script. `testdummy` sources the file and looks for functions with

specific prefixes and then executes them sequentially.



If you are writing tests for a script, the first thing you probably want to do

is source your script like so:



    source myscript.sh



It's probably useful to surround the entry point of your script with a condition

to ensure that when sourcing, it does not behave the same as when executing. For

example:



    # allow for sourcing

    if [[ $(basename ${0//-/}) == "myscript.sh" ]]; then

      main_function_to_call

    fi



Tests can be defined in functions with specific prefixes. Given the following

function in our script `myscript.sh`:



    _usage() {

      echo "usage: $0 [args]"

    }



We could write a test like so:



    test_usage_function() { _usage | grep -E '^usage:\s'; }



All tests should be wrapped inside of a `testdummy` prefixed function to avoid

any issues when first sourcing the testfile.



#### Test Prefixes



`testdummy` reserves and looks for the following prefixes in function names in

order to know just what to execute:



* `test_`

* `do_`

* `it_`



Functions will be passed over (not executed) unless they start with one of these

prefixes.



### Helpers and Matchers



`testdummy` exposes a set of useful builtin functions for testing commands and

functions.



#### `describe ""`



`describe` is a purely organizational helper that is used for grouping sets of

tests in the output.



Given the following test file:



    describe "test cli flags"

    it_responds_to_help_flag() { ... }

    it_responds_to_verbose_flag() { ... }



    describe "test private functions"

    test_usage_function() { ... }



We could expect the following output:



    test cli flags

      it responds to help flag        [PASS]

      it responds to verbose flag     [PASS]



    test private functions

      test usage function             [PASS]



#### `cmd ""`



`cmd` is executed within a test function and takes a single string argument

that represents the command to execute. `cmd` does not react to failures or

output, but rather stores that information to be tested by other matchers

within the same function.



    test_echo_function() {

      cmd "echo 'this will pass'"

    }

    test_false_function() {

      # will not exit or fail the test

      cmd "/bin/false"

    }



#### `assert_rc `



Asserts that the command executed by the `cmd` function returned the specified

code. If the code does not match, the test function will fail.



Example:



    describe "passing test"

    test_echo_function() {

      cmd "echo 'this will pass'"

      assert_rc 0

    }

    describe "failing test"

    test_false_function() {

      cmd "/bin/false"

      assert_rc 1

    }



#### `assert_content ""`



Asserts that the output of the command executed by the `cmd` function contains

the content of ``. If the output does not, then the test function will

fail. The contents of `` can also be a regex pattern.



Example:



    describe "passing test"

    test_echo_function() {

      cmd "echo 'this will pass'"

      assert_content "will pass"

      assert_content '^this\s\w+'

    }

    describe "failing test"

    test_false_function() {

      cmd "echo 'this will fail'"

      assert_content "banana"

    }



#### Custom



Anything is permitted inside of a `testdummy` test function. There are no

requirements around using the builtin matchers or helpers.



Example:



    describe "passing test"

    test_echo_function() {

      echo "this will pass" | grep -q "pass"

      [ $? -eq 0 ]

    }

    describe "failing test"

    test_false_function() {

      echo "this will fail" | grep -q "pass"

      [ $? -eq 0 ]

    }