run-tests

name: run-tests description: Runs and writes tests (sanity, unit, integration) for this Ansible collection using ansible-test. Use when asked to run, check, or write tests for a module or utility. Do not use for PR reviews or questions unrelated to testing.

Skill: run-tests

Purpose

Run and write tests for this Ansible collection. Covers sanity, unit, and integration tests using ansible-test.

When to Invoke

TRIGGER when:

• A user asks to run tests, check tests, or verify changes with tests
• A user asks how to test a module or utility
• A user asks to write tests for new or modified code

DO NOT TRIGGER when:

• Reviewing a PR for overall quality (use .agents/skills/pr-review/SKILL.md instead)
• The question is about module logic unrelated to testing

Test Infrastructure

All tests run inside Docker/Podman via ansible-test --docker. No local package installation is needed. The collection must be installed at ansible_collections/community/libvirt/ (relative to a directory on ANSIBLE_COLLECTIONS_PATHS) for imports to resolve correctly.

Test Commands

Sanity

Checks style, documentation, and imports for a changed file:

ansible-test sanity plugins/modules/virt.py --docker -vvv

Unit

Runs unit tests for changed files:

ansible-test units tests/unit/plugins/modules/test_virt.py --docker -vvv

Unit tests live under tests/unit/plugins/ and use the PyTest framework. Every new function or class method MUST have a corresponding unit test.

Integration

Runs integration tests against a target environment (started by Docker):

ansible-test integration virt --docker default -vvv
ansible-test integration virt_net --docker default -vvv

Integration tests live under tests/integration/targets/<module_name>/.

When Tests Are Required

Integration Test Pattern

Every integration test target must follow this sequence:

1. Call the module under test → register: result
2. Assert on result using ansible.builtin.assert
3. Verify the resulting state independently → register: result → ansible.builtin.assert
4. This must be done in check_mode: true as well

- name: Create network in check mode
  check_mode: true
  community.libvirt.virt_net:
    name: testnet
    command: define
    xml: '{{ lookup("template", "testnet.xml.j2") }}'
  register: result

- name: Assert changed
  ansible.builtin.assert:
    that:
      - result is changed

- name: Create network in real mode
  community.libvirt.virt_net:
    name: testnet
    command: define
    xml: '{{ lookup("template", "testnet.xml.j2") }}'
  register: result

- name: Assert changed
  ansible.builtin.assert:
    that:
      - result is changed

Tests must also cover:

• Idempotency: run the same task a second time and assert result is not changed.
• state: absent: where applicable, remove the resource and assert it is gone.