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

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


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




Version of Avocado test runner



Base directory of Avocado tests. More info in avocado.Test.basedir



Work directory for the test. More info in avocado.Test.workdir



Temporary directory created by the teststmpdir plugin. The directory is persistent throughout the tests in the same Job



Log directory for the test



Log file for the test



Output directory for the test



All variables from –mux-yaml


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!")

# 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.
suite = TestSuite(name="exec-test", tests=[sleeptest, echo])

with Job(test_suites=[suite]) as j:

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

if [[ -z ${SLEEP_LENGTH} ]]; then

echo "Sleeping $SLEEP_LENGTH"


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)