Test APIs¶
At the most basic level, there’s the Test APIs which you should use when writing tests in Python and planning to make use of any other utility library.
The Test APIs can be found in the avocado main module and its most
important member is the avocado.Test class. By conforming to the
avocado.Test API, that is, by inheriting from it, you can use the full
set of utility libraries.
The Test APIs are guaranteed to be stable across a single major version of Avocado. That means that a test written for a given version of Avocado should not break on later minor versions because of Test API changes.
This is the bare minimum set of APIs that users should use, and can rely on, while writing tests.
Module contents¶
- class avocado.Test(methodName='test', name=None, params=None, base_logdir=None, config=None, runner_queue=None, tags=None)¶
Bases:
TestCase,TestDataBase 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 (
avocado.core.test.TestID) – Pretty name of the test name. For normal tests, written with the avocado API, this should not be set. This is reserved for internal Avocado use, such as when running random executables as tests.base_logdir – Directory where test logs should go. If None provided a temporary directory will be created.
config (dict) – the job configuration, usually set by command line options and argument parsing
- actual_time_end = -1¶
(unix) time when the test finished, actual one to be shown to users
- actual_time_start = -1¶
(unix) time when the test started, actual one to be shown to users
- property basedir¶
The directory where this test (when backed by a file) is located at
- property cache_dirs¶
Returns a list of cache directories as set in config file.
- static cancel(msg=None)¶
Cancels the test.
This method is expected to be called from the test method, not anywhere else, since by definition, we can only cancel a test that is currently under execution. If you call this method outside the test method, avocado will mark your test status as ERROR, and instruct you to fix your test in the error message.
- Parameters
msg (str) – an optional message that will be recorded in the logs
- static error(msg=None)¶
Errors the currently running test.
After calling this method a test will be terminated and have its status as ERROR.
- Parameters
msg (str) – an optional message that will be recorded in the logs
- static fail(msg=None)¶
Fails the currently running test.
After calling this method a test will be terminated and have its status as FAIL.
- Parameters
msg (str) – an optional message that will be recorded in the logs
- property fail_class¶
- property fail_reason¶
- fetch_asset(name, asset_hash=None, algorithm=None, locations=None, expire=None, find_only=False, cancel_on_missing=False)¶
Method o call the utils.asset in order to fetch and asset file supporting hash check, caching and multiple locations.
- Parameters
name – the asset filename or URL
asset_hash – asset hash (optional)
algorithm – hash algorithm (optional, defaults to
avocado.utils.asset.DEFAULT_HASH_ALGORITHM)locations – list of URLs from where the asset can be fetched (optional)
expire – time for the asset to expire
find_only – When True, fetch_asset only looks for the asset in the cache, avoiding the download/move action. Defaults to False.
cancel_on_missing – whether the test should be canceled if the asset was not found in the cache or if fetch could not add the asset to the cache. Defaults to False.
- Raises
OSError – when it fails to fetch the asset or file is not in the cache and cancel_on_missing is False.
- Returns
asset file local path.
- property filename¶
Returns the name of the file (path) that holds the current test
- get_state()¶
Serialize selected attributes representing the test state
- Returns
a dictionary containing relevant test state data
- Return type
- property log¶
The enhanced test log
- property logdir¶
Path to this test’s logging dir
- property logfile¶
Path to this test’s main debug.log file
- property outputdir¶
Directory available to test writers to attach files to the results
- property params¶
Parameters of this test (AvocadoParam instance)
- property phase¶
The current phase of the test execution
Possible (string) values are: INIT, SETUP, TEST, TEARDOWN and FINISHED
- 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.
- property runner_queue¶
The communication channel between test and test runner
- property running¶
Whether this test is currently being executed
- set_runner_queue(runner_queue)¶
Override the runner_queue
- property status¶
The result status of this test
- property tags¶
The tags associated with this test
- tearDown()¶
Hook method for deconstructing the test fixture after testing it.
- property teststmpdir¶
Returns the path of the temporary directory that will stay the same for all tests in a given Job.
- time_elapsed = -1¶
duration of the test execution (always recalculated from time_end - time_start
- time_end = -1¶
(unix) time when the test finished, monotonic (could be forced from test)
- time_start = -1¶
(unix) time when the test started, monotonic (could be forced from test)
- timeout = None¶
Test timeout (the timeout from params takes precedence)
- property traceback¶
- whiteboard = ''¶
Arbitrary string which will be stored in $logdir/whiteboard location when the test finishes.
- property workdir¶
This property returns a writable directory that exists during the entire test execution, but will be cleaned up once the test finishes.
It can be used on tasks such as decompressing source tarballs, building software, etc.
- exception avocado.TestCancel¶
Bases:
TestBaseExceptionIndicates that a test was canceled.
Should be thrown when the cancel() test method is used.
- status = 'CANCEL'¶
- exception avocado.TestError¶
Bases:
TestBaseExceptionIndicates that the test was not fully executed and an error happened.
This is the sort of exception you raise if the test was partially executed and could not complete due to a setup, configuration, or another fatal condition.
- status = 'ERROR'¶
- exception avocado.TestFail¶
Bases:
TestBaseException,AssertionErrorIndicates that the test failed.
TestFail inherits from AssertionError in order to keep compatibility with vanilla python unittests (they only consider failures the ones deriving from AssertionError).
- status = 'FAIL'¶
- avocado.cancel_on(exceptions=None)¶
Cancel the test when decorated function produces exception of the specified type.
- Parameters
exceptions – Tuple or single exception to be assumed as test CANCEL [Exception].
- Note
self.error, self.cancel and self.fail remain intact.
- Note
to allow simple usage param ‘exceptions’ must not be callable.
- avocado.fail_on(exceptions=None)¶
Fail the test when decorated function produces exception of the specified type.
- Parameters
exceptions – Tuple or single exception to be assumed as test FAIL [Exception].
- Note
self.error, self.cancel and self.fail remain intact.
- Note
to allow simple usage param ‘exceptions’ must not be callable.
- avocado.skip(message=None)¶
Decorator to skip a test.
- Parameters
message (str) – the message given when the test is skipped
- avocado.skipIf(condition, message=None)¶
Decorator to skip a test if a condition is True.
- avocado.skipUnless(condition, message=None)¶
Decorator to skip a test if a condition is False.