Shell Unit Test Framework

A simple bash test runner
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

• About the Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

All you need is a compatible shell eg bash

Installation

1. Clone the shUnit repo

git clone https://github.com/F0xedb/shUnit.git

copy shunit and assert.sh to your path. eg

cp shunit /usr/bin/shunit
cp assert.sh /usr/bin/assert.sh

Arch user can do the following

yay -Syu shunit
# or manually
makepkg -si

Usage

Running shunit is relatively simple cd into the root directory of the project and run shunit shunit will run all files ending with .shunit

Here is a basic unit test file

# unit test showcase
function Test_AequalsA {
    AssertEqual "a" "a" # no problem
    AssertContains "abcdefg" "def"  # no problem
}

function Test_Fail {
    AssertEquals "a" "b" # error a != b
}

The functions using assert should be prefixed with Test. Only these function will be ran by the unit test runner. Any other function (except for special functions) are helper functions you can use.

The runner outputs the following

$ shunit
> Running unit test : unit test showcase
> Pass: Test_AequalsA
> Error: Test_Fail failed - expected a got b
> unit test failed: Pass: 1 Error: 1

Here is a short list of assertions:

• AssertEquals input a, b -> must equal or an error occurs
• AssertFileEquals input a, b(files) -> must equal or an error occurs
• AssertContains input a,b -> b must be a substring of a
• AssertFileContains input a,b (files- -> b must be inside of a
• AssertExists input a -> Check if a file or variable exists
• AssertTrue input a -> give a shell statement to check if something exists eg [ -f "$A" ]
• Assert input a -> Fails automatically when called. The input is a short message of what went wrong

Here are some simple examples

# Assertion examples

# special functions
# ran once on startup
function setup {
touch a
    cat <<EOF > b
    b
EOF
}
# runs after all tests are completed
function destroy {
    rm a b
}

# unit tests
function Test_exists {
    file="$HOME/h"
    AssertExists "$file" # file doesn't exist so this test fails
}
function Test_content {
    AssertFileEquals "a" "b" # the content is not the same so the test failes
}
function Test_equals {
    AssertEquals "a" "a" # the strings are the same so the test passes
}
function Test_filecontains {
    AssertFileContains "b" "a" # file b contains data in file a so a pass
    AssertFileContains "a" "b" # file a contains nothing so it doesn't contain the data in b => test failed
}

function Test_assert {
    if [[ "a" != "b" ]]; then
        # The 1 indicates that the assert is an error
        # 0 would indicate a success and generate a Pass: check
        assert "1" "A does not equal b" # just errors when this is called
    fi
}

function Test_assert_true {
    assertTrue [[ "a" != "b" ]] # this is the same as the assert function
}

Optionally we have "special" functions for helping your unit tests

• setup # called once per file at the start
• destory # called once per file at the end (even when a test fails)
• setupTest # called before each function
• destroyTest # called after each function

These function don't need to be used, but are usefull to clean up the test suite For more examples, please refer to the Documentation

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GPL License. See LICENSE for more information.

Contact

F0xedb - [email protected]

Project Link: https://github.com/F0xedb/shUnit

Acknowledgements

• F0xedb