dist/atf-sh/libatf-sh.subr

#
# Automated Testing Framework (atf)
#
# Copyright (c) 2007, 2008, 2009, 2010, 2011 The NetBSD Foundation, Inc.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
# IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
# GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
# IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#

set -e

# ------------------------------------------------------------------------
# GLOBAL VARIABLES
# ------------------------------------------------------------------------

# The list of all test cases defined by the test program.
Defined_Test_Cases=

# Values for the expect property.
Expect=pass
Expect_Reason=

# A boolean variable that indicates whether we are parsing a test case's
# head or not.
Parsing_Head=false

# The program name.
Prog_Name=${0##*/}

# The file to which the test case will print its result.
Results_File=

# The test program's source directory: i.e. where its auxiliary data files
# and helper utilities can be found.  Can be overriden through the '-s' flag.
Source_Dir="$(dirname ${0})"

# Indicates the test case we are currently processing.
Test_Case=

# List of meta-data variables for the current test case.
Test_Case_Vars=

# The list of all test cases provided by the test program.
# Subset of ${Defined_Test_Cases}.
Test_Cases=
Test_Cases_With_Cleanup=

# ------------------------------------------------------------------------
# PUBLIC INTERFACE
# ------------------------------------------------------------------------

#
# atf_add_test_case tc-name
#
#   Adds the given test case to the list of test cases that form the test
#   program.  The name provided here must be accompanied by two functions
#   named after it: <tc-name>_head and <tc-name>_body, and optionally by
#   a <tc-name>_cleanup function.
#
atf_add_test_case()
{
    _atf_is_tc_defined "${1}" || \
        _atf_error 128 "Test case ${1} was not correctly defined by" \
                       "this test program"
    Test_Cases="${Test_Cases} ${1}"
}

#
# atf_check cmd expcode expout experr
#
#   Executes atf-check with given arguments and automatically calls
#   atf_fail in case of failure.
#
atf_check()
{
    ${Atf_Check} "${@}" || \
        atf_fail "atf-check failed; see the output of the test for details"
}

#
# atf_check_equal expr1 expr2
#
#   Checks that expr1's value matches expr2's and, if not, raises an
#   error.  Ideally expr1 and expr2 should be provided quoted (not
#   expanded) so that the error message is helpful; otherwise it will
#   only show the values, not the expressions themselves.
#
atf_check_equal()
{
    eval _val1=\"${1}\"
    eval _val2=\"${2}\"
    test "${_val1}" = "${_val2}" || \
        atf_fail "${1} != ${2} (${_val1} != ${_val2})"
}

#
# atf_config_get varname [defvalue]
#
#   Prints the value of a configuration variable.  If it is not
#   defined, prints the given default value.
#
atf_config_get()
{
    _varname="__tc_config_var_$(_atf_normalize ${1})"
    if [ ${#} -eq 1 ]; then
        eval _value=\"\${${_varname}-__unset__}\"
        [ "${_value}" = __unset__ ] && \
            _atf_error 1 "Could not find configuration variable \`${1}'"
        echo ${_value}
    elif [ ${#} -eq 2 ]; then
        eval echo \${${_varname}-${2}}
    else
        _atf_error 1 "Incorrect number of parameters for atf_config_get"
    fi
}

#
# atf_config_has varname
#
#   Returns a boolean indicating if the given configuration variable is
#   defined or not.
#
atf_config_has()
{
    _varname="__tc_config_var_$(_atf_normalize ${1})"
    eval _value=\"\${${_varname}-__unset__}\"
    [ "${_value}" != __unset__ ]
}

#
# atf_expect_death reason
#
#   Sets the expectations to 'death'.
#
atf_expect_death()
{
    _atf_validate_expect

    Expect=death
    _atf_create_resfile expected_death -1 "${@}"
}

#
# atf_expect_timeout reason
#
#   Sets the expectations to 'timeout'.
#
atf_expect_timeout()
{
    _atf_validate_expect

    Expect=timeout
    _atf_create_resfile expected_timeout -1 "${@}"
}

#
# atf_expect_exit exitcode reason
#
#   Sets the expectations to 'exit'.
#
atf_expect_exit()
{
    _exitcode="${1}"; shift

    _atf_validate_expect

    Expect=exit
    _atf_create_resfile expected_exit "${_exitcode}" "${@}"
}

#
# atf_expect_fail reason
#
#   Sets the expectations to 'fail'.
#
atf_expect_fail()
{
    _atf_validate_expect

    Expect=fail
    Expect_Reason="${*}"
}

#
# atf_expect_pass
#
#   Sets the expectations to 'pass'.
#
atf_expect_pass()
{
    _atf_validate_expect

    Expect=pass
    Expect_Reason=
}

#
# atf_expect_signal signo reason
#
#   Sets the expectations to 'signal'.
#
atf_expect_signal()
{
    _signo="${1}"; shift

    _atf_validate_expect

    Expect=signal
    _atf_create_resfile expected_signal "${_signo}" "${@}"
}

#
# atf_expected_failure msg1 [.. msgN]
#
#   Makes the test case report an expected failure with the given error
#   message.  Multiple words can be provided, which are concatenated with
#   a single blank space.
#
atf_expected_failure()
{
    _atf_create_resfile expected_failure -1 "${Expect_Reason}:" "${@}"
    exit 0
}

#
# atf_fail msg1 [.. msgN]
#
#   Makes the test case fail with the given error message.  Multiple
#   words can be provided, in which case they are joined by a single
#   blank space.
#
atf_fail()
{
    case "${Expect}" in
        fail)
            atf_expected_failure "${@}"
            ;;
        pass)
            _atf_create_resfile failed -1 "${@}"
            exit 1
            ;;
        *)
            _atf_error 128 "Unreachable"
            ;;
    esac
}

#
# atf_get varname
#
#   Prints the value of a test case-specific variable.  Given that one
#   should not get the value of non-existent variables, it is fine to
#   always use this function as 'val=$(atf_get var)'.
#
atf_get()
{
    eval echo \${__tc_var_${Test_Case}_$(_atf_normalize ${1})}
}

#
# atf_get_srcdir
#
#   Prints the value of the test case's source directory.
#
atf_get_srcdir()
{
    _atf_internal_get srcdir
}

#
# atf_init_test_cases
#
#   The function in charge of registering the test cases that have to
#   be made available to the user.  Must be redefined.
#
atf_init_test_cases()
{
    _atf_error 128 "No test cases defined"
}

#
# atf_pass
#
#   Makes the test case pass.  Shouldn't be used in general, as a test
#   case that does not explicitly fail is assumed to pass.
#
atf_pass()
{
    case "${Expect}" in
        fail)
            Expect=pass
            atf_fail "Test case was expecting a failure but got a pass instead"
            ;;
        pass)
            _atf_create_resfile passed -1
            exit 0
            ;;
        *)
            _atf_error 128 "Unreachable"
            ;;
    esac
}

#
# atf_require_prog prog
#
#   Checks that the given program name (either provided as an absolute
#   path or as a plain file name) can be found.  If it is not available,
#   automatically skips the test case with an appropriate message.
#
#   Relative paths are not allowed because the test case cannot predict
#   where it will be executed from.
#
atf_require_prog()
{
    _prog=
    case ${1} in
    /*)
        _prog="${1}"
        [ -x ${_prog} ] || \
            atf_skip "The required program ${1} could not be found"
        ;;
    */*)
        atf_fail "atf_require_prog does not accept relative path names \`${1}'"
        ;;
    *)
        _prog=$(_atf_find_in_path "${1}")
        [ -n "${_prog}" ] || \
            atf_skip "The required program ${1} could not be found" \
                     "in the PATH"
        ;;
    esac
}

#
# atf_set varname val1 [.. valN]
#
#   Sets the test case's variable 'varname' to the specified values
#   which are concatenated using a single blank space.  This function
#   is supposed to be called form the test case's head only.
#
atf_set()
{
    ${Parsing_Head} || \
        _atf_error 128 "atf_set called from the test case's body"

    Test_Case_Vars="${Test_Case_Vars} ${1}"
    _var=$(_atf_normalize ${1}); shift
    eval __tc_var_${Test_Case}_${_var}=\"\${*}\"
}

#
# atf_skip msg1 [.. msgN]
#
#   Skips the test case because of the reason provided.  Multiple words
#   can be given, in which case they are joined by a single blank space.
#
atf_skip()
{
    _atf_create_resfile skipped -1 "${@}"
    exit 0
}

#
# atf_test_case tc-name cleanup
#
#   Defines a new test case named tc-name.  The name provided here must be
#   accompanied by two functions named after it: <tc-name>_head and
#   <tc-name>_body.  If cleanup is set to 'cleanup', then this also expects
#   a <tc-name>_cleanup function to be defined.
#
atf_test_case()
{
    Defined_Test_Cases="${Defined_Test_Cases} ${1}"

    eval "${1}_head() { :; }"
    eval "${1}_body() { atf_fail 'Test case not implemented'; }"
    if [ "${2}" = cleanup ]; then
        Test_Cases_With_Cleanup="${Test_Cases_With_Cleanup} ${1}"
        eval "${1}_cleanup() { :; }"
    else
        eval "${1}_cleanup() {
            _atf_error 1 'Test case ${1} declared without a cleanup routine'; }"
    fi
}

# ------------------------------------------------------------------------
# PRIVATE INTERFACE
# ------------------------------------------------------------------------

#
# _atf_config_set varname val1 [.. valN]
#
#   Sets the test case's private variable 'varname' to the specified
#   values which are concatenated using a single blank space.
#
_atf_config_set()
{
    _var=$(_atf_normalize ${1}); shift
    eval __tc_config_var_${_var}=\"\${*}\"
    Config_Vars="${Config_Vars} __tc_config_var_${_var}"
}

#
# _atf_config_set_str varname=val
#
#   Sets the test case's private variable 'varname' to the specified
#   value.  The parameter is of the form 'varname=val'.
#
_atf_config_set_from_str()
{
    _oldifs=${IFS}
    IFS='='
    set -- ${*}
    _var=${1}
    shift
    _val="${@}"
    IFS=${_oldifs}
    _atf_config_set "${_var}" "${_val}"
}

#
# _atf_create_resfile result arg [reason ...]
#
#   Creates the results file.
#
_atf_create_resfile()
{
    _result="${1}"; shift
    if [ "${1}" -eq -1 ]; then
        _arg=""
        shift
    else
        _arg="(${1})"
        shift
    fi
    if [ ${#} -gt 0 ]; then
        _reason=": ${*}"
    else
        _reason=""
    fi

    if [ -n "${Results_File}" ]; then
        echo "${_result}${_arg}${_reason}" >"${Results_File}" || \
            _atf_error 128 "Cannot create results file '${Results_File}'"
    else
        echo "${_result}${_arg}${_reason}"
    fi
}

#
# _atf_ensure_boolean var
#
#   Ensures that the test case defined the variable 'var' to a boolean
#   value.
#
_atf_ensure_boolean()
{
    _atf_ensure_not_empty ${1}

    case $(atf_get ${1}) in
    [Yy][Ee][Ss]|[Tt][Rr][Uu][Ee])
        atf_set ${1} true
        ;;
    [Nn][Oo]|[Ff][Aa][Ll][Ss][Ee])
        atf_set ${1} false
        ;;
    *)
        _atf_error 128 "Invalid value for boolean variable \`${1}'"
        ;;
    esac
}

#
# _atf_ensure_not_empty var
#
#   Ensures that the test case defined the variable 'var' to a non-empty
#   value.
#
_atf_ensure_not_empty()
{
    [ -n "$(atf_get ${1})" ] || \
        _atf_error 128 "Undefined or empty variable \`${1}'"
}

#
# _atf_error error_code [msg1 [.. msgN]]
#
#   Prints the given error message (which can be composed of multiple
#   arguments, in which case are joined by a single space) and exits
#   with the specified error code.
#
#   This must not be used by test programs themselves (hence making
#   the function private) to indicate a test case's failure.  They
#   have to use the atf_fail function.
#
_atf_error()
{
    _error_code="${1}"; shift

    echo "${Prog_Name}: ERROR:" "$@" 1>&2
    exit ${_error_code}
}

#
# _atf_warning msg1 [.. msgN]
#
#   Prints the given warning message (which can be composed of multiple
#   arguments, in which case are joined by a single space).
#
_atf_warning()
{
    echo "${Prog_Name}: WARNING:" "$@" 1>&2
}

#
# _atf_find_in_path program
#
#   Looks for a program in the path and prints the full path to it or
#   nothing if it could not be found.  It also returns true in case of
#   success.
#
_atf_find_in_path()
{
    _prog="${1}"

    _oldifs=${IFS}
    IFS=:
    for _dir in ${PATH}
    do
        if [ -x ${_dir}/${_prog} ]; then
            IFS=${_oldifs}
            echo ${_dir}/${_prog}
            return 0
        fi
    done
    IFS=${_oldifs}

    return 1
}

#
# _atf_has_tc name
#
#   Returns true if the given test case exists.
#
_atf_has_tc()
{
    for _tc in ${Test_Cases}; do
        if [ ${_tc} = ${1} ]; then
            return 0
        fi
    done
    return 1
}

#
# _atf_get_bool varname
#
#   Evaluates a test case-specific variable as a boolean and returns its
#   value.
#
_atf_get_bool()
{
    eval $(atf_get ${1})
}

#
# _atf_internal_get varname
#
#   Prints the value of a test case-specific internal variable.  Given
#   that one should not get the value of non-existent variables, it is
#   fine to always use this function as 'val=$(_atf_internal_get var)'.
#
_atf_internal_get()
{
    eval echo \${__tc_internal_var_${Test_Case}_${1}}
}

#
# _atf_internal_set varname val1 [.. valN]
#
#   Sets the test case's private variable 'varname' to the specified
#   values which are concatenated using a single blank space.
#
_atf_internal_set()
{
    _var=${1}; shift
    eval __tc_internal_var_${Test_Case}_${_var}=\"\${*}\"
}

#
# _atf_list_tcs
#
#   Describes all test cases and prints the list to the standard output.
#
_atf_list_tcs()
{
    echo 'Content-Type: application/X-atf-tp; version="1"'
    echo

    set -- ${Test_Cases}
    while [ ${#} -gt 0 ]; do
        _atf_parse_head ${1}

        echo "ident: $(atf_get ident)"
        for _var in ${Test_Case_Vars}; do
            [ "${_var}" != "ident" ] && echo "${_var}: $(atf_get ${_var})"
        done

        [ ${#} -gt 1 ] && echo
        shift
    done
}

#
# _atf_normalize str
#
#   Normalizes a string so that it is a valid shell variable name.
#
_atf_normalize()
{
    echo ${1} | tr .- __
}

#
# _atf_parse_head tcname
#
#   Evaluates a test case's head to gather its variables and prepares the
#   test program to run it.
#
_atf_parse_head()
{
    ${Parsing_Head} && _atf_error 128 "_atf_parse_head called recursively"
    Parsing_Head=true

    Test_Case="${1}"
    Test_Case_Vars=

    if _atf_has_cleanup "${1}"; then
        atf_set has.cleanup "true"
    fi

    atf_set ident "${1}"
    ${1}_head
    _atf_ensure_not_empty ident
    test $(atf_get ident) = "${1}" || \
        _atf_error 128 "Test case redefined ident"

    Parsing_Head=false
}

#
# _atf_run_tc tc
#
#   Runs the specified test case.  Prints its exit status to the
#   standard output and returns a boolean indicating if the test was
#   successful or not.
#
_atf_run_tc()
{
    case ${1} in
    *:*)
        _tcname=${1%%:*}
        _tcpart=${1#*:}

        if [ "${_tcpart}" != body -a "${_tcpart}" != cleanup ]; then
            _atf_syntax_error "Unknown test case part \`${_tcpart}'"
        fi
        ;;

    *)
        _tcname=${1}
        _tcpart=body
        ;;
    esac

    if _atf_has_tc ${_tcname}; then
        if [ "${__RUNNING_INSIDE_ATF_RUN}" != "internal-yes-value" ]; then
            _atf_warning "Running test cases without atf-run(1) is unsupported"
            _atf_warning "No isolation nor timeout control is being applied;" \
                "you may get unexpected failures; see atf-test-case(4)"
        fi

        _atf_parse_head ${_tcname}

        _atf_internal_set srcdir "${Source_Dir}"

        case ${_tcpart} in
        body)
            if ${_tcname}_body; then
                _atf_validate_expect
                _atf_create_resfile passed -1
            else
                Expect=pass
                atf_fail "Test case body returned a non-ok exit code, but" \
                    "this is not allowed"
            fi
            ;;
        cleanup)
            if _atf_has_cleanup "${_tcname}"; then
                if ${_tcname}_cleanup; then
                    :
                else
                    _atf_error 128 "The test case cleanup returned a non-ok" \
                        "exit code, but this is not allowed"
                fi
            fi
            ;;
        *)
            _atf_error 128 "Unknown test case part"
            ;;
        esac
    else
        _atf_syntax_error "Unknown test case \`${1}'"
    fi
}

#
# _atf_sighup_handler
#
#   Handler for the SIGHUP signal that registers its occurrence so that
#   it can be processed at a later stage.
#
_atf_sighup_handler()
{
    Held_Signals="${Held_Signals} SIGHUP"
}

#
# _atf_sigint_handler
#
#   Handler for the SIGINT signal that registers its occurrence so that
#   it can be processed at a later stage.
#
_atf_sigint_handler()
{
    Held_Signals="${Held_Signals} SIGINT"
}

#
# _atf_sigterm_handler
#
#   Handler for the SIGTERM signal that registers its occurrence so that
#   it can be processed at a later stage.
#
_atf_sigterm_handler()
{
    Held_Signals="${Held_Signals} SIGTERM"
}

#
# _atf_syntax_error msg1 [.. msgN]
#
#   Formats and prints a syntax error message and terminates the
#   program prematurely.
#
_atf_syntax_error()
{
    echo "${Prog_Name}: ERROR: ${@}" 1>&2
    echo "${Prog_Name}: See atf-test-program(1) for usage details." 1>&2
    exit 1
}

#
# _atf_is_tc_defined tc-name
#
#   Returns a boolean indicating if the given test case was defined by the
#   test program or not.
#
_atf_is_tc_defined()
{
    for _tc in ${Defined_Test_Cases}; do
        [ ${_tc} = ${1} ] && return 0
    done
    return 1
}

#
# _atf_has_cleanup tc-name
#
#   Returns a boolean indicating if the given test case has a cleanup
#   routine or not.
#
_atf_has_cleanup()
{
    for _tc in ${Test_Cases_With_Cleanup}; do
        [ ${_tc} = ${1} ] && return 0
    done
    return 1
}

#
# _atf_validate_expect
#
#   Ensures that the current test case state is correct regarding the expect
#   status.
#
_atf_validate_expect()
{
    case "${Expect}" in
        death)
            Expect=pass
            atf_fail "Test case was expected to terminate abruptly but it" \
                "continued execution"
            ;;
        exit)
            Expect=pass
            atf_fail "Test case was expected to exit cleanly but it continued" \
                "execution"
            ;;
        fail)
            Expect=pass
            atf_fail "Test case was expecting a failure but none were raised"
            ;;
        pass)
            ;;
        signal)
            Expect=pass
            atf_fail "Test case was expected to receive a termination signal" \
                "but it continued execution"
            ;;
        timeout)
            Expect=pass
            atf_fail "Test case was expected to hang but it continued execution"
            ;;
        *)
            _atf_error 128 "Unreachable"
            ;;
    esac
}

#
# _atf_warning [msg1 [.. msgN]]
#
#   Prints the given warning message (which can be composed of multiple
#   arguments, in which case are joined by a single space).
#
#   This must not be used by test programs themselves (hence making
#   the function private).
#
_atf_warning()
{
    echo "${Prog_Name}: WARNING:" "$@" 1>&2
}

#
# main [options] test_case
#
#   Test program's entry point.
#
main()
{
    # Process command-line options first.
    _numargs=${#}
    _lflag=false
    while getopts :lr:s:v: arg; do
        case ${arg} in
        l)
            _lflag=true
            ;;

        r)
            Results_File=${OPTARG}
            ;;

        s)
            Source_Dir=${OPTARG}
            ;;

        v)
            _atf_config_set_from_str "${OPTARG}"
            ;;

        \?)
            _atf_syntax_error "Unknown option -${OPTARG}."
            # NOTREACHED
            ;;
        esac
    done
    shift `expr ${OPTIND} - 1`

    # First of all, make sure that the source directory is correct.  It
    # doesn't matter if the user did not change it, because the default
    # value may not work.  (TODO: It possibly should, even though it is
    # not a big deal because atf-run deals with this.)
    case ${Source_Dir} in
        /*)
            ;;
        *)
            Source_Dir=$(pwd)/${Source_Dir}
            ;;
    esac
    [ -f ${Source_Dir}/${Prog_Name} ] || \
        _atf_error 1 "Cannot find the test program in the source" \
                     "directory \`${Source_Dir}'"

    # Set some global variables useful to the user.  Not specific to the
    # test case because they may be needed during initialization too.
    # XXX I'm not too fond on this though.  Sure, it is very useful in some
    # situations -- such as in NetBSD's fs/tmpfs/* tests where each test
    # program includes a helper subroutines file -- but there are also
    # other, maybe better ways to achieve the same.  Because, for example,
    # at the moment it is not possible to detect failures in the inclusion
    # and report them nicely.  Plus this change is difficult to implement
    # in the current C++ API.
    _atf_internal_set srcdir "${Source_Dir}"

    # Call the test program's hook to register all available test cases.
    atf_init_test_cases

    # Run or list test cases.
    if `${_lflag}`; then
        if [ ${#} -gt 0 ]; then
            _atf_syntax_error "Cannot provide test case names with -l"
        fi
        _atf_list_tcs
    else
        if [ ${#} -eq 0 ]; then
            _atf_syntax_error "Must provide a test case name"
        elif [ ${#} -gt 1 ]; then
            _atf_syntax_error "Cannot provide more than one test case name"
        else
            _atf_run_tc "${1}"
        fi
    fi
}

# vim: syntax=sh:expandtab:shiftwidth=4:softtabstop=4