pytest-ansible

Warnings

• breaking Version 2.0.0 introduced major changes to allow Ansible-style inventory indexing and improved results processing, shifting from dictionaries to Python objects. Tests written for older versions might require updates to handle these changes in result structures.
  Fix: Review and update test assertions to accommodate the new Python object-based result structures and Ansible-style inventory indexing introduced in 2.0.0 and later versions.
• deprecated Version 1.4.0 started raising `DeprecationWarnings` for `scope=class` fixtures. While they might still function, it's recommended to migrate away from them for future compatibility.
  Fix: Refactor fixtures from `scope=class` to a more appropriate scope (e.g., `module` or `function`) or use alternative patterns for resource setup/teardown within your test suite.
• gotcha The `pytest-molecule` plugin's functionality has been merged into `pytest-ansible`. Users of `pytest-molecule` should migrate to `pytest-ansible` for ongoing support and future updates.
  Fix: Uninstall `pytest-molecule` and install `pytest-ansible`. Update test configurations to leverage the integrated Molecule scenario testing within `pytest-ansible`.
• gotcha `pytest-ansible` only guarantees support for actively maintained versions of Python (>=3.10) and `ansible-core` (>=2.14). Using older versions may lead to unexpected behavior or lack of support.
  Fix: Ensure your environment uses Python 3.10 or newer and `ansible-core` 2.14 or newer to maintain compatibility and receive full support.
• gotcha There are reported conflicts when `pytest-ansible` is used alongside `testinfra`. This can lead to unexpected test failures or behavior.
  Fix: If encountering issues, investigate specific interactions between the two plugins. Consider isolating tests that use `pytest-ansible` from those that use `testinfra` or consult the project's issue tracker for potential workarounds or fixes.

Install

• pip install pytest-ansible Install stable version

Imports

• ansible_adhoc

  import pytest # Fixtures like ansible_adhoc are made available by the plugin

  pytest-ansible primarily provides fixtures (e.g., `ansible_adhoc`, `ansible_module`) that are automatically discovered by pytest. Direct imports from `pytest_ansible` are generally not needed for typical test usage.

Quickstart

This quickstart demonstrates how to write a basic pytest test using the `ansible_adhoc` fixture provided by `pytest-ansible`. It shows how to execute an Ansible module (like `setup` or `ping`) against a local host and assert its results. A minimal Ansible inventory file (`hosts.ini`) is required for the tests to run successfully, which can be specified via the `--ansible-inventory` pytest option.

import pytest
import os

# --- Required Setup: inventory file (e.g., hosts.ini) ---
# [local]
# localhost ansible_connection=local
# ---------------------------------------------------------

def test_local_setup_module(ansible_adhoc):
    """
    Tests the 'setup' module on 'localhost' using the ansible_adhoc fixture.
    Requires an Ansible inventory file (e.g., hosts.ini) in the current
    working directory or specified via `--ansible-inventory` when running pytest.
    """
    # Run the 'setup' module on 'localhost'
    contacted = ansible_adhoc("setup", host_pattern="localhost")

    # Assert that 'localhost' was contacted and 'changed' is not in its result
    assert 'localhost' in contacted
    assert 'changed' not in contacted['localhost']
    assert 'ansible_facts' in contacted['localhost']

def test_ansible_ping_module(ansible_adhoc):
    """
    Tests the 'ping' module on 'localhost'.
    """
    contacted = ansible_adhoc("ping", host_pattern="localhost")
    assert 'localhost' in contacted
    assert contacted['localhost']['ping'] == 'pong'

# To run this example:
# 1. Save the above content as 'test_ansible_module.py'.
# 2. Create a file named 'hosts.ini' in the same directory with the content:
#    [local]
#    localhost ansible_connection=local
# 3. Execute pytest from your terminal: `pytest --ansible-inventory=hosts.ini test_ansible_module.py`