Test APIs

This is the bare mininum set of APIs that users should use, and can rely on, while writing tests.

Module contents

avocado.main

alias of TestProgram

class avocado.Test(methodName='test', name=None, params=None, base_logdir=None, tag=None, job=None, runner_queue=None)

Bases: unittest.case.TestCase

Base implementation for the test class.

You’ll inherit from this to write your own tests. Typically you’ll want to implement setUp(), test*() and tearDown() methods on your own tests.

Initializes the test.

Parameters:
  • methodName – Name of the main method to run. For the sake of compatibility with the original unittest class, you should not set this.
  • name – Pretty name of the test name. For normal tests, written with the avocado API, this should not be set, this is reserved for running random executables as tests.
  • base_logdir – Directory where test logs should go. If None provided, it’ll use avocado.data_dir.create_job_logs_dir().
  • tag – Tag that differentiates 2 executions of the same test name. Example: ‘long’, ‘short’, so we can differentiate ‘sleeptest.long’ and ‘sleeptest.short’.
  • job – The job that this test is part of.
check_reference_stderr()
check_reference_stdout()
default_params = {}
error(message=None)

Errors the currently running test.

After calling this method a test will be terminated and have its status as ERROR.

Parameters:message (str) – an optional message that will be recorded in the logs
fail(message=None)

Fails the currently running test.

After calling this method a test will be terminated and have its status as FAIL.

Parameters:message (str) – an optional message that will be recorded in the logs
get_data_path(basename)

Find a test dependency path inside the test data dir.

This is a short hand for an operation that will be commonly used on avocado tests, so we feel it deserves its own API.

Parameters:basename – Basename of the dep file. Ex: testsuite.tar.bz2.
Returns:Path where dependency is supposed to be found.
get_state()

Serialize selected attributes representing the test state

Returns:a dictionary containing relevant test state data
Return type:dict
get_tagged_name(logdir)

Get a test tagged name.

Combines name + tag (if present) to obtain unique name. When associated directory already exists, appends ”.$number” until unused name is generated to avoid clashes.

Parameters:logdir – Log directory being in use for result storage.
Returns:Unique test name
record_reference_stderr()
record_reference_stdout()
report_state()

Send the current test state to the test runner process

run_avocado()

Wraps the run method, for execution inside the avocado runner.

Result:Unused param, compatibility with unittest.TestCase.
setUp()

Setup stage that the test needs before passing to the actual test*.

Must be implemented by tests if they want such an stage. Commonly we’ll download/compile test suites, create files needed for a test, among other possibilities.

skip(message=None)

Skips the currently running test.

This method should only be called from a test’s setUp() method, not anywhere else, since by definition, if a test gets to be executed, it can’t be skipped anymore. If you call this method outside setUp(), avocado will mark your test status as ERROR, and instruct you to fix your test in the error message.

Parameters:message (str) – an optional message that will be recorded in the logs
srcdir = None
tearDown()

Cleanup stage after the test* is done.

Examples of cleanup are deleting temporary files, restoring firewall configurations or other system settings that were changed in setup.

workdir = None
avocado.fail_on(exceptions=None)

Fail the test when decorated function produces exception of the specified type.

(For example, our method may raise IndexError on tested software failure. We can either try/catch it or use this decorator instead)

Parameters:exceptions – Tuple or single exception to be assumed as test fail [Exception]
Note:self.error and self.skip behavior remains intact
Note:To allow simple usage param “exceptions” must not be callable