1# 2# Automated Testing Framework (atf) 3# 4# Copyright (c) 2007 The NetBSD Foundation, Inc. 5# All rights reserved. 6# 7# Redistribution and use in source and binary forms, with or without 8# modification, are permitted provided that the following conditions 9# are met: 10# 1. Redistributions of source code must retain the above copyright 11# notice, this list of conditions and the following disclaimer. 12# 2. Redistributions in binary form must reproduce the above copyright 13# notice, this list of conditions and the following disclaimer in the 14# documentation and/or other materials provided with the distribution. 15# 16# THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND 17# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 18# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 19# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20# IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY 21# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 23# GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 25# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 26# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 27# IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28# 29 30set -e 31 32# ------------------------------------------------------------------------ 33# GLOBAL VARIABLES 34# ------------------------------------------------------------------------ 35 36# Values for the expect property. 37Expect=pass 38Expect_Reason= 39 40# A boolean variable that indicates whether we are parsing a test case's 41# head or not. 42Parsing_Head=false 43 44# The program name. 45Prog_Name=${0##*/} 46 47# The file to which the test case will print its result. 48Results_File= 49 50# The test program's source directory: i.e. where its auxiliary data files 51# and helper utilities can be found. Can be overriden through the '-s' flag. 52Source_Dir="$(dirname ${0})" 53 54# Indicates the test case we are currently processing. 55Test_Case= 56 57# List of meta-data variables for the current test case. 58Test_Case_Vars= 59 60# The list of all test cases provided by the test program. 61Test_Cases= 62 63# ------------------------------------------------------------------------ 64# PUBLIC INTERFACE 65# ------------------------------------------------------------------------ 66 67# 68# atf_add_test_case tc-name 69# 70# Adds the given test case to the list of test cases that form the test 71# program. The name provided here must be accompanied by two functions 72# named after it: <tc-name>_head and <tc-name>_body, and optionally by 73# a <tc-name>_cleanup function. 74# 75atf_add_test_case() 76{ 77 Test_Cases="${Test_Cases} ${1}" 78} 79 80# 81# atf_check cmd expcode expout experr 82# 83# Executes atf-check with given arguments and automatically calls 84# atf_fail in case of failure. 85# 86atf_check() 87{ 88 ${Atf_Check} "${@}" || \ 89 atf_fail "atf-check failed; see the output of the test for details" 90} 91 92# 93# atf_check_equal expr1 expr2 94# 95# Checks that expr1's value matches expr2's and, if not, raises an 96# error. Ideally expr1 and expr2 should be provided quoted (not 97# expanded) so that the error message is helpful; otherwise it will 98# only show the values, not the expressions themselves. 99# 100atf_check_equal() 101{ 102 eval _val1=\"${1}\" 103 eval _val2=\"${2}\" 104 test "${_val1}" = "${_val2}" || \ 105 atf_fail "${1} != ${2} (${_val1} != ${_val2})" 106} 107 108# 109# atf_config_get varname [defvalue] 110# 111# Prints the value of a configuration variable. If it is not 112# defined, prints the given default value. 113# 114atf_config_get() 115{ 116 _varname="__tc_config_var_$(_atf_normalize ${1})" 117 if [ ${#} -eq 1 ]; then 118 eval _value=\"\${${_varname}-__unset__}\" 119 [ "${_value}" = __unset__ ] && \ 120 _atf_error 1 "Could not find configuration variable \`${1}'" 121 echo ${_value} 122 elif [ ${#} -eq 2 ]; then 123 eval echo \${${_varname}-${2}} 124 else 125 _atf_error 1 "Incorrect number of parameters for atf_config_get" 126 fi 127} 128 129# 130# atf_config_has varname 131# 132# Returns a boolean indicating if the given configuration variable is 133# defined or not. 134# 135atf_config_has() 136{ 137 _varname="__tc_config_var_$(_atf_normalize ${1})" 138 eval _value=\"\${${_varname}-__unset__}\" 139 [ "${_value}" != __unset__ ] 140} 141 142# 143# atf_expect_death reason 144# 145# Sets the expectations to 'death'. 146# 147atf_expect_death() 148{ 149 _atf_validate_expect 150 151 Expect=death 152 _atf_create_resfile "expected_death: ${*}" 153} 154 155# 156# atf_expect_timeout reason 157# 158# Sets the expectations to 'timeout'. 159# 160atf_expect_timeout() 161{ 162 _atf_validate_expect 163 164 Expect=timeout 165 _atf_create_resfile "expected_timeout: ${*}" 166} 167 168# 169# atf_expect_exit exitcode reason 170# 171# Sets the expectations to 'exit'. 172# 173atf_expect_exit() 174{ 175 _exitcode="${1}"; shift 176 177 _atf_validate_expect 178 179 Expect=exit 180 if [ "${_exitcode}" = "-1" ]; then 181 _atf_create_resfile "expected_exit: ${*}" 182 else 183 _atf_create_resfile "expected_exit(${_exitcode}): ${*}" 184 fi 185} 186 187# 188# atf_expect_fail reason 189# 190# Sets the expectations to 'fail'. 191# 192atf_expect_fail() 193{ 194 _atf_validate_expect 195 196 Expect=fail 197 Expect_Reason="${*}" 198} 199 200# 201# atf_expect_pass 202# 203# Sets the expectations to 'pass'. 204# 205atf_expect_pass() 206{ 207 _atf_validate_expect 208 209 Expect=pass 210 Expect_Reason= 211} 212 213# 214# atf_expect_signal signo reason 215# 216# Sets the expectations to 'signal'. 217# 218atf_expect_signal() 219{ 220 _signo="${1}"; shift 221 222 _atf_validate_expect 223 224 Expect=signal 225 if [ "${_signo}" = "-1" ]; then 226 _atf_create_resfile "expected_signal: ${*}" 227 else 228 _atf_create_resfile "expected_signal(${_signo}): ${*}" 229 fi 230} 231 232# 233# atf_expected_failure msg1 [.. msgN] 234# 235# Makes the test case report an expected failure with the given error 236# message. Multiple words can be provided, which are concatenated with 237# a single blank space. 238# 239atf_expected_failure() 240{ 241 _atf_create_resfile "expected_failure: ${Expect_Reason}: ${*}" 242 exit 0 243} 244 245# 246# atf_fail msg1 [.. msgN] 247# 248# Makes the test case fail with the given error message. Multiple 249# words can be provided, in which case they are joined by a single 250# blank space. 251# 252atf_fail() 253{ 254 case "${Expect}" in 255 fail) 256 atf_expected_failure "${@}" 257 ;; 258 pass) 259 _atf_create_resfile "failed: ${*}" 260 exit 1 261 ;; 262 *) 263 _atf_error 128 "Unreachable" 264 ;; 265 esac 266} 267 268# 269# atf_get varname 270# 271# Prints the value of a test case-specific variable. Given that one 272# should not get the value of non-existent variables, it is fine to 273# always use this function as 'val=$(atf_get var)'. 274# 275atf_get() 276{ 277 eval echo \${__tc_var_${Test_Case}_$(_atf_normalize ${1})} 278} 279 280# 281# atf_get_srcdir 282# 283# Prints the value of the test case's source directory. 284# 285atf_get_srcdir() 286{ 287 echo ${Source_Dir} 288} 289 290# 291# atf_pass 292# 293# Makes the test case pass. Shouldn't be used in general, as a test 294# case that does not explicitly fail is assumed to pass. 295# 296atf_pass() 297{ 298 case "${Expect}" in 299 fail) 300 Expect=pass 301 atf_fail "Test case was expecting a failure but got a pass instead" 302 ;; 303 pass) 304 _atf_create_resfile passed 305 exit 0 306 ;; 307 *) 308 _atf_error 128 "Unreachable" 309 ;; 310 esac 311} 312 313# 314# atf_require_prog prog 315# 316# Checks that the given program name (either provided as an absolute 317# path or as a plain file name) can be found. If it is not available, 318# automatically skips the test case with an appropriate message. 319# 320# Relative paths are not allowed because the test case cannot predict 321# where it will be executed from. 322# 323atf_require_prog() 324{ 325 _prog= 326 case ${1} in 327 /*) 328 _prog="${1}" 329 [ -x ${_prog} ] || \ 330 atf_skip "The required program ${1} could not be found" 331 ;; 332 */*) 333 atf_fail "atf_require_prog does not accept relative path names \`${1}'" 334 ;; 335 *) 336 _prog=$(_atf_find_in_path "${1}") 337 [ -n "${_prog}" ] || \ 338 atf_skip "The required program ${1} could not be found" \ 339 "in the PATH" 340 ;; 341 esac 342} 343 344# 345# atf_set varname val1 [.. valN] 346# 347# Sets the test case's variable 'varname' to the specified values 348# which are concatenated using a single blank space. This function 349# is supposed to be called form the test case's head only. 350# 351atf_set() 352{ 353 ${Parsing_Head} || \ 354 _atf_error 128 "atf_set called from the test case's body" 355 356 Test_Case_Vars="${Test_Case_Vars} ${1}" 357 _var=$(_atf_normalize ${1}); shift 358 eval __tc_var_${Test_Case}_${_var}=\"\${*}\" 359} 360 361# 362# atf_skip msg1 [.. msgN] 363# 364# Skips the test case because of the reason provided. Multiple words 365# can be given, in which case they are joined by a single blank space. 366# 367atf_skip() 368{ 369 _atf_create_resfile "skipped: ${*}" 370 exit 0 371} 372 373# 374# atf_test_case tc-name cleanup 375# 376# Defines a new test case named tc-name. The name provided here must be 377# accompanied by two functions named after it: <tc-name>_head and 378# <tc-name>_body. If cleanup is set to 'cleanup', then this also expects 379# a <tc-name>_cleanup function to be defined. 380# 381atf_test_case() 382{ 383 eval "${1}_head() { :; }" 384 eval "${1}_body() { atf_fail 'Test case not implemented'; }" 385 if [ "${2}" = cleanup ]; then 386 eval __has_cleanup_${1}=true 387 eval "${1}_cleanup() { :; }" 388 else 389 eval "${1}_cleanup() { 390 _atf_error 1 'Test case ${1} declared without a cleanup routine'; }" 391 fi 392} 393 394# ------------------------------------------------------------------------ 395# PRIVATE INTERFACE 396# ------------------------------------------------------------------------ 397 398# 399# _atf_config_set varname val1 [.. valN] 400# 401# Sets the test case's private variable 'varname' to the specified 402# values which are concatenated using a single blank space. 403# 404_atf_config_set() 405{ 406 _var=$(_atf_normalize ${1}); shift 407 eval __tc_config_var_${_var}=\"\${*}\" 408 Config_Vars="${Config_Vars} __tc_config_var_${_var}" 409} 410 411# 412# _atf_config_set_str varname=val 413# 414# Sets the test case's private variable 'varname' to the specified 415# value. The parameter is of the form 'varname=val'. 416# 417_atf_config_set_from_str() 418{ 419 _oldifs=${IFS} 420 IFS='=' 421 set -- ${*} 422 _var=${1} 423 shift 424 _val="${@}" 425 IFS=${_oldifs} 426 _atf_config_set "${_var}" "${_val}" 427} 428 429# 430# _atf_create_resfile contents 431# 432# Creates the results file. 433# 434_atf_create_resfile() 435{ 436 if [ -n "${Results_File}" ]; then 437 echo "${*}" >"${Results_File}" || \ 438 _atf_error 128 "Cannot create results file '${Results_File}'" 439 else 440 echo "${*}" 441 fi 442} 443 444# 445# _atf_error error_code [msg1 [.. msgN]] 446# 447# Prints the given error message (which can be composed of multiple 448# arguments, in which case are joined by a single space) and exits 449# with the specified error code. 450# 451# This must not be used by test programs themselves (hence making 452# the function private) to indicate a test case's failure. They 453# have to use the atf_fail function. 454# 455_atf_error() 456{ 457 _error_code="${1}"; shift 458 459 echo "${Prog_Name}: ERROR:" "$@" 1>&2 460 exit ${_error_code} 461} 462 463# 464# _atf_warning msg1 [.. msgN] 465# 466# Prints the given warning message (which can be composed of multiple 467# arguments, in which case are joined by a single space). 468# 469_atf_warning() 470{ 471 echo "${Prog_Name}: WARNING:" "$@" 1>&2 472} 473 474# 475# _atf_find_in_path program 476# 477# Looks for a program in the path and prints the full path to it or 478# nothing if it could not be found. It also returns true in case of 479# success. 480# 481_atf_find_in_path() 482{ 483 _prog="${1}" 484 485 _oldifs=${IFS} 486 IFS=: 487 for _dir in ${PATH} 488 do 489 if [ -x ${_dir}/${_prog} ]; then 490 IFS=${_oldifs} 491 echo ${_dir}/${_prog} 492 return 0 493 fi 494 done 495 IFS=${_oldifs} 496 497 return 1 498} 499 500# 501# _atf_has_tc name 502# 503# Returns true if the given test case exists. 504# 505_atf_has_tc() 506{ 507 for _tc in ${Test_Cases}; do 508 [ "${_tc}" != "${1}" ] || return 0 509 done 510 return 1 511} 512 513# 514# _atf_list_tcs 515# 516# Describes all test cases and prints the list to the standard output. 517# 518_atf_list_tcs() 519{ 520 echo 'Content-Type: application/X-atf-tp; version="1"' 521 echo 522 523 set -- ${Test_Cases} 524 while [ ${#} -gt 0 ]; do 525 _atf_parse_head ${1} 526 527 echo "ident: $(atf_get ident)" 528 for _var in ${Test_Case_Vars}; do 529 [ "${_var}" != "ident" ] && echo "${_var}: $(atf_get ${_var})" 530 done 531 532 [ ${#} -gt 1 ] && echo 533 shift 534 done 535} 536 537# 538# _atf_normalize str 539# 540# Normalizes a string so that it is a valid shell variable name. 541# 542_atf_normalize() 543{ 544 echo ${1} | tr .- __ 545} 546 547# 548# _atf_parse_head tcname 549# 550# Evaluates a test case's head to gather its variables and prepares the 551# test program to run it. 552# 553_atf_parse_head() 554{ 555 Parsing_Head=true 556 557 Test_Case="${1}" 558 Test_Case_Vars= 559 560 if _atf_has_cleanup "${1}"; then 561 atf_set has.cleanup "true" 562 fi 563 564 ${1}_head 565 atf_set ident "${1}" 566 567 Parsing_Head=false 568} 569 570# 571# _atf_run_tc tc 572# 573# Runs the specified test case. Prints its exit status to the 574# standard output and returns a boolean indicating if the test was 575# successful or not. 576# 577_atf_run_tc() 578{ 579 case ${1} in 580 *:*) 581 _tcname=${1%%:*} 582 _tcpart=${1#*:} 583 584 if [ "${_tcpart}" != body -a "${_tcpart}" != cleanup ]; then 585 _atf_syntax_error "Unknown test case part \`${_tcpart}'" 586 fi 587 ;; 588 589 *) 590 _tcname=${1} 591 _tcpart=body 592 ;; 593 esac 594 595 _atf_has_tc "${_tcname}" || _atf_syntax_error "Unknown test case \`${1}'" 596 597 if [ "${__RUNNING_INSIDE_ATF_RUN}" != "internal-yes-value" ]; then 598 _atf_warning "Running test cases without atf-run(1) is unsupported" 599 _atf_warning "No isolation nor timeout control is being applied;" \ 600 "you may get unexpected failures; see atf-test-case(4)" 601 fi 602 603 _atf_parse_head ${_tcname} 604 605 case ${_tcpart} in 606 body) 607 if ${_tcname}_body; then 608 _atf_validate_expect 609 _atf_create_resfile passed 610 else 611 Expect=pass 612 atf_fail "Test case body returned a non-ok exit code, but" \ 613 "this is not allowed" 614 fi 615 ;; 616 cleanup) 617 if _atf_has_cleanup "${_tcname}"; then 618 ${_tcname}_cleanup || _atf_error 128 "The test case cleanup" \ 619 "returned a non-ok exit code, but this is not allowed" 620 fi 621 ;; 622 *) 623 _atf_error 128 "Unknown test case part" 624 ;; 625 esac 626} 627 628# 629# _atf_syntax_error msg1 [.. msgN] 630# 631# Formats and prints a syntax error message and terminates the 632# program prematurely. 633# 634_atf_syntax_error() 635{ 636 echo "${Prog_Name}: ERROR: ${@}" 1>&2 637 echo "${Prog_Name}: See atf-test-program(1) for usage details." 1>&2 638 exit 1 639} 640 641# 642# _atf_has_cleanup tc-name 643# 644# Returns a boolean indicating if the given test case has a cleanup 645# routine or not. 646# 647_atf_has_cleanup() 648{ 649 _found=true 650 eval "[ x\"\${__has_cleanup_${1}}\" = xtrue ] || _found=false" 651 [ "${_found}" = true ] 652} 653 654# 655# _atf_validate_expect 656# 657# Ensures that the current test case state is correct regarding the expect 658# status. 659# 660_atf_validate_expect() 661{ 662 case "${Expect}" in 663 death) 664 Expect=pass 665 atf_fail "Test case was expected to terminate abruptly but it" \ 666 "continued execution" 667 ;; 668 exit) 669 Expect=pass 670 atf_fail "Test case was expected to exit cleanly but it continued" \ 671 "execution" 672 ;; 673 fail) 674 Expect=pass 675 atf_fail "Test case was expecting a failure but none were raised" 676 ;; 677 pass) 678 ;; 679 signal) 680 Expect=pass 681 atf_fail "Test case was expected to receive a termination signal" \ 682 "but it continued execution" 683 ;; 684 timeout) 685 Expect=pass 686 atf_fail "Test case was expected to hang but it continued execution" 687 ;; 688 *) 689 _atf_error 128 "Unreachable" 690 ;; 691 esac 692} 693 694# 695# _atf_warning [msg1 [.. msgN]] 696# 697# Prints the given warning message (which can be composed of multiple 698# arguments, in which case are joined by a single space). 699# 700# This must not be used by test programs themselves (hence making 701# the function private). 702# 703_atf_warning() 704{ 705 echo "${Prog_Name}: WARNING:" "$@" 1>&2 706} 707 708# 709# main [options] test_case 710# 711# Test program's entry point. 712# 713main() 714{ 715 # Process command-line options first. 716 _numargs=${#} 717 _lflag=false 718 while getopts :lr:s:v: arg; do 719 case ${arg} in 720 l) 721 _lflag=true 722 ;; 723 724 r) 725 Results_File=${OPTARG} 726 ;; 727 728 s) 729 Source_Dir=${OPTARG} 730 ;; 731 732 v) 733 _atf_config_set_from_str "${OPTARG}" 734 ;; 735 736 \?) 737 _atf_syntax_error "Unknown option -${OPTARG}." 738 # NOTREACHED 739 ;; 740 esac 741 done 742 shift `expr ${OPTIND} - 1` 743 744 # First of all, make sure that the source directory is correct. It 745 # doesn't matter if the user did not change it, because the default 746 # value may not work. (TODO: It possibly should, even though it is 747 # not a big deal because atf-run deals with this.) 748 case ${Source_Dir} in 749 /*) 750 ;; 751 *) 752 Source_Dir=$(pwd)/${Source_Dir} 753 ;; 754 esac 755 [ -f ${Source_Dir}/${Prog_Name} ] || \ 756 _atf_error 1 "Cannot find the test program in the source" \ 757 "directory \`${Source_Dir}'" 758 759 # Call the test program's hook to register all available test cases. 760 atf_init_test_cases 761 762 # Run or list test cases. 763 if `${_lflag}`; then 764 if [ ${#} -gt 0 ]; then 765 _atf_syntax_error "Cannot provide test case names with -l" 766 fi 767 _atf_list_tcs 768 else 769 if [ ${#} -eq 0 ]; then 770 _atf_syntax_error "Must provide a test case name" 771 elif [ ${#} -gt 1 ]; then 772 _atf_syntax_error "Cannot provide more than one test case name" 773 else 774 _atf_run_tc "${1}" 775 fi 776 fi 777} 778 779# vim: syntax=sh:expandtab:shiftwidth=4:softtabstop=4 780