skip to navigation
skip to content

pytest-ansible-playbook 0.3.0

Pytest fixture which runs given ansible playbook file.

This repository contains pytest plugin which provides an easy way to run particular ansible playbooks during setup phase of a test case. This is useful when you already have some playbook files you would like to reuse during test setup or plan to maintain test setup in ansible playbooks for you to be able to use it both during test run setup and directly via ansible for other purposes (automatically during deployment or manually when needed).

Compared with pytest-ansible module, this module doesn’t allow you to inspect ansible facts or details about results of each ansible task, nor doest it allow to specify and execute an ansible task directly. So if you need any of that, go for pytest-ansible instead. This plugin provides the only missing ansible feature which pytest-ansible is not supposed to provide - to run ansible playbook file directly.

Initial structure of this repository was generated with Cookiecutter along with @hackebrot’s Cookiecutter-pytest-plugin template.


  • The plugin provides ansible_playbook pytest fixture, which allows one to run one or more ansible playbooks during test setup or tear down.
  • It’s compatible with both python2 and python3 (playbooks are executed via running ansible-playbook in subprocess instead of using api of ansible python module).
  • Doesn’t allow you to configure ansible in any way, all changes of ansible setup needs to be done in ansible playbooks, variable or config files. This encourages you to maintain a clear separation of ansible playbooks and the tests.


Ansible should be installed (so that ansible-playbook binary is available in PATH). Use version provided by packaging system of your operation system.


There is no stable release yet, so the only option is to use latest sources from master branch.

Latest development version

The suggested way to install from sources of current master branch is via python virtual enviroment:

$ cd pytest-ansible-playbook
$ virtualenv .env
$ source .env/bin/activate
$ pip install -e .

Note that you can use virtualenvwrapper to simplify this workflow.


When the plugin is installed, you can use the following command-line parameters:

py.test \
    [--ansible-playbook-directory <path_to_directory_with_playbooks>] \
    [--ansible-playbook-inventory <path_to_inventory_file>]

Where <path_to_directory_with_playbooks> is a directory which contains ansible playbooks and any other ansible files such as configuration or roles if needed. A ansible-playbook process will be able to access the files stored there, since this directory is set as cwd (current working directory) of the ansible process.

The <path_to_inventory_file> is file with ansible inventory. You can use either an absolute path or a relative path within the ansible directory specified via the 1st option.

Note that the option names were chosen this way so that it doesn’t conflict with pytest-ansible plugin.

Using ansible playbook fixture

The plugin provides a single pytest fixture called ansible_playbook. To specify playbooks to be executed by the fixture, use the following pytest markers:

  • @pytest.mark.ansible_playbook_setup('playbook.yml')
  • @pytest.mark.ansible_playbook_teardown('playbook.yml')

Note that you can list multiple playbooks in the marker if needed, eg.:

@pytest.mark.ansible_playbook_setup('playbook.01.yml', 'playbook.02.yml')

both playbooks would be executed in the given order.

Here is an example how to specify 2 playbooks to be run during setup phase of a test case and one for the teardown:

@pytest.mark.ansible_playbook_setup('setup_foo.yml', 'bar.yml')
def test_foo(ansible_playbook):
    Some testing is done here.

While using markers without ansible_playbook fixture like this is valid:

def test_foo():
    Some testing is done here.

no playbook would be executed in such case.

Also note that using a marker without any playbook parameter or using the fixture without any marker is not valid and would cause an error.


Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.


Distributed under the terms of the Apache License 2.0 license, “pytest-ansible-playbook” is free and open source software


If you encounter any problems, please file an issue along with a detailed description.

File Type Py Version Uploaded on Size
pytest-ansible-playbook-0.3.0.tar.gz (md5) Source 2016-11-08 9KB