Package: pytest-ansible-playbook
This repository containspytestpluginwhich provides an easy way
to run particularansible playbooksduring 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 withpytest-ansiblemodule, this module doesn’t allow you to
inspectansible factsor 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 forpytest-ansibleinstead. This plugin provides the only
missing ansible feature whichpytest-ansibleis not supposed to provide - to
run ansible playbook file directly.Initial structure of this repository was generated withCookiecutteralong with@hackebrot’sCookiecutter-pytest-plugintemplate.FeaturesThe plugin providesansible_playbookpytest fixture, which allows
one to run one or more ansible playbooks during test setup or tear down of a
test case.It also providescontext managerpytest_ansible_playbook.runner()which can be used to build custom fixtures with anyscopeor to execute
setup and/or teardown playbooks in a code of a test case.It’s compatible with both python2 and python3 (playbooks are executed via
runningansible-playbookin 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.RequirementsAnsible should be installed (so thatansible-playbookbinary is
available in PATH). Use version provided by packaging system of your operation
system.InstallationYou can either installstable release from PyPIor use latest development
version from master branch.Installing stable releaseYou can install “pytest-ansible-playbook” viapipfromPyPI:$ pip install pytest-ansible-playbookInstalling latest development versionThe suggested way to install from sources of current master branch is
viapython virtual enviroment:$ cd pytest-ansible-playbook
$ virtualenv .env
$ source .env/bin/activate
$ pip install -e .Note that you can usevirtualenvwrapperto simplify this workflow.UsageWhen 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. Aansible-playbookprocess 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 withansible 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
withpytest-ansibleplugin.Using ansible playbook fixtureThe plugin provides a single pytest fixture calledansible_playbook. To
specify playbooks to be executed by the fixture, use the followingpytest
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')
@pytest.mark.ansible_playbook_teardown('teardown_foo.yml')
def test_foo(ansible_playbook):
    """
    Some testing is done here.
    """While using markers withoutansible_playbookfixture like this is valid:@pytest.mark.ansible_playbook_setup('setup_foo.yml')
@pytest.mark.ansible_playbook_teardown('teardown_foo.yml')
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.Using ansible playbook runner functionFunctionpytest_ansible_playbook.runneris acontext managerwhich can
be used either to create a custompytest fixtureor to run playbooks within
a test case.Creating custom fixture this way is useful when you want to:define set of setup/teardown playbooks and use it with multiple test cases,run setup or teardown playbooks in any fixturescope(to overcome the fact thatansible_playbookhasfuctionscope),combine run of given setup/teardown playbooks with other non
ansible setup or teardown steps
(to overcome the fact that you can’t useansible_playbookfixture to run
setup/teardown for another fixture, becausepytest doesn’t expect fixtures
to have markers).specify that teardown playbooks are skipped when a test case failsExample of simple custom fixture:iport pytest
from pytest_ansible_playbook import runner

@pytest.fixture(scope="session")
def custom_fixture(request):
    setup_playbooks = ['setup_foo.yml', 'setup_bar.yml']
    teardown_playbooks = ['teardown_foo.yml', 'teardown_bar.yml']
    with runner(request, setup_playbooks, teardown_playbooks):
        # here comes code executed during setup, after running the setup
        # playbooks
        yield
        # here you can place code to be executed during teardown, but
        # before running the teardown playbooks

def test_bar(custom_fixture):
    assert 1 == 1And here is an example of using the fixture inside a test case directly:from pytest_ansible_playbook import runner

def test_foo(request):
    with runner(request, ['setup_foo.yml'], ['teardown_foo.yml']):
        # code here is executed after the setup playbooks, but before the
        # teardown ones
        assert 1 == 1If you want to avoid running teardown playbook(s) when a test case fails, useskip_teardownargument of the runner:with runner(
        request, teardown_playbooks=['teardown.yml'], skip_teardown=True):
    assert 1 == 0ContributingContributions are very welcome. Tests can be run withtox, please ensure
the coverage at least stays the same before you submit a pull request.LicenseDistributed under the terms of theApache License 2.0license,
“pytest-ansible-playbook” is free and open source softwareIssuesIf you encounter any problems, pleasefile an issuealong with a detailed
description.