Testing Strategies

Last updated: January 12, 2026

📚 Reference: This guide aligns with the official Testing Strategies documentation.

My Testing Journey with Ansible

Early in my Ansible career, I deployed a playbook to production that I thought was perfect. It had worked flawlessly in my test environment. Within minutes of the production run, I realized I'd made a critical error – my test environment didn't accurately reflect production, and a seemingly minor difference caused a catastrophic failure.

That experience taught me a valuable lesson: testing Ansible automation is not optional, it's essential. This guide shares the testing strategies I've developed over years of building production Ansible automation.

Why Test Ansible Code?

You might ask, "Isn't Ansible idempotent? Why do I need tests?" Here's why:

1. Idempotence ≠ Correctness: Ansible may not change state, but that doesn't mean it configured things correctly.

2. Environment Differences: Development and production are never identical.

3. Dependency Changes: Collections and modules update; your code needs to adapt.

4. Team Collaboration: Tests document expected behavior for team members.

5. Confidence: Tests enable you to refactor and improve without fear.

The Testing Pyramid for Ansible

Just like software development, Ansible automation benefits from a testing pyramid:

Level 1: Syntax and Linting (Foundation)

The quickest, cheapest tests catch the most obvious errors.

Level 2: Unit Tests (Core)

Test individual components in isolation.

Level 3: Functional Tests (Middle)

Test roles and tasks with real Ansible execution.

Level 4: Integration Tests (Top)

Test complete playbooks against real or simulated infrastructure.

Level 1: Syntax Validation and Linting

Syntax Checking

Always start with basic syntax validation:

# Check playbook syntax
ansible-playbook site.yml --syntax-check

# Check all playbooks in a directory
find . -name "*.yml" -exec ansible-playbook {} --syntax-check \;

YAML Linting with yamllint

Install and configure yamllint:

# Install
pip install yamllint

# Create configuration: .yamllint
cat > .yamllint << 'EOF'
---
extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
    indent-sequences: yes
  comments:
    min-spaces-from-content: 1
EOF

# Run yamllint
yamllint .

Ansible Linting with ansible-lint

# Install
pip install ansible-lint

# Create configuration: .ansible-lint
cat > .ansible-lint << 'EOF'
---
# Exclude specific rules if needed
skip_list:
  - 'yaml[line-length]'

# Set warning level
warn_list:
  - experimental
  - fqcn-builtins

# Use specific rules
enable_list:
  - no-changed-when
  - no-handler
  - unnamed-task
EOF

# Run ansible-lint
ansible-lint

# Lint specific files
ansible-lint playbooks/deploy.yml

Pre-commit Hooks

Automate syntax checking with git pre-commit hooks:

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
---
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
        args: ['--unsafe']  # For Ansible templates
      - id: check-added-large-files

  - repo: https://github.com/adrienverge/yamllint
    rev: v1.33.0
    hooks:
      - id: yamllint

  - repo: https://github.com/ansible/ansible-lint
    rev: v6.22.1
    hooks:
      - id: ansible-lint
        files: \.(yaml|yml)$
EOF

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Level 2: Unit Testing

Testing Custom Filters

If you've created custom filters, unit test them:

# filter_plugins/custom_filters.py
def calculate_percentage(value, total):
    """Calculate percentage"""
    if total == 0:
        return 0
    return round((value / total) * 100, 2)

class FilterModule:
    def filters(self):
        return {
            'calculate_percentage': calculate_percentage
        }

# tests/unit/test_custom_filters.py
import pytest
from filter_plugins.custom_filters import calculate_percentage

def test_calculate_percentage_normal():
    assert calculate_percentage(25, 100) == 25.0

def test_calculate_percentage_zero_total():
    assert calculate_percentage(10, 0) == 0

def test_calculate_percentage_rounding():
    assert calculate_percentage(1, 3) == 33.33

# Run tests
pytest tests/unit/

Testing Custom Modules

# library/custom_module.py
#!/usr/bin/python
from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            name=dict(type='str', required=True),
            state=dict(type='str', default='present', choices=['present', 'absent'])
        )
    )
    
    # Module logic here
    result = {'changed': False, 'name': module.params['name']}
    module.exit_json(**result)

if __name__ == '__main__':
    main()

# tests/unit/test_custom_module.py
import pytest
from ansible.module_utils import basic
from ansible.module_utils._text import to_bytes
import json

def set_module_args(args):
    """Prepare arguments for AnsibleModule"""
    args = json.dumps({'ANSIBLE_MODULE_ARGS': args})
    basic._ANSIBLE_ARGS = to_bytes(args)

def test_module_present():
    set_module_args({'name': 'test_item', 'state': 'present'})
    
    # Import after setting args
    from library import custom_module
    
    with pytest.raises(SystemExit):
        custom_module.main()

Level 3: Functional Testing with Molecule

Molecule is the standard for testing Ansible roles.

Installing Molecule

# Install molecule with docker driver
pip install "molecule[docker]"

# Or with podman
pip install "molecule[podman]"

# Verify installation
molecule --version

Creating a New Role with Molecule

# Create role with molecule
molecule init role my_role --driver-name docker

# Structure created:
# my_role/
# ├── README.md
# ├── defaults/
# │   └── main.yml
# ├── files/
# ├── handlers/
# │   └── main.yml
# ├── meta/
# │   └── main.yml
# ├── molecule/
# │   └── default/
# │       ├── converge.yml
# │       ├── molecule.yml
# │       └── verify.yml
# ├── tasks/
# │   └── main.yml
# ├── templates/
# ├── tests/
# │   ├── inventory
# │   └── test.yml
# └── vars/
#     └── main.yml

Molecule Configuration

# molecule/default/molecule.yml
---
dependency:
  name: galaxy
  options:
    requirements-file: requirements.yml

driver:
  name: docker

platforms:
  - name: ubuntu-20
    image: geerlingguy/docker-ubuntu2004-ansible:latest
    pre_build_image: true
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:ro
  
  - name: centos-8
    image: geerlingguy/docker-centos8-ansible:latest
    pre_build_image: true
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:ro

provisioner:
  name: ansible
  config_options:
    defaults:
      callbacks_enabled: ansible.posix.profile_tasks
  inventory:
    host_vars:
      ubuntu-20:
        ansible_python_interpreter: /usr/bin/python3

verifier:
  name: ansible

scenario:
  test_sequence:
    - dependency
    - cleanup
    - destroy
    - syntax
    - create
    - prepare
    - converge
    - idempotence
    - side_effect
    - verify
    - cleanup
    - destroy

Converge Playbook

# molecule/default/converge.yml
---
- name: Converge
  hosts: all
  gather_facts: yes
  
  roles:
    - role: my_role
      vars:
        my_role_config:
          setting1: value1
          setting2: value2

Verification Tests

# molecule/default/verify.yml
---
- name: Verify
  hosts: all
  gather_facts: yes
  
  tasks:
    - name: Check if service is running
      service:
        name: myapp
        state: started
      check_mode: yes
      register: service_status
      failed_when: service_status is changed
    
    - name: Verify configuration file exists
      stat:
        path: /etc/myapp/config.yml
      register: config_file
      failed_when: not config_file.stat.exists
    
    - name: Verify configuration content
      slurp:
        path: /etc/myapp/config.yml
      register: config_content
      
    - name: Parse and validate configuration
      set_fact:
        config_data: "{{ config_content.content | b64decode | from_yaml }}"
    
    - name: Assert configuration values
      assert:
        that:
          - config_data.setting1 == 'value1'
          - config_data.setting2 == 'value2'
        fail_msg: "Configuration does not match expected values"

Running Molecule Tests

# Run full test sequence
molecule test

# Just create and converge (for development)
molecule converge

# Verify only
molecule verify

# Test idempotence
molecule idempotence

# Destroy test environment
molecule destroy

# Test against specific platform
molecule test --platform-name ubuntu-20

# Debug with login to container
molecule login --host ubuntu-20

Real-World Molecule Example: Nginx Role

# roles/nginx/molecule/default/molecule.yml
---
driver:
  name: docker

platforms:
  - name: nginx-ubuntu
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    pre_build_image: true
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:ro

provisioner:
  name: ansible
  playbooks:
    prepare: prepare.yml
    converge: converge.yml
    verify: verify.yml

# roles/nginx/molecule/default/prepare.yml
---
- name: Prepare
  hosts: all
  gather_facts: yes
  
  tasks:
    - name: Update apt cache
      apt:
        update_cache: yes
      when: ansible_os_family == 'Debian'

# roles/nginx/molecule/default/converge.yml
---
- name: Converge
  hosts: all
  
  roles:
    - role: nginx
      nginx_vhosts:
        - server_name: example.com
          root: /var/www/example
          index: index.html

# roles/nginx/molecule/default/verify.yml
---
- name: Verify
  hosts: all
  
  tasks:
    - name: Check nginx is installed
      package:
        name: nginx
        state: present
      check_mode: yes
      register: nginx_installed
      failed_when: nginx_installed is changed
    
    - name: Check nginx is running
      service:
        name: nginx
        state: started
      check_mode: yes
      register: nginx_running
      failed_when: nginx_running is changed
    
    - name: Test nginx responds
      uri:
        url: http://localhost
        status_code: 200
      register: nginx_response
    
    - name: Verify vhost configuration
      stat:
        path: /etc/nginx/sites-available/example.com
      register: vhost_config
      failed_when: not vhost_config.stat.exists

Level 4: Integration Testing

Test Kitchen for Ansible (Alternative to Molecule)

# kitchen.yml
---
driver:
  name: docker

provisioner:
  name: ansible_playbook
  hosts: all
  require_ansible_repo: false
  ansible_verbose: true
  ansible_version: 2.16.0

platforms:
  - name: ubuntu-22.04
    driver_config:
      image: ubuntu:22.04
      platform: ubuntu

  - name: centos-8
    driver_config:
      image: centos:8
      platform: centos

suites:
  - name: default
    provisioner:
      playbook: tests/test.yml
    verifier:
      name: inspec
      inspec_tests:
        - tests/integration

ServerSpec for Verification

# tests/integration/default/serverspec/nginx_spec.rb
require 'spec_helper'

describe 'Nginx' do
  describe package('nginx') do
    it { should be_installed }
  end

  describe service('nginx') do
    it { should be_enabled }
    it { should be_running }
  end

  describe port(80) do
    it { should be_listening }
  end

  describe file('/etc/nginx/nginx.conf') do
    it { should exist }
    it { should be_file }
    its(:content) { should match /worker_processes/ }
  end
end

InSpec for Compliance Testing

# tests/integration/default/controls/nginx_spec.rb
control 'nginx-01' do
  impact 1.0
  title 'Nginx should be installed and running'
  desc 'Ensure nginx is properly installed and configured'
  
  describe package('nginx') do
    it { should be_installed }
  end
  
  describe service('nginx') do
    it { should be_installed }
    it { should be_enabled }
    it { should be_running }
  end
  
  describe port(80) do
    it { should be_listening }
  end
end

CI/CD Integration

GitHub Actions

# .github/workflows/ansible-test.yml
name: Ansible Testing

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install ansible-lint yamllint
      
      - name: Run yamllint
        run: yamllint .
      
      - name: Run ansible-lint
        run: ansible-lint

  molecule:
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      matrix:
        distro:
          - ubuntu2204
          - centos8
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install molecule[docker] docker
      
      - name: Run Molecule tests
        run: molecule test
        env:
          MOLECULE_DISTRO: ${{ matrix.distro }}

  integration:
    runs-on: ubuntu-latest
    needs: molecule
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Run integration tests
        run: |
          ansible-playbook tests/integration.yml -i tests/inventory

GitLab CI

# .gitlab-ci.yml
stages:
  - lint
  - test
  - integration

variables:
  PYTHON_VERSION: "3.11"

lint:yaml:
  stage: lint
  image: python:${PYTHON_VERSION}
  before_script:
    - pip install yamllint
  script:
    - yamllint .

lint:ansible:
  stage: lint
  image: python:${PYTHON_VERSION}
  before_script:
    - pip install ansible-lint
  script:
    - ansible-lint

molecule:test:
  stage: test
  image: python:${PYTHON_VERSION}
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  before_script:
    - pip install molecule[docker]
  script:
    - molecule test
  parallel:
    matrix:
      - DISTRO: [ubuntu2204, centos8]

integration:test:
  stage: integration
  image: python:${PYTHON_VERSION}
  script:
    - ansible-playbook tests/integration.yml -i tests/inventory
  only:
    - main
    - develop

Test-Driven Development (TDD) with Ansible

Write Tests First

# tests/test_webserver.yml (written first)
---
- name: Test web server role
  hosts: test_host
  
  tasks:
    - name: Check nginx package
      package:
        name: nginx
        state: present
      check_mode: yes
      register: nginx_pkg
      failed_when: nginx_pkg is changed
    
    - name: Verify nginx service
      service:
        name: nginx
        state: started
        enabled: yes
      check_mode: yes
      register: nginx_svc
      failed_when: nginx_svc is changed

Implement Role to Pass Tests

# roles/webserver/tasks/main.yml (written second)
---
- name: Install nginx
  package:
    name: nginx
    state: present

- name: Start and enable nginx
  service:
    name: nginx
    state: started
    enabled: yes

Performance Testing

Measuring Playbook Performance

---
- name: Performance test
  hosts: all
  
  tasks:
    - name: Enable profiling
      set_fact:
        ansible_callbacks: profile_tasks
    
    - name: Time-sensitive task
      command: /usr/bin/my-command
      register: result
      
    - name: Assert performance
      assert:
        that:
          - result.delta < '00:00:05'  # Less than 5 seconds
        fail_msg: "Task took too long: {{ result.delta }}"

Using ansible-runner for Metrics

import ansible_runner

r = ansible_runner.run(
    private_data_dir='/tmp/demo',
    playbook='test.yml'
)

print(f"Status: {r.status}")
print(f"Return Code: {r.rc}")
print(f"Stats: {r.stats}")

# Analyze timing
for event in r.events:
    if event['event'] == 'runner_on_ok':
        task_name = event['event_data']['task']
        duration = event['event_data'].get('duration', 0)
        print(f"{task_name}: {duration}s")

Best Practices Summary

1. Test at Multiple Levels: Syntax → Unit → Functional → Integration

2. Automate Testing: Use CI/CD pipelines

3. Test Idempotence: Ensure playbooks can run multiple times

4. Test on Multiple Platforms: Use matrix testing

5. Use Check Mode: Test without making changes

6. Version Control Tests: Keep tests with code

7. Document Expected Behavior: Tests are documentation

8. Test Failure Scenarios: Don't just test happy paths

9. Monitor Performance: Track execution time

10. Regular Test Maintenance: Keep tests updated

Conclusion

Testing Ansible automation transforms it from "scripts that might work" to "reliable, documented infrastructure code." Whether you're managing two servers or two thousand, proper testing strategies ensure your automation is dependable, maintainable, and trustworthy.

Start with syntax checks, add linting, incorporate Molecule for roles, and build up to full integration testing. Your infrastructure – and your team – will thank you.

---

Further Reading

• Ansible Testing Strategies

• Molecule Documentation

• ansible-lint Documentation

• InSpec Documentation

Ready to build bulletproof automation? Start testing today! ✅