shellfu-bash-jat/src/jat.sh.skel

#!/bin/bash

shellfu import pretty
shellfu import isa
shellfu import termcolors

#
# Just A[nother] Test assert and logging library
#
#
# COMMON ARGUMENTS
# ================
#
# Assert functions share following parameters:
#
#  *  `-b BEID`   Behavior Evidence ID; is a Simple Name (see STRINGS)
#     associated with a particular behavior.  If provided, BEID is merely
#     included within the log, see BEHAVIOR EVIDENCE ID section for more
#     details.
#
#  *  `-c CASEID`   Case ID; together with $JAT__TEST_ID can be used to
#     uniquely identify a particular test case, with granularity up to
#     single assert.  CASEID set here is joined with any CASEIDs set
#     by active phase.
#
#  *  `-h HINT`   Human-readable description used to describe meaning of
#     the assertion to reader.  Note that HINT should be worded in such
#     way that it makes claim about the reality that matches expectation.
#     That is, to reader of the log, a passing assert tells true, but
#     a failing assert "lies".
#
# Phase start functions share following parameters:
#
#  *  `-C DIR`  Change to directory DIR for duration of the phase.
#
#  *  `-c CASEID`  Inherit CASEID as Case ID to all asserts in this
#     phase.  Individual asserts can extend the final case id for
#     extra granularity and profit.
#
#
# STRINGS
# =======
#
# Many strings, when passed to jat functions, are internally used
# as paths, prefixes or identifiers.  For this reason, they may be
# restricted to contain only "safe" chars.  Following classes are
# defined:
#
#  *  *simple word* - must begin with letter or underscore; second
#     and further characters may be letter, digit or underscore.
#

#
# Path to result directory
#
JAT__DIR=${JAT__DIR:-/var/tmp/jat}

#
# Path to result log
#
# If unset, another identical log is *still* created under a unique
# subdirectory of $JAT__DIR.  Set this if you want to have log at
# a predictable path.  This can be useful  eg. if you want to send
# log into a named pipe.
#
JAT__YLOG=${JAT__YLOG:-}

#
# Behavior Evidence ID namespace
#
# All BEIDs will be prefixed by this namespace qualifier,
# and meaning of them must be defined within that namespace.
#
JAT__BEID_NS=${JAT__BEID_NS:-_jat_anon_beid_ns_}

#
# Test name
#
JAT__TEST_ID=${JAT__TEST_ID:-_jat_anon_test_}

#
# Test version
#
JAT__TEST_VERSION=${JAT__TEST_VERSION:-_jat_no_test_version_}

#
# Path to main logfile
#
__JAT__SDIR=

#
# Colored words for `jat__show_*` functions
#
__JAT__SWORD_END=${TERMCOLORS_LBLACK}END${TERMCOLORS_NONE}
__JAT__SWORD_FAIL=${TERMCOLORS_RED}FAIL${TERMCOLORS_NONE}
__JAT__SWORD_FINALIZE=${TERMCOLORS_LBLACK}FINALIZE${TERMCOLORS_NONE}
__JAT__SWORD_PASS=${TERMCOLORS_GREEN}PASS${TERMCOLORS_NONE}
__JAT__SWORD_PHASE=${TERMCOLORS_YELLOW}phase${TERMCOLORS_NONE}
__JAT__SWORD_RELOAD=${TERMCOLORS_LBLUE}RELOAD${TERMCOLORS_NONE}
__JAT__SWORD_SESSION=${TERMCOLORS_YELLOW}session${TERMCOLORS_NONE}
__JAT__SWORD_START=${TERMCOLORS_LBLACK}START${TERMCOLORS_NONE}
__JAT__SWORD_SUT=${TERMCOLORS_YELLOW}sut${TERMCOLORS_NONE}
__JAT__SWORD_TERROR=${TERMCOLORS_RED}ERROR${TERMCOLORS_NONE}
__JAT__SWORD_TEST=${TERMCOLORS_YELLOW}test${TERMCOLORS_NONE}
__JAT__SWORD_TINFO=${TERMCOLORS_LBLACK}INFO${TERMCOLORS_NONE}
__JAT__SWORD_TWARNING=${TERMCOLORS_RED}WARNING${TERMCOLORS_NONE}


#
# Make result log deterministic?
#
# Determines whether result should be made deterministic.  Currently
# this means that instead of wall clock time, timestamps will be simply
# ordinal stamps like `time-1`, `time-2`...
#
# This makes test log deterministic, enabling comparison of multiple
# runs against each other or against fixed oracle.  The disadvantage
# is that you can't assess performance data from the log.
#
__JAT__DETERMINISTIC=true

#
# Log format version
#
__JAT__LOG_FMT='jat/0.0'

#
# Self version (in variable to enable overriding in unit tests)
#
__JAT__SELF_VERSION=__MKIT_PROJ_VERSION__

jat__cmd() {
    #
    # Assert that command $@ returns zero (or other)
    #
    # Usage:
    #
    #     jat__cmd [-o R_OUT] [-e R_ERR] [-s R_ESF] [-S ES_EXPR] [--] CMD [ARG]..
    #
    # Run CMD with all ARGs and if exit status is zero, announce assertion
    # success (PASS), otherwise announce assertion failure (FAIL).
    #
    # Exit status expectation can be changed from zero to ES_EXPR, which
    # must be in form of comma-separated list of integer values or ranges
    # thereof.  E, g. expression '0,10-20' would be a valid expression,
    # matching 0, 11, 20, but not 2 or 21.
    #
    # If R_ESF is passed, it will be treated as path to file where exit status
    # of CODE is written.  This is recommended over consulting $?, since the
    # latter is not reliable; see below.
    #
    # If path R_OUT or R_ERR are provided, standard output and standard
    # error are saved to respective files.
    #
    # See COMMON ARGUMENTS section for common assert options.
    #
    # Exit status of the this function normally will, but IS NOT GUARRANTEED TO
    # correspond to the exit status of the CODE. For example, if the function
    # call is incomplete, the exit status will be 2.
    #
    local __jat__cmd=()
    local __jat__r_es
    local __jat__o_es=0
    local __jat__hint
    local __jat__beids=()
    local __jat__caseid
    local __jat__etype=TEST_ERROR
    local __jat__r_out
    local __jat__r_err
    local __jat__r_esf
    #
    # NOTE: names need to be qualified because they might interfere
    #       with the actual execution of the assert command.
    #
    while true; do case $1 in
        -b) __jat__beids+=("$2"); shift 2 || { __jat__usage "missing BEID"; return 2; } ;;
        -c) __jat__caseid="$2"; shift 2 || { __jat__usage "missing CASEID"; return 2; } ;;
        -h) __jat__hint=$2; shift 2 || { __jat__usage "missing HINT"; return 2; } ;;
        -e) __jat__r_err=$2; shift 2 || { __jat__usage "missing R_ERR"; return 2; } ;;
        -o) __jat__r_out=$2; shift 2 || { __jat__usage "missing R_OUT"; return 2; } ;;
        -s) __jat__r_esf=$2; shift 2 || { __jat__usage "missing R_ESF"; return 2; } ;;
        -S) __jat__o_es=$2; shift 2 || { __jat__usage "missing ES_EXPR"; return 2; } ;;
        --) shift; break ;;
        *) break ;;
    esac done
    __jat__cmd=("$@")
    test -n "${__jat__cmd[*]}" || { __jat__usage "no CMD?"; return 2; }
    test -n "$__jat__hint" || __jat__hint="${__jat__cmd[*]}"
    debug -v __jat__cmd __jat__o_es __jat__hint __jat__beids
    jat__log_info "CMD: ${__jat__cmd[*]}"
    case ${#__jat__r_out}:${#__jat__r_err} in
        0:0) "${__jat__cmd[@]}" ;;
        0:*) "${__jat__cmd[@]}" 2>"$__jat__r_err" ;;
        *:0) "${__jat__cmd[@]}" >"$__jat__r_out" ;;
        *:*) "${__jat__cmd[@]}" >"$__jat__r_out" 2>"$__jat__r_err" ;;
    esac; __jat__r_es=$?
    debug -v __jat__r_es __jat__r_esf
    if test -n "$__jat__r_esf"; then
        echo $__jat__r_es > "$__jat__r_esf" \
         || jat__log_error "error writing R_ESF file: $__jat__r_esf"
    fi
    if __jat__es_match "$__jat__o_es" "$__jat__r_es"; then
        __jat__etype=PASS
    else
        __jat__etype=FAIL
    fi
    __jat__assert $__jat__etype "$__jat__hint" "$__jat__caseid" "${__jat__beids[@]}" \
        -- "t.cmd=${__jat__cmd[*]}" "o.es_expr=$__jat__o_es" "r.es=$__jat__r_es"
    return "$__jat__r_es"
}

jat__cmp() {
    #
    # Assert that value $@ returns zero (or other)
    #
    # Usage:
    #
    #     jat__cmp [assert-options] RVAL OP OVAL
    #
    # Compare RVAL (result value) to OVAL (oracle value) and announce
    # assertion success (PASS) or assertion failure (FAIL).
    #
    # OP can be any of `eq`, `ne`, `lt`, `gt`, `le`, `ge` for numeric values,
    # `==` and `re` for string values.  In case of `re`, OVAL is expected to
    # be basic regular expression and is matched against whole string (ie.
    # anchors `^` and `$` are included automatically.
    #
    # Note that in most cases using jat__cmd() with `test` or `grep` commands
    # is all you need.
    #
    # See COMMON ARGUMENTS section for common assert options.
    #
    local RVal      # "result" value
    local Op        # operator
    local OVal      # "oracle" value
    local hint      # log hint
    local caseid    # case id
    local beids=()  # Behavior Evidence IDs
    local cmpes     # comparison exit status
    while true; do case $1 in
        -b) beids+=("$2"); shift 2 || { __jat__usage "missing BEID"; return 2; } ;;
        -c) caseid="$2"; shift 2 || { __jat__usage "missing CASEID"; return 2; } ;;
        -h) hint=$2; shift 2 || { __jat__usage "missing HINT"; return 2; } ;;
        *) break ;;
    esac done
    RVal=$1; Op=$2; OVal=$3
    test -n "$RVal" || { __jat__usage "no RVAL?"; return 2; }
    test -n "$Op" || { __jat__usage "no OP?"; return 2; }
    test -n "$OVal" || { __jat__usage "no OVAL?"; return 2; }
    test -n "$hint" || hint="$RVal $Op $OVal"
    debug -v RVal Op OVal hint beids
    __jat__cmp_match; cmpes=$?
    case $cmpes in
        0)
            __jat__assert PASS "$hint" "$caseid" "${beids[@]}" \
                -- "r.val=$RVal" "t.op=$Op" "o.val=$OVal"
            ;;
        1)
            __jat__assert FAIL "$hint" "$caseid" "${beids[@]}" \
                -- "r.val=$RVal" "t.op=$Op" "o.val=$OVal"
            ;;
        *)
            __jat__usage "bad syntax: $RVal $Op $OVal"
            return 2
            ;;
    esac
}

jat__eval() {
    #
    # Assert that command in code $1 returns zero (or other)
    #
    # Usage:
    #
    #     jat__eval [-s R_ESF] [-S ES_EXPR] [--] CODE
    #
    # Run CODE using eval builtin and if exit status is zero, announce assertion
    # success (PASS), otherwise announce assertion failure (FAIL).
    #
    # Exit status expectation can be changed from zero to ES_EXPR, which
    # must be in form of comma-separated list of integer values or ranges
    # thereof.  E, g. expression '0,10-20' would be a valid expression,
    # matching 0, 11, 20, but not 2 or 21.
    #
    # If R_ESF is passed, it will be treated as path to file where exit status
    # of CODE is written.  This is recommended over consulting $?, since the
    # latter is not reliable; see below.
    #
    # This is similar to jat__cmd(), except that code is checked against syntax
    # errors and user is given full control over redirections.
    #
    # See COMMON ARGUMENTS section for common assert options.
    #
    # Exit status of the this function normally will, but IS NOT GUARRANTEED TO
    # correspond to the exit status of the CODE. For example, if the function
    # call is incomplete, the exit status will be 2.  If there is syntax error
    # in CODE, the exit status will be 3.
    #
    local __jat__caseid
    local __jat__code=""
    local __jat__r_es
    local __jat__r_esf
    local __jat__o_es=0
    local __jat__hint
    local __jat__beids=()
    local __jat__etype=TEST_ERROR
    #
    # NOTE: names need to be qualified because they might interfere
    #       with the actual execution of the assert command.
    #
    while true; do case $1 in
        -b) __jat__beids+=("$2"); shift 2 || { __jat__usage "missing BEID"; return 2; } ;;
        -c) __jat__caseid="$2"; shift 2 || { __jat__usage "missing CASEID"; return 2; } ;;
        -h) __jat__hint=$2; shift 2 || { __jat__usage "missing HINT"; return 2; } ;;
        -s) __jat__r_esf=$2; shift 2 || { __jat__usage "missing R_ESF"; return 2; } ;;
        -S) __jat__o_es=$2; shift 2 || { __jat__usage "missing ES_EXPR"; return 2; } ;;
        --) shift; break ;;
        *) break ;;
    esac done
    __jat__code=$1
    test -n "$__jat__code" || { __jat__usage "no CODE?"; return 2; }
    test -n "$2" &&  { __jat__usage "extra args!: $*"; return 2; }
    test -n "$__jat__hint" || __jat__hint="$__jat__code"
    debug -v __jat__code __jat__o_es __jat__hint __jat__beids
    bash -n <<<"$__jat__code" || {
        jat__log_error "syntax error in test code: $__jat__code"
        return 3
    }
    jat__log_info "CODE: $__jat__code"
    eval "$__jat__code"; __jat__r_es=$?
    if test -n "$__jat__r_esf"; then
        echo $__jat__r_es > "$__jat__r_esf" \
         || jat__log_error "error writing R_ESF file: $__jat__r_esf"
    fi
    debug -v __jat__r_es
    if __jat__es_match "$__jat__o_es" "$__jat__r_es"; then
        __jat__etype=PASS
    else
        __jat__etype=FAIL
    fi
    __jat__assert $__jat__etype "$__jat__hint" "$__jat__caseid" "${__jat__beids[@]}" \
        -- "t.code=$__jat__code" "o.es_expr=$__jat__o_es" "r.es=$__jat__r_es"
    return "$__jat__r_es"
}

jat__fail() {
    #
    # Assert test failure
    #
    # Usage:
    #
    #     jat__fail [assert-options]
    #
    # Simply log event that an assert has failed.  Use other assert functions
    # if you can, since they probably provide more useful information to log
    # reader.
    #
    # See COMMON ARGUMENTS section for common assert options.
    #
    local hint      # log hint
    local caseid    # case ID
    local beids=()  # Behavior Evidence IDs
    while true; do case $1 in
        -b) beids+=("$2"); shift 2 || { __jat__usage "missing BEID"; return 2; } ;;
        -c) caseid="$2"; shift 2 || { __jat__usage "missing CASEID"; return 2; } ;;
        -h) hint=$2; shift 2 || { __jat__usage "missing HINT"; return 2; } ;;
        *) break ;;
    esac done
    test -n "$1" && { __jat__usage "extra arguments: $*"; return 2; }
    debug -v hint beids
    __jat__assert FAIL "$hint" "$caseid" "${beids[@]}"
}

jat__filebackup() {
    #
    # Back up file $1
    #
    # Usage:
    #
    #     jat__filebackup [-n NS] [-c] [--] PATH
    #
    # Back up PATH aside to be able to restore it later using
    # jat__filerestore().
    #
    # Provide `-c` switch to ensure that path is removed before restoring.
    # If NS is given, it must be "simple word" (see STRINGS section).
    #
    local path
    local abspath
    local ns=_jat_anon_backupns_
    local store
    local dest
    local clean=false
    local pdig
    local nshint
    while true; do case $1 in
        --) shift; break ;;
        -c|--clean)
            clean=true
            shift ;;
        -n|--namespace)
            ns=$2; nshint="(NS=$ns) "
            shift 2 || { __jat__usage "no NS?"; return 2; }
            ;;
        -*) __jat__usage "unknown argument: $1"; return 2 ;;
        *) break ;;
    esac done
    path=$1
    test -n "$path" || { __jat__usage "no PATH?"; return 2; }
    isa__name "$ns" || { __jat__usage "NS must be simple word"; return 2; }
    abspath=$(readlink -e "$path") || {
        jat__log_error "no such file: $1"
        return 3
    }
    pdig=$(md5sum <<<"$abspath" | cut -d' ' -f1)
    __jat__sd_keya "backup/$ns/rainbow" "$pdig $abspath"
    $clean && __jat__sd_keya "backup/$ns/clean" "$abspath"
    store=$(__jat__sd_path "backup/$ns/store")
    mkdir -p "$store"
    dest="$store/$pdig"
    test -e "$store/$pdig" && {
        jat__log_error "already backed up, giving up: $nshint$path"
        return 2
    }
    cp -ar "$abspath" "$store/$pdig" || {
        jat__log_error "failed to create backup: $abspath"
        return 3
    }
    jat__log_info "backed up: $nshint$path"
    debug -c tree "$(__jat__sd_path backup)"
}

jat__filerestore() {
    #
    # Restore paths stored by jat__filebackup()
    #
    # Usage:
    #
    #     jat__filerestore [-n NS]
    #
    # Restore all paths backed up using jat__filebackup().  Paths
    # are restored in opposite order than backed up.
    #
    local abspath
    local ns=_jat_anon_backupns_
    local store
    local pdig
    local nshint
    local rainbow
    local cleanlog
    while true; do case $1 in
        -n|--namespace)
            ns=$2; nshint="(NS=$ns) "
            shift 2 || { __jat__usage "no NS?"; return 2; }
            ;;
        "") break ;;
        *) __jat__usage "unknown argument: $1"; return 2 ;;
    esac done
    isa__name "$ns" || { __jat__usage "NS must be simple word"; return 2; }
    test -d "$__JAT__SDIR/internal/backup/$ns" || {
        jat__log_error "unknown backup namespace: $ns"
        return 3
    }
    rainbow=$(__jat__sd_path "backup/$ns/rainbow")
    cleanlog=$(__jat__sd_path "backup/$ns/clean")
    store=$(__jat__sd_path "backup/$ns/store")
    while read -r pdig abspath; do
        debug -v pdig abspath
        grep -qxF "$abspath" "$cleanlog" 2>/dev/null && {
            rm -rf "$abspath" || {
                jat__log_error "failed to pre-clean original path: $abspath"
                return 3
            }
        }
        debug -c ls -l "$store"
        cp -Tar "$store/$pdig" "$abspath" || {
            jat__log_error "failed to restore backup: $nshint$abspath"
            return 3
        }
        jat__log_info "restored: $nshint$abspath"
        :
    done <"$rainbow"
}

jat__sfinish() {
    #
    # Finalize session
    #
    # Log event to announce that log is finalized and remove test
    # session.
    #
    # This is necessary because in order to support persistent multi
    # PID tests (ie, re-booting within test), jat__sinit() will reload
    # leftover session and whole log will be merged.
    #
    local fileas    # session id for filing in 'finished' folder
    test -d "$JAT__DIR/session" || {
        __jat__show_error "no active session: no $JAT__DIR/session"
        return 2
    }
    __jat__show_sfinish
    __jat__log_event SINFO "finishing session"
    __jat__writelog <<<"finalized: true"
    __jat__writelog <<<"end: $(__jat__newstamp)"
    fileas=$(__jat__sd_keyr fileas)
    mkdir -p "$JAT__DIR/finished"
    mv "$JAT__DIR/session" "$JAT__DIR/finished/$fileas"
    rm -f "$JAT__DIR/last"
    ln -s "finished/$fileas" "$JAT__DIR/last"
}

jat__log_error() {
    #
    # Log internal error unrelated to SUT
    #
    local msg=$1
    echo "error" >> "$(__jat__sd_path "llog")"
    echo "error" >> "$(__jat__sd_path "P.llog")"
    __jat__log_event TEST_ERROR "$msg"
    __jat__show_terror "$msg"
}

jat__log_info() {
    #
    # Log internal info unrelated to SUT
    #
    local msg=$1
    echo "info" >> "$(__jat__sd_path "llog")"
    echo "info" >> "$(__jat__sd_path "P.llog")"
    __jat__log_event SINFO "$msg"
    __jat__show_tinfo "$msg"
}

jat__log_warning() {
    #
    # Log internal error unrelated to SUT
    #
    local msg=$1
    echo "warning" >> "$(__jat__sd_path "llog")"
    echo "warning" >> "$(__jat__sd_path "P.llog")"
    __jat__log_event TEST_WARNING "$msg"
    __jat__show_twarning "$msg"
}

jat__pass() {
    #
    # Assert test pass
    #
    # Usage:
    #
    #     jat__pass [assert-options]
    #
    # Simply log event that an assert has passed.  Use other assert functions
    # if you can, since they probably provide more useful information to log
    # reader.
    #
    # See COMMON ARGUMENTS section for common assert options.
    #
    local hint      # log hint
    local beids=()  # Behavior Evidence IDs
    local caseid    # case ID
    while true; do case $1 in
        -b) beids+=("$2"); shift 2 || { __jat__usage "missing BEID"; return 2; } ;;
        -c) caseid="$2"; shift 2 || { __jat__usage "missing CASEID"; return 2; } ;;
        -h) hint=$2; shift 2 || { __jat__usage "missing HINT"; return 2; } ;;
        *) break ;;
    esac done
    test -n "$1" && { __jat__usage "extra arguments: $*"; return 2; }
    debug -v hint beids
    __jat__assert PASS "$hint" "$caseid" "${beids[@]}"
}

jat__promise_asserts() {
    #
    # Promise number of asserts will be $1
    #
    local num=$1
    test -n "$num" || {
        __jat__usage "no NUM?"
        return 2
    }
    __jat__log_event PROMISE "assert number: $num" "" \
        -- "num=$num"
}

jat__sinit() {
    #
    # Initialize session
    #
    # Load active session if found; otherwise initialize new one.
    #
    local reload=false
    mkdir -p "$JAT__DIR" \
     || die "could not initialize JAT__DIR: $JAT__DIR"
    __JAT__SDIR=$JAT__DIR/session
    test -d "$__JAT__SDIR" && reload=true
    mkdir -p "$__JAT__SDIR"
    __jat__sd_keyw fileas "session-$(date +%s-%N)"
    export __JAT__SDIR
    export JAT__YLOG
    debug -v reload __JAT__SDIR
    if $reload; then
        __jat__log_event SINFO "reloaded session" "" \
            -- \
            "JAT__LOG_FMT=$__JAT__LOG_FMT" \
            "JAT__VERSION=$__JAT__SELF_VERSION"
        __jat__show_sinitr
    else
        debug -v __JAT__SDIR JAT__YLOG
        {
            echo "---"
            echo "format: $__JAT__LOG_FMT"
            echo "jat_version: $__JAT__SELF_VERSION"
            echo "test:"
            echo "    id: $JAT__TEST_ID"
            echo "    version: $JAT__TEST_VERSION"
            echo "start: $(__jat__newstamp)"
            echo "events:"
        } | __jat__writelog
        __jat__pdummy
        __jat__log_event SINFO "started new session"
        __jat__show_sinitn
    fi
}

jat__stat() {
    #
    # Print session statistic $1
    #
    # Usage:
    #    jat__stat sasrtc      # session assert count
    #    jat__stat spassc      # session pass count
    #    jat__stat sfailc      # session fail count
    #    jat__stat pasrtc      # phase assert count
    #    jat__stat ppassc      # phase pass count
    #    jat__stat pfailc      # phase fail count
    #    jat__stat swarc       # session warning count
    #    jat__stat pwarc       # phase warning count
    #    jat__stat serrc       # session error count
    #    jat__stat perrc       # phase error count
    #
    # Print statistics about session state.
    #
    local which=$1
    case $which in
        swarc)  grep -cxF warning "$(__jat__sd_path "llog")" ;;
        pwarc)  grep -cxF warning "$(__jat__sd_path "P.llog")" ;;
        serrc)  grep -cxF error "$(__jat__sd_path "llog")" ;;
        perrc)  grep -cxF error "$(__jat__sd_path "P.llog")" ;;
        sfailc) grep -cxF FAIL "$(__jat__sd_path "vlog")" ;;
        pfailc) grep -cxF FAIL "$(__jat__sd_path "P.vlog")" ;;
        ppassc) grep -cxF PASS "$(__jat__sd_path "P.vlog")" ;;
        spassc) grep -cxF PASS "$(__jat__sd_path "vlog")" ;;
        pasrtc) grep -cx 'PASS\|FAIL' "$(__jat__sd_path "P.vlog")" ;;
        sasrtc) grep -cx 'PASS\|FAIL' "$(__jat__sd_path "vlog")" ;;
        *) __jat__usage "invalid statistic field: $which"
           return 2 ;;
    esac
}

jat__pend() {
    #
    # End active phase
    #
    local oldpdir
    oldpdir=$(__jat__sd_keyR P.pdir)
    test -n "$oldpdir" && {
        jat__log_info "changing back from phase dir: $oldpdir"
        popd >/dev/null
    }
    __jat__show_pend
    __jat__pdummy
    __jat__log_event SINFO
}

jat__pstartd() {
    #
    # Start diagnostic phase named $1
    #
    # See COMMON ARGUMENTS section of this manual.
    #
    __jat__pstart -t diag "$@"
}

jat__pstartc() {
    #
    # Start cleanup phase named $1
    #
    # See COMMON ARGUMENTS section of this manual.
    #
    __jat__pstart -t cleanup "$@"
}

jat__pstarts() {
    #
    # Start setup phase named $1
    #
    # See COMMON ARGUMENTS section of this manual.
    #
    __jat__pstart -t setup "$@"
}

jat__pstartt() {
    #
    # Start test phase named $1
    #
    # See COMMON ARGUMENTS section of this manual.
    #
    __jat__pstart -t test "$@"
}

jat__submit() {
    #
    # Submit file $1 as part of test result
    #
    # Usage:
    #
    #     jat__submit PATH [ALTNAME]
    #
    # Last element of PATH is used as result name, unless alternative
    # name ALTNAME is given, in which case it's used instead.
    #
    local path=$1
    local altname=$2
    local dest=$__JAT__SDIR/results
    local nhint
    test -n "$path" || {
        __jat__usage "no SRC?"
        return 2
    }
    test -n "$altname" && {
        dest="$dest/$altname"
        nhint=" as $altname"
    }
    mkdir -p "$(dirname "$dest")" || {
        jat__log_error "cannot write to result storage: $dest"
        return 3
    }
    jat__log_info "submitting result: $path$nhint"
    cp -ar "$path" "$dest"
}

__jat__assert() {
    #
    # Make assert event
    #
    # Use this function to create own asserts
    #
    case $1 in
        PASS)   __jat__show_pass "$2" ;;
        FAIL)   __jat__show_fail "$2" ;;
    esac
    __jat__log_event "$@"
}

__jat__bumpid() {
    #
    # Create and/or bump ID named $1
    #
    # Print next ID from series named $1.  Series starts
    # with 1, so on firts call, value of ID is 1, then 2.
    # etc.
    #
    # Isession is not initialized, ID value will be 0 and
    # return status will be 3.
    #
    local name=$1   # name of id
    local cache     # ordinal cache
    local ord       # ordinal
    if test -n "$__JAT__SDIR"; then
        cache=$(__jat__sd_path "series/$name")
    else
        echo 0; return 3
    fi
    if test -f "$cache"; then
        ord=$(<"$cache")
        ((ord++))
    else
        ord=1
    fi
    echo $ord >"$cache"
    echo "$name-$ord"
}

__jat__cmp_match() {
    #
    # True if $RVal matches $OVal by $Op
    #
    case $Op in
        eq|ne|lt|gt|le|ge) test "$RVal" -"$Op" "$OVal" ;;
        ==)                test "$RVal" == "$OVal" ;;
        re)                grep -qx "$OVal" <<< "$RVal" ;;
        *)  return 2 ;;
    esac
}

__jat__es_match() {
    #
    # True if exit status $1 matches expression $EsExpr
    #
    local expr=$1
    local es=$2
    local part
    for part in ${expr//,/ }; do
        test -n "$part" || continue
        #FIXME: a rather funny implementation (works, though...)
        eval "echo {${part/-/..}}" | grep -qwF "$es" && return 0
    done
    return 1
}

__jat__log_event() {
    #
    # Pass YAML log event to __jat__writelog()
    #
    # Usage:
    #
    #     __jat__log_event ETYPE HINT CASEID [BEID].. -- [KEY=VALUE]..
    #
    # ETYPE can be FAIL, PASS, TEST_ERROR or SINFO (the latter two
    # are for events unrelated to SUT, like internal errors or
    # phase start/end events).
    #
    # HINT and BEIDs are explained in COMMON ARGUMENTS section of this
    # manual.
    #
    # You can provide any amount of KEY=VALUE pairs, meaning of which
    # is specific to every assert function.  (The assert function name
    # is auto-detected and logged so that you can infer KEY meanings
    # later.)  Each KEY must be simple word, except that prefixes of
    # `t.`, `r.`, and `o.` are allowed to signify that the value logged
    # is relevant to test method, result or oracle, respectively.
    local etype=$1; shift
    local hint=$1;    shift
    local acaseid=$1; shift
    local arg
    local beids=()
    local pairs=()
    local real_beids=()
    local caseid="$JAT__TEST_ID"
    local pcaseid
    local reading=beids
    local pair
    local origin=${FUNCNAME[1]}
    pcaseid=$(__jat__sd_keyR P.caseid)
    test -n "$pcaseid" && caseid+=":$pcaseid"
    test -n "$acaseid" && caseid+=":$acaseid"
    case $etype in
        PASS|FAIL|SINFO|TEST_ERROR|TEST_WARNING|PROMISE) : ;;
        *)  __jat__show_error "bad ETYPE, changing to TEST_ERROR: $etype"
            etype=TEST_ERROR ;;
    esac
    case $etype:$origin in
        PASS:__jat__assert)        : ;;
        FAIL:__jat__assert)        : ;;
        TEST_ERROR:__jat__usage)   : ;;
        SINFO:jat__sinit)          : ;;
        SINFO:jat__sfinish)        : ;;
        SINFO:__jat__pstart)       : ;;
        SINFO:jat__pend)           : ;;
        SINFO:jat__log_info)       : ;;
        TEST_ERROR:jat__log_error) : ;;
        TEST_WARNING:jat__log_warning) : ;;
        *)  __jat__show_error "illegal call of __jat__log_event: $etype from $origin"
            etype=TEST_ERROR ;;
    esac
    for arg in "$@"; do
        case $reading:$arg in
            *:)
                shift
                ;;
            beids:--)
                shift
                reading=pairs
                ;;
            beids:*)
                __jat__valid_beid "$arg" || {
                    beids=(); pairs=(); etype=API_BUG
                    hint="bad BEID syntax (must be simple id): '$arg'"
                    __jat__show_error "$hint"
                    break
                }
                beids+=("$arg")
                shift
                ;;
            pairs:*)
                __jat__valid_pair "$arg" || {
                    beids=(); pairs=(); etype=API_BUG
                    hint="bad K=V syntax: '$arg'"
                    __jat__show_error "$hint"
                    break
                }
                pairs+=("$arg")
                shift
                ;;
        esac
    done
    for beid in "${beids[@]}"; do
        case $beid in
            "")     : ;;
            *.*)    real_beids+=("$beid") ;;
            *)      real_beids+=("$JAT__BEID_NS.$beid") ;;
        esac
    done
    echo "$etype" >> "$(__jat__sd_path "vlog")"
    echo "$etype" >> "$(__jat__sd_path "P.vlog")"
    {
        # NOTE: some scalars are printed directly for performance
        #       reasons (these will never be null nor will they
        #       contain YAML special chars)
        #
        echo "-"
        echo "    origin: $origin"
        echo "    etype: $etype"
        echo "    stamp: $(__jat__newstamp)"
        echo "    caseid: $caseid"
        __jat__yamls hint "$hint"
        __jat__yamla beids "${real_beids[@]}"
        __jat__yamld data "${pairs[@]}"
        echo "    phase:"
        echo "        id: $(__jat__sd_keyr phase)"
        echo "        name: $(__jat__sd_keyr P.name)"
        echo "        type: $(__jat__sd_keyr P.type)"
    } | sed 's/^/    /' | __jat__writelog
}

__jat__newstamp() {
    #
    # Create new timestamp
    #
    case $__JAT__DETERMINISTIC in
        true)   __jat__bumpid time ;;
        false)  date +%s ;;
        *) die "bad value of __JAT__DETERMINISTIC: $__JAT__DETERMINISTIC" ;;
    esac
}

__jat__pdummy() {
    #
    # Create dummy phase
    #
    __jat__sd_keyw phase "dummy"
    __jat__sd_keyw P.name "_jat_dummy_phase_"
    __jat__sd_keyw P.type "none"
}

__jat__pstart() {
    #
    # Start phase of type $1 and name $2
    #
    local type      # phase name
    local name      # ^^ name
    local pdir      # ^^ directory
    local pcaseid   # ^^ case id, if assigned
    local oldphase  # current phase id
    while true; do case $1 in
        -t) type="$2"; shift 2 || return 2 ;;
        -c) pcaseid="$2"; shift 2 || return 2 ;;
        -C) pdir="$2"; shift 2 || return 2 ;;
        *)  break ;;
    esac done
    name="${1:-_jat_anon_phase_}"
    oldphase=$(__jat__sd_keyr phase)
    test "$oldphase" == dummy || {
        jat__log_error "old phase not ended; ending automatically: $oldphase"
        jat__pend
    }
    debug -v type name pdir
    __jat__sd_keyw phase "$(__jat__bumpid phasid)"
    __jat__sd_keyw P.type "$type"
    __jat__sd_keyw P.name "$name"
    __jat__sd_keyw P.caseid "$pcaseid"
    __jat__show_pstart "$name"
    __jat__log_event SINFO
    test -n "$pdir" && {
        __jat__sd_keyw P.pdir "$pdir"
        __jat__sd_keyw P.PWD "$PWD"
        jat__log_info "changing directory for phase: $pdir"
        pushd "$pdir" >/dev/null || {
            jat__log_error "failed to change to phase directory: $pdir"
            return 3
        }
    }
}

__jat__sd_keya() {
    #
    # Append line $2 to session key $1
    #
    local key=$1
    local value=$2
    local path
    path=$(__jat__sd_path "$key")
    echo "$value" >> "$path" || {
        __jat__show_error "error appending session data: key '$key' to '$path'"
        return 3
    }
}

__jat__sd_keyR() {
    #
    # Read session key $1 if it exists, return 1 otherwise
    #
    local key=$1
    local path
    path=$(__jat__sd_path "$key") || return 1
    cat "$path" || {
        __jat__show_error "error reading session data: key '$key' from '$path'"
        return 3
    }
}

__jat__sd_keyr() {
    #
    # Read session key $1
    #
    local key=$1
    local path
    path=$(__jat__sd_path "$key")
    cat "$path" || {
        __jat__show_error "error reading session data: key '$key' from '$path'"
        return 3
    }
}

__jat__sd_keyw() {
    #
    # Write $2 to session key $1
    #
    local key=$1
    local value=$2
    local path
    path=$(__jat__sd_path "$key")
    echo "$value" > "$path" || {
        __jat__show_error "error writing session data: key '$key' to '$path'"
        return 3
    }
}

__jat__sd_path() {
    #
    # Dereference path to session key $1; true if exists
    #
    # Key starting with 'P.' will be phase-specific.
    #
    local key=$1
    local path="$__JAT__SDIR/internal/"
    case $key in
        "")     __jat__show_error "no KEY?"; return 2 ;;
        P.*)    path+="phase-$(__jat__sd_keyr phase)/$key" ;;
        *)      path+="$key" ;;
    esac
    mkdir -p "${path%/*}" 2>/dev/null || {
        __jat__show_error "could not create key: $path"
        return 2
    }
    echo "$path"
    test -e "$path"
}

__jat__show() {
    #
    # Show to user and also keep in ansi log
    #
    local msg
    for msg in "$@"; do
        echo -e "$msg" >> "$__JAT__SDIR/log.ansi"
        echo -e "$msg" >&2
    done
}

__jat__show_fail() {
    #
    # Show assert fail message $1 to stderr
    #
    __jat__show \
        "  $__JAT__SWORD_SUT.$__JAT__SWORD_FAIL: $1"
}

__jat__show_pass() {
    #
    # Show assert fail message $1 to stderr
    #
    __jat__show \
        "  $__JAT__SWORD_SUT.$__JAT__SWORD_PASS: $1"
}

__jat__show_pend() {
    #
    # Show phase end
    #
    local pverd     # phase verdict text
    local pname     # ^^ name
    local pnhint    # ^^ ^^ display
    pname=$(__jat__sd_keyr P.name)
    test "$pname" == "_jat_anon_phase_" || pnhint=" '$pname'"
    case "$(jat__stat pfailc)" in
        0)  pverd="$__JAT__SWORD_PASS" ;;
        *)  pverd="$__JAT__SWORD_FAIL" ;;
    esac
    __jat__show \
        "$__JAT__SWORD_PHASE.$__JAT__SWORD_END.$pverd$pnhint" \
        ""
}

__jat__show_pstart() {
    #
    # Show phase start
    #
    local pname=$1  # phase name
    local pnhint    # ^^ ^^ display
    test "$pname" == "_jat_anon_phase_" || pnhint=" '$pname'"
    __jat__show \
        "$__JAT__SWORD_PHASE.$__JAT__SWORD_START$pnhint"
}

__jat__show_sfinish() {
    #
    # Show message about session $1 finalization to stderr
    #
    local sverd         # session verdict text
    case "$(jat__stat sfailc)" in
        0)  sverd="$__JAT__SWORD_PASS" ;;
        *)  sverd="$__JAT__SWORD_FAIL" ;;
    esac
    __jat__show \
        "$__JAT__SWORD_SESSION.$__JAT__SWORD_FINALIZE.$sverd"
}

__jat__show_sinitn() {
    #
    # Show message about session initialization to stderr
    #
    __jat__show \
        "$__JAT__SWORD_TEST.$__JAT__SWORD_TINFO: id: $JAT__TEST_ID" \
        "$__JAT__SWORD_TEST.$__JAT__SWORD_TINFO: version: $JAT__TEST_VERSION" \
        "" \
        "$__JAT__SWORD_SESSION.$__JAT__SWORD_START" \
        ""
}

__jat__show_sinitr() {
    #
    # Show message about session reload to stderr
    #
    __jat__show \
        "$__JAT__SWORD_TEST.$__JAT__SWORD_TINFO: id: $JAT__TEST_ID" \
        "$__JAT__SWORD_TEST.$__JAT__SWORD_TINFO: version: $JAT__TEST_VERSION" \
        "" \
        "$__JAT__SWORD_SESSION.$__JAT__SWORD_RELOAD" \
        ""
}

__jat__show_tinfo() {
    #
    # Show test info
    #
    local sp=""
    test "$(__jat__sd_keyr phase)" == dummy || sp="  "
    __jat__show \
        "$sp$__JAT__SWORD_TEST.$__JAT__SWORD_TINFO: $1"
}

__jat__show_terror() {
    #
    # Show test error
    #
    local sp=""
    test "$(__jat__sd_keyr phase)" == dummy || sp="  "
    __jat__show \
        "$sp$__JAT__SWORD_TEST.$__JAT__SWORD_TERROR: $1"
}

__jat__show_twarning() {
    #
    # Show test warning
    #
    local sp=""
    test "$(__jat__sd_keyr phase)" == dummy || sp="  "
    __jat__show \
        "$sp$__JAT__SWORD_TEST.$__JAT__SWORD_TWARNING: $1"
}

__jat__show_error() {
    #
    # Emit general jat warning (not related to SUT)
    #
    warn "jat.ERROR" "$1"
}

__jat__usage() {
    #
    # Print usage error $1 and hint according to FUNCNAME
    #
    local msg=$1
    local parent=${FUNCNAME[1]}
    local patt
    local patts=()
    __jat__show_error "bad usage: $msg"
    case $parent in
        jat__cmd)      patts=("[assert-options] [-o R_OUT] [-e R_ERR] [-s R_ESF] [-S ES_EXPR] [--] CMD [ARG]..") ;;
        jat__eval)     patts=("[assert-options] [-s R_ESF] [-S ES_EXPR] [--] CODE") ;;
        jat__cmp)      patts=("[assert-options] RVAL OP OVAL") ;;
        jat__fail)     patts=("[assert-options]") ;;
        jat__pass)     patts=("[assert-options]") ;;
        jat__submit)   patts=("SRC [ALTNAME]") ;;
        jat__stat)     patts=(spassc sfailc ppassc pfailc) ;;
    esac
    for patt in "${patts[@]}"; do
        __jat__show_error "usage: $parent $patt"
    done
    __jat__log_event TEST_ERROR "bad usage: $parent()" "" \
        -- "PATTERNS=${patts[*]}"
}

__jat__writelog() {
    #
    # Write logged output (copy if needed)
    #
    case $JAT__YLOG in
        "") cat >> "$__JAT__SDIR/log.yaml" ;;
        -)  tee -a "$__JAT__SDIR/log.yaml" ;;
        *)  tee -a "$__JAT__SDIR/log.yaml" >> "$JAT__YLOG" ;;
    esac
}

__jat__valid_beid() {
    #
    # True if $1 is a valid BEID
    #
    local tainted=$1
    grep -qx '[[:alpha:]_][[:alnum:]_.]*' <<<"$tainted"
}

__jat__valid_pair() {
    #
    # True if $1 is a valid BEID
    #
    local tainted=$1
    grep -qx '\([tor][.]\)\?[[:alpha:]_][[:alnum:]_]*=.*' <<<"$tainted"
}

__jat__yamls() {
    #
    # Print a scalar field named $1 with value $2
    #
    local name=$1
    local value=$2
    case $value in
        "") echo "    $name: ~" ;;
        *)  echo "    $name: |-"
            echo "        $value" ;;
    esac
}

__jat__yamla() {
    #
    # Print an array field named $1 with array of values $2..
    #
    local name=$1; shift
    local value
    test $# -eq 0 && echo "    $name: []" && return 0
    echo "    $name:"
    for value in "$@"; do
        case $value in
            "") echo "        - ~" ;;
            *)  echo "        - |"
                echo "            $value" ;;
        esac
    done
}

__jat__yamld() {
    #
    # Print a dict field named $1 and composed of KEY=VALUE pairs $2..
    #
    local name=$1; shift
    local pair
    local key
    local value
    test $# -eq 0 && echo "    $name: {}" && return 0
    echo "    $name:"
    for pair in "$@"; do
        key=${pair%%=*}; value=${pair#$key=}
        case $value in
            "") echo "        $key: ~" ;;
            *)  echo "        $key: |"
                echo "            $value" ;;
        esac
    done
}

#shellfu module-version=__MKIT_PROJ_VERSION__