NAME

tap.sh - lightweight TAP output generator for bash test suites

SYNOPSIS

tap.sh is intended to make writing TAP-based tests in bash as easy as possible. It consists of a single file that can be included directly in test programs. The resulting test programs can be used with test harnesses such as AutoMake and prove.

DESCRIPTION

Test Control

tap_plan count

Generate TAP plan. If the number of tests is unknown, use tap_done_testing instead.

tap_skip_all [format [arguments]]

Skip all tests.

if [[ $RUN_DEVELOPER_TESTS -eq 1 ]]; then
    run_developer_tests
else
    tap_skip_all "run with RUN_DEVELOPER_TESTS=1 for developer tests"
fi

tap_done_testing

Indicate the end of testing for tests without a plan. If the number of tests is known, use tap_plan instead.

tap_finish

Prints a note summarizing the test results. Returns 1 if there were any failures or the number of tests run does not match the number planned; returns 0 otherwise. Provided as a convenience for tests that may be run outside a TAP harness and/or need to indicate success or failure by exit value.

$tap_todo

Indicate that the following tests are expected to fail. Set to '' to disable.

tap_todo="make 1 equal 2"
tap_is_int 1 2 "1 == 2" # counted as success
tap_todo=''
tap_is_int 1 2 "1 == 2" # counted as failure

void tap_skip count [format [arguments]]

Skip tests.

if [[ $BAZ -eq 1 ]]; then
    tap_ok foo
    tap_ok bar
else
    tap_skip 2 "foo and bar require BAZ"
fi

tap_bail [format [arguments]]

Indicate an unrecoverable error. It is up to the caller to actually exit the test.

tap_diag format [arguments]

Print a diagnostic message. Harnesses should suppress the message for tests marked with tap_todo.

tap_note format [arguments]

Like tap_diag except harnesses should hide the message unless run in verbose mode. Useful for debugging the test itself.

Test Functions

tap_ok success [format [arguments]]

Check test success.

tap_is_str got expected [format [arguments]]

Compare two strings with helpful diagnostic output.

tap_is_int got expected [format [arguments]]

Compare two integers with helpful diagnostic output.

tap_diff got expected [format [arguments]]

Check if two files are identical with helpful diagnostic output.

tap_like got regex [format [arguments]]

Check if a string matches a regular expression with helpful diagnostic output.

Custom Test Functions

Functions beginning with tap_* will be excluded from the caller information printed on test failures.

#!/bin/bash
source tap.sh || exit 1
tap_mytest() {
   tap_is_int 1 2
}
tap_mytest

not ok 1
#   Failed test at tmp.sh line 6.
#          got: '1'
#     expected: '2'

EXAMPLES

Basic Usage

#!/bin/bash

source tap.sh || exit 1

tap_plan 2
...
tap_is_int $? 0 "foo return value"
tap_is_str "foo" "bar"

tap_finish

COPYRIGHT AND LICENSE

Copyright 2014 Andrew Gregory <andrew.gregory.8@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO

http://podwiki.hexten.net/TAP/TAP.html, prove, Test::More

Project URL: http://github.com/andrewgregory/tap.sh