Writing tests

A good starting point before writing your own test, is to have a look at the existing test modules.

Test class

You can easily write own test modules / classes by inheriting from the ansibleci.test.Test class. When you’ve created your own class as a subclass of ansibleci.test.Test you’ve access to several methods:

class ansibleci.test.Test(runner)

This is the abstract class for all tests, which means all concrete test classes must inherit from this class.

failed(message)

Marks a (sub-)test as failed. This will change the result of the whole test to FAILED.

get_config()

Returns the Runner’s Config instance, which can be used to access configuration params.

get_helper()

Returns the Runner’s Helper instance, which can be used to access common used methods.

get_runner()

Returns the Runner instance which has called / instanced us.

passed(message)

Marks a (sub-)test as passed. This will not change the result of the whole test.

Marking (sub-)tests as passed or failed

To mark a test as passed or failed you can use:

self.passed('Test Foo passed')
self.failed('Test Bar failed')

Accessing config params

To access the config params you should call self.get_config(), which gives you access to the Config instance:

class ansibleci.config.Config(load_defaults=True)

Configuration class which can be used to work with configuration parameters.

The class is designed to work with getters and setters, so you can easily read / write config parameters by accessing the Config instance’s attributes. You can also add complete Python modules to the Config instance by calling the add_module() method.

By default all ansibleci.defaults will be loaded, however you can overwrite that in the constructor.

add_module(module)

Adds configuration parameters from a Python module.

For example, if you want to access the FOOBAR config parameter:

config = self.get_config()
foobar = config.FOOBAR

Helper class

We’re providing a Helper class for common used methods:

class ansibleci.helper.Helper(config)

Helper class which provides common used helper methods.

get_absolute_path(path)

Returns the absolute path of the path argument.

If path is already absolute, nothing changes. If the path is relative, then the BASEDIR will be prepended.

get_item_identifier(item)

Returns the identifier of a (task) item, which by default is the name param of the item. If no name param is defined then the method will return “unknown”.

@todo: Update this method to consider other params when name is not defined (e.g. “include”).

get_roles()

Returns a key-value dict with a roles, while the key is the role name and the value is the absolute role path.

get_roles_paths()

Returns all absolute paths to the roles/ directories, while considering the BASEDIR and ROLES config variables.

get_yaml_items(dir_path, param=None)

Loops through the dir_path and parses all YAML files inside the directory.

If no param is defined, then all YAML items will be returned in a list. If a param is defined, then all items will be scanned for this param and a list of all those values will be returned.

read_yaml(filename)

Reads and parses a YAML file and returns the content.

The helper instance can be accessed by self.get_helper(). For example, if you want to get the roles path:

helper     = self.get_helper()
roles_path = helper.get_roles_path()

Store test class / module

You should never store your custom tests in the existing ansibleci.tests module.

However, you can easily create a new module and store it for example in a tests/ directory next to your main script (i.e. test.py). Just make sure you’ve an __init__.py file in your module directory.

Enable test

To run your own test make sure you add your new test module / class to the ENABLED_TESTS config list and make sure Python can import this path.