aserta

a handy unit testing framework; originally forked from assert.sh

Features
Examples
- Sourcing the script
- Running a single test
Install
- Mac OS X
Reference
- Functions
- Options
License

Features ↑

minimal setup & lightweight interface
time benchmarks with real-time display of test progress
run all tests, stop on first failure, or collect numbers only
automatically set the exit status of the test script
test grouping in individual suites
skip individual tests

Examples ↑

Sourcing the script ↑

Write the following snippet into a new file named my-tests, in the same directory as the aserta script is located.

#!/usr/bin/env bash

source aserta

# Command exit codes
assert_success    "true"
assert_failure    "false"
assert_raises     "unknown_cmd" 127

# Expected output
assert            "echo test"    "test"
assert            "seq 3"        "1\n2\n3"
assert_contains   "echo foobar"  "oba"
assert_startswith "echo foobar"  "foo"
assert_endswith   "echo foobar"  "bar"
assert_matches    "echo foobar"  "^f.*r$"

assert_end "example"

Run it to check that it passes:

$ bash my-tests
all 9 example tests passed in 0.090s.

Now make sure the test fails by changing, for example, the parameter of the first test, from true to false:

assert_success "false"

Run it again to check how it fails now:

$ bash my-tests
test #1 "false" failed:
        program terminated with code 1 instead of 0
1 of 9 example tests failed in 0.089s.

The default error status code is 1:

$ echo $?
1

Running a single test ↑

It is possible to run a single test without sourcing the script, just by passing the desired test function as an argument to the script just after the script options, and then the test function arguments. E.g.:

$ aserta --verbose assert_raises unknown-command 127
.

This way of running tests has several disadvantages:

Only one test can be run on each call.
Can't show test suite summary statistics.
Doesn't support: skip, skip_if and assert_end.

To run a test function without sourcing the script, first make sure the script is executable:

$ chmod +x aserta

And remember to provide the option -v (--verbose) or the option -x (--stop) if you want to see the result of the test. Otherwise it wont have any effect.

$ ./aserta -v assert_success true
.

$ ./aserta -v assert_success false
X

$ ./aserta -x assert_success true

$ ./aserta -x assert_success false
test #1 "false" failed:
        program terminated with code 1 instead of 0

Install ↑

Manually

The latest stable version:

$ wget git.io/aserta.stable && chmod +x aserta

The bleeding edge version (master):

$ wget git.io/aserta && chmod +x aserta

With bpkg
```
$ bpkg install andamira/aserta # -g
```
With basher
```
$ basher install andamira/aserta
```

Mac OS X ↑

The script should work as it is in a Mac OS X system.

But it is encouraged to install the GNU version of coreutils and grep in order to achieve greater speeds in tests with regular expressions, and to be able to measure time in milliseconds, instead of full seconds.

A very easy way to install them is by using Brew:

$ brew tap homebrew/dupes
$ brew install coreutils grep

Reference ↑

Functions ↑

Return Status ↑

assert_raises <command> [exitcode] [STDIN]

Verify the command terminated with the expected status code. The default [exitcode] is assumed to be 0.
assert_success <command> [STDIN]

Verify the command terminated successfully. This is equivalent to assert <command> when no exit code is specified.
assert_failure <command> [STDIN]

Verify the command terminated in failure.

Expected Output ↑

assert <command> [STDOUT] [STDIN]

Verify the command output equals the output string.

STDOUT supports all control sequences echo -e interprets, like \n for a newline.

The default STDOUT is assumed to be empty.
assert_startswith <command> <expected start of STDOUT>

Verify the command output starts with the expected string.
assert_endswith <command> <expected end of STDOUT>

Verify the command output ends with the expected string.
assert_contains <command> <expected part of STDOUT>

Verify the command output contains the expected string.
assert_NOTcontains <command> <not expected part of STDOUT>

Verify the command output does not contain the expected string.
assert_matches <command> <expected matching pattern>

Verify the command output matches the extended REGEXP pattern.

String Comparison ↑

assert_str_equals <string> <expected string>

Verify the first string equals the second string.
assert_str_NOTequals <string> <not expected string>

Verify the first string does not equal the second string.
assert_str_startswith <string> <expected start of string>

Verify the first string starts with the second string.
assert_str_endswith <string> <expected end of string>

Verify the first string ends with the second string.
assert_str_contains <string> <expected part of string content>

Verify the first string contains the second string.
assert_str_NOTcontains <string> <not expected part of string content>

Verify the first string does not contain the second string.
assert_str_matches <string> <expected matching pattern>

Verify the first string matches the extended REGEXP pattern.

Flow Control ↑

assert_end [suite]

Finalize the current test suite and print statistics.
skip

Unconditionally skip the following test case.

The skipped test case is exempt from any test diagnostics, and not accounted for in the total number of tests.
skip_if <command>

Skip the following test case if the command exits successfully.

Use this if you want to run a test only if some precondition is met. E.g. if the test needs root privileges or network access.

Options ↑

See aserta --help for command line options on test runners.

command line option	ENV variable	description
`-c`, `--continue`	`$CONTINUE`	Don't modify exit code depending on suite status.
`-d`, `--discover`	`$DISCOVERONLY`	Collect test suites and number of tests only.
`-i`, `--invariant`	`$INVARIANT`	Don't measure runtime. Useful for parsing output.
`-v`, `--verbose`	`$DEBUG`	Real-time output for every individual test.
`-x`, `--stop`	`$STOP`	Stop running tests after the first failure.

License ↑

The work previous to the fork of assert.sh was released under the LGPLv3 license.
- View COPYING and COPYING.LESSER
The new work in the current project aserta, is released under the MIT license.
- View LICENSE.md

MattSurabian / aserta