Writing an Executable Test

This very simple example of an executable test in shell script:

$ echo '#!/bin/bash' > /tmp/executable_test.sh
$ echo 'exit 0' >> /tmp/executable_test.sh
$ chmod +x /tmp/executable_test.sh

Notice that the file is given executable permissions, which is a requirement for Avocado to treat it as a executable test. Also notice that the script exits with status code 0, which signals a successful result to Avocado.

BASH extensions for Executable tests

Exec-tests written in shell can use a few Avocado utilities. In your shell code, check if the libraries are available with something like:

AVOCADO_SHELL_EXTENSIONS_DIR=$(avocado exec-path 2>/dev/null)

And if available, injects that directory containing those utilities into the PATH used by the shell, making those utilities readily accessible:

if [ $? == 0 ]; then
  PATH=$AVOCADO_SHELL_EXTENSIONS_DIR:$PATH
fi

For a full list of utilities, take a look into at the directory return by avocado exec-path (if any). Also, the example test examples/tests/simplewarning.sh can serve as further inspiration:

#!/bin/sh -e
PATH=$(avocado "exec-path"):$PATH

avocado_debug "Debug message"
avocado_info "Info message"
avocado_warn "Warning message (should cause this test to finish with warning)"
avocado_error "Error message (ordinary message not changing the results)"
echo "Simple output without log-level specification"
exit 0  # no error reported

Tip

These extensions may be available as a separate package. For RPM packages, look for the bash sub-package.

Environment Variables for Tests

Avocado’s environment variables

Avocado exports some information, including test parameters, as environment variables to the running test. Here is a list of the variables that Avocado currently exports to exec-test tests in default:

Environment Variable	Meaning	Example
AVOCADO_VERSION	Version of Avocado test runner	92.0
AVOCADO_TEST_BASEDIR	Base directory of Avocado tests. More info in `avocado.Test.basedir`	$HOME/src/avocado/avocado.dev/examples/tests
AVOCADO_TEST_WORKDIR	Work directory for the test. More info in `avocado.Test.workdir`	/var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test
AVOCADO_TESTS_COMMON_TMPDIR	Temporary directory created by the teststmpdir plugin. The directory is persistent throughout the tests in the same Job	/var/tmp/avocado_XhEdo/
AVOCADO_TEST_LOGDIR	Log directory for the test	/var/tmp/.avocado-task_5t_srpn/test-results/1-Env.test
AVOCADO_TEST_LOGFILE	Log file for the test	/var/tmp/.avocado-taskcx8of8di/test-results/1-Env.test/debug.log
AVOCADO_TEST_OUTPUTDIR	Output directory for the test	/var/tmp/.avocado-taskcx8of8di/test-results/1-Env.test/data
***	All variables from –mux-yaml	TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; …

User’s environment variables

You can also let avocado set your own environment variables. For that, you need to pass the environment variables as keyword arguments (kwargs) to the exec-tests. Here is an example of Job API which passes SLEEP_LENGTH to sleeptest.sh to set the time for which the test should sleep:

#!/usr/bin/env python3

import sys

from avocado.core.job import Job
from avocado.core.nrunner.runnable import Runnable
from avocado.core.suite import TestSuite

# an exec-test runnable consists of a runnable type (exec-test),
# an uri (examples/tests/sleeptest.sh), followed by zero to n arguments
# ending with zero to m keyword arguments.
#
# During the execution, arguments are appended to the uri and keyword
# arguments are converted to environment variable.

# here, SLEEP_LENGTH become an environment variable
sleeptest = Runnable("exec-test", "examples/tests/sleeptest.sh", SLEEP_LENGTH="2")
# here, 'Hello World!' is appended to the uri (/usr/bin/echo)
echo = Runnable("exec-test", "/usr/bin/echo", "Hello World!")

# here, echo-hello-world is used as id of this runnable
id_test = Runnable(
    "exec-test", "/usr/bin/echo", "Hello World!", identifier="echo-hello-world"
)

# the execution of examples/tests/sleeptest.sh takes around 2 seconds
# and the output of the /usr/bin/echo test is available at the
# job-results/latest/test-results/exec-test-2-_usr_bin_echo/stdout file.
# and the last test is the same as the echo, but you can notice that
# the identifier in avocado output is more specific to what this test is doing.
suite = TestSuite(name="exec-test", tests=[sleeptest, echo, id_test])

with Job(test_suites=[suite]) as j:
    sys.exit(j.run())

And now we can see that sleeptest.sh can use SLEEP_LENGTH environment variable:

#!/bin/sh
if [[ -z ${SLEEP_LENGTH} ]]; then
  SLEEP_LENGTH=1
fi

echo "Sleeping $SLEEP_LENGTH"
sleep $SLEEP_LENGTH

Note

All environment variables set by avocado will be accessible only during the test runtime and it won’t change your environment.

Disabling environment variables

Let’s imagine that your testing environment has some important variables, but they could have a negative impact on one of your tests. In that case, avocado lets you disable those variables during the test runtime. To disable a test variable, you need to set it in test kwargs to None like this:

Runnable("exec-test", "examples/tests/sleeptest.sh", SLEEP_LENGTH=None)

If you need to clear the whole environment before your test, then you can set runner.exectest.clear_env config variable. This variable has two options. system and all. If you use system option the testing environment will have only Avocado default variables and variables from test kwargs. If you use all option, the testing environment will have only variables from test kwargs:

Runnable("exec-test", "examples/tests/sleeptest.sh", config={'runner.exectest.clear_env': system}, SLEEP_LENGTH=1)