tests/utils/utils.sh

   1 #!/bin/bash
   2 #
   3 # SPDX-License-Identifier: GPL-2.0-only
   4 #
   5 # Copyright (c) 2019 Michael Jeanson <mjeanson@efficios.com>
   6 # Copyright (C) 2019-2023 Philippe Proulx <pproulx@efficios.com>
   7
   8 # Source this file at the beginning of a shell script test to access
   9 # useful testing variables and functions:
  10 #
  11 #     SH_TAP=1
  12 #
  13 #     if [[ -n ${BT_TESTS_SRCDIR:-} ]]; then
  14 #         UTILSSH=$BT_TESTS_SRCDIR/utils/utils.sh
  15 #     else
  16 #         UTILSSH=$(dirname "$0")/../utils/utils.sh
  17 #     fi
  18 #
  19 #     # shellcheck source=../utils/utils.sh
  20 #     source "$UTILSSH"
  21 #
  22 # Make sure the relative path to `utils.sh` (this file) above is
  23 # correct (twice).
  24
  25 # An unbound variable is an error
  26 set -u
  27
  28 # Sets the variable named `$1` to `$2` if it's not set, and exports it.
  29 _bt_tests_set_var_def() {
  30         local -r varname=$1
  31         local -r val=$2
  32
  33         if [[ -z ${!varname:-} ]]; then
  34                 eval "$varname='$val'"
  35         fi
  36
  37         export "${varname?}"
  38 }
  39
  40 # Name of the OS on which we're running, if not set.
  41 #
  42 # One of:
  43 #
  44 # `mingw`:          MinGW (Windows)
  45 # `darwin`:         macOS
  46 # `linux`:          Linux
  47 # `cygwin`:         Cygwin (Windows)
  48 # `unsupported`:    Anything else
  49 #
  50 # See <https://en.wikipedia.org/wiki/Uname#Examples> for possible values
  51 # of `uname -s`.
  52 #
  53 # Do some translation to ease our life down the road for comparison.
  54 # Export it so that executed commands can use it.
  55 if [[ -z ${BT_TESTS_OS_TYPE:-} ]]; then
  56         BT_TESTS_OS_TYPE=$(uname -s)
  57
  58         case $BT_TESTS_OS_TYPE in
  59         MINGW*)
  60                 BT_TESTS_OS_TYPE=mingw
  61                 ;;
  62         Darwin)
  63                 BT_TESTS_OS_TYPE=darwin
  64                 ;;
  65         Linux)
  66                 BT_TESTS_OS_TYPE=linux
  67                 ;;
  68         CYGWIN*)
  69                 BT_TESTS_OS_TYPE=cygwin
  70                 ;;
  71         *)
  72                 BT_TESTS_OS_TYPE=unsupported
  73                 ;;
  74         esac
  75 fi
  76
  77 export BT_TESTS_OS_TYPE
  78
  79 # Sets and exports, if not set:
  80 #
  81 # • `BT_TESTS_SRCDIR` to the base source directory of tests.
  82 # • `BT_TESTS_BUILDDIR` to the base build directory of tests.
  83 _set_vars_srcdir_builddir() {
  84         # If `readlink -f` is available, then get a resolved absolute path
  85         # to the tests source directory. Otherwise, make do with a relative
  86         # path.
  87         local -r scriptdir=$(dirname "${BASH_SOURCE[0]}")
  88         local testsdir
  89
  90         if readlink -f . &> /dev/null; then
  91                 testsdir=$(readlink -f "$scriptdir/..")
  92         else
  93                 testsdir=$scriptdir/..
  94         fi
  95
  96         # Base source directory of tests
  97         _bt_tests_set_var_def BT_TESTS_SRCDIR "$testsdir"
  98
  99         # Base build directory of tests
 100         _bt_tests_set_var_def BT_TESTS_BUILDDIR "$testsdir"
 101 }
 102
 103 _set_vars_srcdir_builddir
 104 unset -f _set_vars_srcdir_builddir
 105
 106 # Sources the generated environment file (`env.sh`) if it exists.
 107 _source_env_sh() {
 108         local -r env_sh_path=$BT_TESTS_BUILDDIR/utils/env.sh
 109
 110         if [[ -f $env_sh_path ]]; then
 111                 # shellcheck disable=SC1090,SC1091
 112                 . "$env_sh_path"
 113         fi
 114 }
 115
 116 _source_env_sh
 117 unset -f _source_env_sh
 118
 119 # Path to the `babeltrace2` command, if not set
 120 if [[ -z ${BT_TESTS_BT2_BIN:-} ]]; then
 121         BT_TESTS_BT2_BIN=$BT_TESTS_BUILDDIR/../src/cli/babeltrace2
 122
 123         if [[ $BT_TESTS_OS_TYPE == mingw ]]; then
 124                 BT_TESTS_BT2_BIN+=.exe
 125         fi
 126 fi
 127
 128 export BT_TESTS_BT2_BIN
 129
 130 # This doesn't need to be exported, but it needs to remain set for
 131 # bt_run_in_py_env() to use it.
 132 #
 133 # TODO: Remove when `tests/bindings/python/bt2/test_plugin.py` is fixed.
 134 _bt_tests_plugins_path=$BT_TESTS_BUILDDIR/../src/plugins
 135
 136 # Colon-separated list of project plugin paths, if not set
 137 _bt_tests_set_var_def BT_TESTS_BABELTRACE_PLUGIN_PATH \
 138         "$_bt_tests_plugins_path/ctf:$_bt_tests_plugins_path/utils:$_bt_tests_plugins_path/text:$_bt_tests_plugins_path/lttng-utils"
 139
 140 # Directory containing the Python plugin provider library, if not set
 141 _bt_tests_set_var_def BT_TESTS_PROVIDER_DIR "$BT_TESTS_BUILDDIR/../src/python-plugin-provider/.libs"
 142
 143 # Directory containing the built `bt2` Python package, if not set
 144 _bt_tests_set_var_def BT_TESTS_PYTHONPATH "$BT_TESTS_BUILDDIR/../src/bindings/python/bt2/build/build_lib"
 145
 146 # Name of the `awk` command to use when testing, if not set
 147 _bt_tests_set_var_def BT_TESTS_AWK_BIN awk
 148
 149 # Name of the `grep` command to use when testing, if not set
 150 _bt_tests_set_var_def BT_TESTS_GREP_BIN grep
 151
 152 # Name of the `python3` command to use when testing, if not set
 153 _bt_tests_set_var_def BT_TESTS_PYTHON_BIN python3
 154
 155 # Major and minor version of the `python3` command to use when testing.
 156 #
 157 # This doesn't need to be exported, but it needs to remain set for
 158 # bt_run_in_py_utils_env() to use it.
 159 _bt_tests_py3_version=$($BT_TESTS_PYTHON_BIN -c 'import sys; print("{}.{}".format(sys.version_info.major, sys.version_info.minor))')
 160
 161 # Name of the `python3-config` command to use when testing, if not set
 162 _bt_tests_set_var_def BT_TESTS_PYTHON_CONFIG_BIN python3-config
 163
 164 # Name of the `sed` command to use when testing, if not set
 165 _bt_tests_set_var_def BT_TESTS_SED_BIN sed
 166
 167 # Name of the `cc` command to use when testing, if not set
 168 _bt_tests_set_var_def BT_TESTS_CC_BIN cc
 169
 170 # Done with _bt_tests_set_var_def()
 171 unset -f _bt_tests_set_var_def
 172
 173 # Whether or not to enable AddressSanitizer, `0` (disabled) if not set.
 174 #
 175 # This doesn't need to be exported from the point of view of this file,
 176 # but the sourced `env.sh` above does export it.
 177 if [[ -z ${BT_TESTS_ENABLE_ASAN:-} ]]; then
 178         BT_TESTS_ENABLE_ASAN=0
 179 fi
 180
 181 # Directory containing test data
 182 BT_TESTS_DATADIR=$BT_TESTS_SRCDIR/data
 183
 184 # Directory containing test CTF traces
 185 BT_CTF_TRACES_PATH=$BT_TESTS_DATADIR/ctf-traces
 186
 187 # Source the shell TAP utilities if `SH_TAP` is `1`
 188 if [[ ${SH_TAP:-} == 1 ]]; then
 189         # shellcheck source=./tap/tap.sh
 190         . "$BT_TESTS_SRCDIR/utils/tap/tap.sh"
 191 fi
 192
 193 # Removes the CR characters from the file having the path `$1`.
 194 #
 195 # This is sometimes needed on Windows with text files.
 196 #
 197 # We can't use the `--string-trailing-cr` option of `diff` because
 198 # Solaris doesn't have it.
 199 bt_remove_cr() {
 200         "$BT_TESTS_SED_BIN" -i'' -e 's/\r//g' "$1"
 201 }
 202
 203 # Prints `$1` without CR characters.
 204 bt_remove_cr_inline() {
 205     "$BT_TESTS_SED_BIN" 's/\r//g' "$1"
 206 }
 207
 208 # Runs the `$BT_TESTS_BT2_BIN` command within an environment which can
 209 # import the `bt2` Python package, redirecting the standard output to
 210 # the `$1` file and the standard error to the `$2` file.
 211 #
 212 # The remaining arguments are forwarded to the `$BT_TESTS_BT2_BIN`
 213 # command.
 214 #
 215 # Returns the exit status of the executed `$BT_TESTS_BT2_BIN`.
 216 bt_cli() {
 217         local -r stdout_file=$1
 218         local -r stderr_file=$2
 219
 220         shift 2
 221
 222         local -a bt_cli_args=("$@")
 223
 224         echo "Running: \`$BT_TESTS_BT2_BIN ${bt_cli_args[*]}\`" >&2
 225         bt_run_in_py_env "$BT_TESTS_BT2_BIN" "${bt_cli_args[@]}" 1>"$stdout_file" 2>"$stderr_file"
 226 }
 227
 228 # Checks the differences between:
 229 #
 230 # • The (expected) contents of the file having the path `$1`.
 231 #
 232 # • The contents of another file having the path `$2`.
 233 #
 234 # Both files are passed through bt_remove_cr_inline() to remove CR
 235 # characters.
 236 #
 237 # Returns 0 if there's no difference, or not zero otherwise.
 238 bt_diff() {
 239         local -r expected_file=$1
 240         local -r actual_file=$2
 241
 242         diff -u <(bt_remove_cr_inline "$expected_file") <(bt_remove_cr_inline "$actual_file") 1>&2
 243 }
 244
 245 # Checks the difference between:
 246 #
 247 # • What the `$BT_TESTS_BT2_BIN` command prints to its standard output
 248 #   when given the third and following arguments of this function.
 249 #
 250 # • The file having the path `$1`.
 251 #
 252 # as well as the difference between:
 253 #
 254 # • What the `$BT_TESTS_BT2_BIN` command prints to its standard error
 255 #   when given the third and following arguments of this function.
 256 #
 257 # • The file having the path `$2`.
 258 #
 259 # Returns 0 if there's no difference, or 1 otherwise, also printing said
 260 # difference to the standard error.
 261 bt_diff_cli() {
 262         local -r expected_stdout_file=$1
 263         local -r expected_stderr_file=$2
 264
 265         shift 2
 266
 267         local -r args=("$@")
 268         local -r temp_stdout_output_file=$(mktemp -t actual-stdout.XXXXXX)
 269         local -r temp_stderr_output_file=$(mktemp -t actual-stderr.XXXXXX)
 270
 271         bt_cli "$temp_stdout_output_file" "$temp_stderr_output_file" "${args[@]}"
 272         bt_diff "$expected_stdout_file" "$temp_stdout_output_file" "${args[@]}"
 273
 274         local -r ret_stdout=$?
 275
 276         bt_diff "$expected_stderr_file" "$temp_stderr_output_file" "${args[@]}"
 277
 278         local -r ret_stderr=$?
 279
 280         rm -f "$temp_stdout_output_file" "$temp_stderr_output_file"
 281         return $((ret_stdout || ret_stderr))
 282 }
 283
 284 # Checks the difference between:
 285 #
 286 # • The content of the file having the path `$1`.
 287 #
 288 # • What the `$BT_TESTS_BT2_BIN` command prints to the standard output
 289 #   when executed with:
 290 #
 291 #   1. The CTF trace directory `$2`.
 292 #   2. The arguments `-c` and `sink.text.details`.
 293 #   3. The third and following arguments of this function.
 294 #
 295 # Returns 0 if there's no difference, or 1 otherwise, also printing said
 296 # difference to the standard error.
 297 bt_diff_details_ctf_single() {
 298         local -r expected_stdout_file=$1
 299         local -r trace_dir=$2
 300
 301         shift 2
 302
 303         local -r extra_details_args=("$@")
 304
 305         # Compare using the CLI with `sink.text.details`
 306         bt_diff_cli "$expected_stdout_file" /dev/null "$trace_dir" \
 307                 -c sink.text.details "${extra_details_args[@]+${extra_details_args[@]}}"
 308 }
 309
 310 # Like bt_diff_details_ctf_single(), except that `$1` is the path to a
 311 # program which generates the CTF trace to compare to.
 312 #
 313 # The program `$1` receives the path to a temporary, empty directory
 314 # where to write the CTF trace as its first argument.
 315 bt_diff_details_ctf_gen_single() {
 316         local -r ctf_gen_prog_path=$1
 317         local -r expected_stdout_file=$2
 318
 319         shift 2
 320
 321         local -r gen_extra_details_args=("$@")
 322         local -r temp_trace_dir=$(mktemp -d)
 323
 324         # Run the CTF trace generator program to get a CTF trace
 325         if ! "$ctf_gen_prog_path" "$temp_trace_dir" 2>/dev/null; then
 326                 echo "ERROR: \`$ctf_gen_prog_path $temp_trace_dir\` failed" >&2
 327                 rm -rf "$temp_trace_dir"
 328                 return 1
 329         fi
 330
 331         # Compare using the CLI with `sink.text.details`
 332         bt_diff_details_ctf_single "$expected_stdout_file" "$temp_trace_dir" \
 333                 "${gen_extra_details_args[@]+${gen_extra_details_args[@]}}"
 334
 335         local -r ret=$?
 336
 337         rm -rf "$temp_trace_dir"
 338         return $ret
 339 }
 340
 341 # Like `grep`, but using `$BT_TESTS_GREP_BIN`.
 342 bt_grep() {
 343         "$BT_TESTS_GREP_BIN" "$@"
 344 }
 345
 346 # Only if `tap.sh` is sourced because bt_grep_ok() uses ok()
 347 if [[ ${SH_TAP:-} == 1 ]]; then
 348         # ok() with the test name `$3` on the result of bt_grep() matching
 349         # the pattern `$1` within the file `$2`.
 350         bt_grep_ok() {
 351                 local -r pattern=$1
 352                 local -r file=$2
 353                 local -r test_name=$3
 354
 355                 bt_grep --silent "$pattern" "$file"
 356
 357                 local -r ret=$?
 358
 359                 if ! ok $ret "$test_name"; then
 360                         {
 361                                 echo "Pattern \`$pattern\` doesn't match the contents of \`$file\`:"
 362                                 echo '--- 8< ---'
 363                                 cat "$file"
 364                                 echo '--- >8 ---'
 365                         } >&2
 366                 fi
 367
 368                 return $ret
 369         }
 370 fi
 371
 372 # Forwards the arguments to `coverage run`.
 373 _bt_tests_check_coverage() {
 374         coverage run "$@"
 375 }
 376
 377 # Executes a command within an environment which can import the testing
 378 # Python modules (in `tests/utils/python`).
 379 bt_run_in_py_utils_env() {
 380         local our_pythonpath=$BT_TESTS_SRCDIR/utils/python
 381
 382         if [[ $_bt_tests_py3_version =~ 3.[45] ]]; then
 383                 # Add a local directory containing a `typing.py` to `PYTHONPATH`
 384                 # for Python 3.4 and Python 3.5 which either don't offer the
 385                 # `typing` module at all, or offer a partial one.
 386                 our_pythonpath=$our_pythonpath:$BT_TESTS_SRCDIR/utils/python/typing
 387         fi
 388
 389         PYTHONPATH=$our_pythonpath${PYTHONPATH:+:}${PYTHONPATH:-} "$@"
 390 }
 391
 392 # Executes a command within an environment which can import the testing
 393 # Python modules (in `tests/utils/python`) and the `bt2` Python package.
 394 bt_run_in_py_env() {
 395         local -x BABELTRACE_PLUGIN_PATH=$BT_TESTS_BABELTRACE_PLUGIN_PATH
 396         local -x LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=$BT_TESTS_PROVIDER_DIR
 397         local -x BT_TESTS_DATADIR=$BT_TESTS_DATADIR
 398         local -x BT_CTF_TRACES_PATH=$BT_CTF_TRACES_PATH
 399         local -x BT_PLUGINS_PATH=$_bt_tests_plugins_path
 400         local -x PYTHONPATH=$BT_TESTS_PYTHONPATH${PYTHONPATH:+:}${PYTHONPATH:-}
 401         local -r main_lib_path=$BT_TESTS_BUILDDIR/../src/lib/.libs
 402
 403         # Set the library search path so that the Python 3 interpreter can
 404         # load `libbabeltrace2`.
 405         if [[ $BT_TESTS_OS_TYPE == mingw || $BT_TESTS_OS_TYPE == cygwin ]]; then
 406                 local -x PATH=$main_lib_path${PATH:+:}${PATH:-}
 407         elif [[ $BT_TESTS_OS_TYPE == darwin ]]; then
 408                 local -x DYLD_LIBRARY_PATH=$main_lib_path${DYLD_LIBRARY_PATH:+:}${DYLD_LIBRARY_PATH:-}
 409         else
 410                 local -x LD_LIBRARY_PATH=$main_lib_path${LD_LIBRARY_PATH:+:}${LD_LIBRARY_PATH:-}
 411         fi
 412
 413         # On Windows, an embedded Python 3 interpreter needs a way to locate
 414         # the path to its internal modules: set the `PYTHONHOME` variable to
 415         # the prefix from `python3-config`.
 416         if [[ $BT_TESTS_OS_TYPE == mingw ]]; then
 417                 local -x PYTHONHOME
 418
 419                 PYTHONHOME=$($BT_TESTS_PYTHON_CONFIG_BIN --prefix)
 420         fi
 421
 422         # If AddressSanitizer is used, we must preload `libasan.so` so that
 423         # libasan doesn't complain about not being the first loaded library.
 424         #
 425         # Python and sed (executed as part of the Libtool wrapper) produce
 426         # some leaks, so we must unfortunately disable leak detection.
 427         #
 428         # Append it to existing `ASAN_OPTIONS` variable, such that we
 429         # override the user's value if it contains `detect_leaks=1`.
 430         if [[ ${BT_TESTS_ENABLE_ASAN:-} == 1 ]]; then
 431                 if $BT_TESTS_CC_BIN --version | head -n 1 | bt_grep -q '^gcc'; then
 432                         local -r lib_asan=$($BT_TESTS_CC_BIN -print-file-name=libasan.so)
 433                         local -r lib_stdcxx=$($BT_TESTS_CC_BIN -print-file-name=libstdc++.so)
 434                         local -x LD_PRELOAD=$lib_asan:$lib_stdcxx${LD_PRELOAD:+:}${LD_PRELOAD:-}
 435                 fi
 436
 437                 local -x ASAN_OPTIONS=${ASAN_OPTIONS:-}${ASAN_OPTIONS:+,}detect_leaks=0
 438         fi
 439
 440         bt_run_in_py_utils_env "$@"
 441 }
 442
 443 # Runs the Python tests matching the pattern `$2` (optional, `*` if
 444 # missing) in the directory `$1` using `testrunner.py`.
 445 #
 446 # This function uses bt_run_in_py_env(), therefore such tests can import
 447 # the testing Python modules (in `tests/utils/python`) and the `bt2`
 448 # Python package.
 449 bt_run_py_test() {
 450         local -r test_dir=$1
 451         local -r test_pattern=${2:-*}
 452         local python_exec
 453
 454         if [[ ${BT_TESTS_COVERAGE:-} == 1 ]]; then
 455                 python_exec=_bt_tests_check_coverage
 456         else
 457                 python_exec=$BT_TESTS_PYTHON_BIN
 458         fi
 459
 460         bt_run_in_py_env \
 461                 "$python_exec" "$BT_TESTS_SRCDIR/utils/python/testrunner.py" \
 462                 --pattern "$test_pattern" "$test_dir"
 463
 464         local -r ret=$?
 465
 466         if [[ ${BT_TESTS_COVERAGE_REPORT:-} == 1 ]]; then
 467                 coverage report -m
 468         fi
 469
 470         if [[ ${BT_TESTS_COVERAGE_HTML:-} == 1 ]]; then
 471                 coverage html
 472         fi
 473
 474         return $ret
 475 }
 476
 477 # Generates a CTF trace into the directory `$2` from the moultipart
 478 # document `$1` using `mctf.py`.
 479 bt_gen_mctf_trace() {
 480         local -r input_file=$1
 481         local -r base_dir=$2
 482         local -r cmd=(
 483                 "$BT_TESTS_PYTHON_BIN" "$BT_TESTS_SRCDIR/utils/python/mctf.py"
 484                 --base-dir "$base_dir"
 485                 "$input_file"
 486         )
 487
 488         echo "Running: \`${cmd[*]}\`" >&2
 489         bt_run_in_py_utils_env "${cmd[@]}"
 490 }
 491
 492 # Call `diag` with the contents of file `$1`.
 493
 494 diag_file() {
 495         diag "$(cat "$1")"
 496 }