Skip to main content

Pytest fixture which runs given ansible playbook file.

Project description

pytest-ansible-playbook-runner

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.

Features

Notes

  • The plugin provides ansible_playbook pytest fixture_, which allows one to run one or more ansible playbooks during test setup or tear down of a test case.

  • It also provides context manager_ pytest_ansible_playbook.runner() which can be used to build custom fixtures with any scope_ or to execute setup and/or teardown playbooks in a code of a test case.

  • It's compatible with 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.

Key features

  1. An option to run arbitrary playbooks in the middle of the test:

    def test_something(ansible_playbook,....):
      ...
    ansible_playbook.run_playbook('my_playbook.yml')
      ...
    
  2. An option to add teardown playbooks in the middle of the test:

    def test_something(ansible_playbook,....):
      ...
      ansible_playbook.add_to_teardown({'file': 'my_playbook.yml', 'extra_vars': {})
      ...
    
  3. Return values have been added to every playbook run. The return value respects playbook execution order and for every host:

    def test_something(ansible_playbook,....):
        ...
        ret = ansible_playbook.run_playbook('my_playbook.yml')
        assert ret['localhost'][0]['msg'] == 'line added'
    	...
    
  4. A test can pass arguments to the playbooks it runs. Thus the playbook has changed from string to dictionary:

    def test_something(ansible_playbook,....):
        ...
        ansible_playbook.run_playbook(
            'my_playbook.yml',
            {'play_host_groupd': 'some_ansible_group', 'param1': 'value1'}
        )
        ...
    
  5. Mark setup / teardown syntax:

    @pytest.mark.ansible_playbook_setup(
        {'file': 'some_playbook.yml', 'extra_vars': 
         {'play_host_groupd': 'some_ansible_group', 'param1': 'value1'}}
    )
    @pytest.mark.ansible_playbook_teardown(
        {'file': 'my_teardown1.yml', 'extra_vars':
         {'play_host_groupd': 'some_ansible_group', 'param1': 'value1'}},
        {'file': 'my_teardown2.yml', 'extra_vars':
         {'play_host_groupd': 'some_ansible_group', 'param1': 'value1'}}
    )
    def test_something(ansible_playbook,....):
        ...
        ansible_playbook.run_playbook(
            'my_playbook.yml',
            {'play_host_groupd': 'some_ansible_group', 'param1': 'value1'}
        )
        ...
    

Now the pytest plugin uses a separate module: playbook_runner. https://github.com/final-israel/playbook_runner This is because other tools may want to also run playbooks not necessarily as a part of the pytest framework.

Requirements

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

Installation

You can either install stable release from PyPI or use latest development version from master branch.

  • Installing stable release - You can install pytest-ansible-playbook-runner via pip from PyPI:
pip install pytest-ansible-playbook-runner
  • Installing latest development version

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

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

Note that you can use virtualenvwrapper to simplify this workflow.

Usage

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.

Example of simple custom fixture:

import pytest
from pytest_ansible_playbook import fixture_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 fixture_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 == 1

And here is an example of using the fixture inside a test case directly:

from pytest_ansible_playbook import fixture_runner

def test_foo(request):
    with fixture_runner(request, ['setup_foo.yml'], ['teardown_foo.yml']):
        # code here is executed after the setup playbooks, but before the
        # teardown ones
        assert 1 == 1

Contributing

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.

License

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

Issues

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

.. file an issue: https://github.com/final-israel/pytest-ansible-playbook-runner/issues .. Cookiecutter: https://github.com/audreyr/cookiecutter .. @hackebrot: https://github.com/hackebrot .. cookiecutter-pytest-plugin: https://github.com/pytest-dev/cookiecutter-pytest-plugin .. pytest: http://docs.pytest.org/en/latest/ .. pytest fixture: http://doc.pytest.org/en/latest/fixture.html .. pytest markers: http://doc.pytest.org/en/latest/example/markers.html .. plugin: http://doc.pytest.org/en/latest/plugins.html .. tox: https://tox.readthedocs.io/en/latest/ .. pip: https://pypi.python.org/pypi/pip/ .. PyPI: https://pypi.python.org/pypi .. stable release from PyPI: https://pypi.org/project/pytest-ansible-playbook-runner/ .. python virtual enviroment: https://virtualenv.pypa.io/en/stable/ .. virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/ .. pytest-ansible: https://pypi.python.org/pypi/pytest-ansible .. ansible playbooks: https://docs.ansible.com/ansible/playbooks.html .. ansible facts: https://docs.ansible.com/ansible/playbooks_variables.html#information-discovered-from-systems-facts .. ansible inventory: https://docs.ansible.com/ansible/intro_inventory.html .. Apache License 2.0: http://www.apache.org/licenses/LICENSE-2.0 .. context manager: https://docs.python.org/3.6/library/stdtypes.html#context-manager-types .. scope: https://docs.pytest.org/en/latest/fixture.html#scope-sharing-a-fixture-instance-across-tests-in-a-class-module-or-session .. pytest doesn't expect fixtures to have markers: https://github.com/pytest-dev/pytest/issues/3664

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest-ansible-playbook-runner-0.5.4.tar.gz (12.7 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file pytest-ansible-playbook-runner-0.5.4.tar.gz.

File metadata

  • Download URL: pytest-ansible-playbook-runner-0.5.4.tar.gz
  • Upload date:
  • Size: 12.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.1.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.7.5

File hashes

Hashes for pytest-ansible-playbook-runner-0.5.4.tar.gz
Algorithm Hash digest
SHA256 c31c0447a9f467bc080a8d951b62ae286ddd6ef4eeade15748f81c41267659ef
MD5 0cdf5a503daf10d91bee66c928df6bbc
BLAKE2b-256 5c0df6971a01ad83cd554a1d2a31c172d5a4c733e60c5f7f99ad18ecb644b721

See more details on using hashes here.

File details

Details for the file pytest_ansible_playbook_runner-0.5.4-py3-none-any.whl.

File metadata

  • Download URL: pytest_ansible_playbook_runner-0.5.4-py3-none-any.whl
  • Upload date:
  • Size: 12.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.1.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.7.5

File hashes

Hashes for pytest_ansible_playbook_runner-0.5.4-py3-none-any.whl
Algorithm Hash digest
SHA256 81a187797b58077147f415eacb0f8864e0910000b389a5736b2c79856f8a5c1a
MD5 dfcdf248f09bd51c2dfcdd5eb80c050b
BLAKE2b-256 03f2316a6c602636bfb8f95cf8fa9ea0a41022c4b3ba33da9d10bc1678ca0749

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page