run-tests

name: run-tests description: Runs and writes tests (sanity, unit, integration) for the community.postgresql 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 the community.postgresql 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/postgresql/ (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/postgresql_db.py --docker -vvv

Unit

Runs unit tests for changed files:

ansible-test units tests/unit/plugins/modules/test_postgresql_query.py --docker -vvv
ansible-test units tests/unit/plugins/module_utils/test_pg_membership.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 live PostgreSQL instance (started by Docker):

ansible-test integration postgresql_db --docker default -vvv
ansible-test integration postgresql_user --docker default -vvv

Integration tests live under tests/integration/targets/<module_name>/. Each target declares setup_postgresql_db as a dependency in tests/integration/targets/<name>/meta/main.yml — this target installs the PostgreSQL server.

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 database state by querying via community.postgresql.postgresql_query → register: result → ansible.builtin.assert
4. This must be done in check_mode: true as well

- name: Create database in check mode
  check_mode: true
  community.postgresql.postgresql_db:
    name: testdb
    state: present
  register: result

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

- name: Verify DB does not exist in PostgreSQL
  community.postgresql.postgresql_query:
    query: "SELECT datname FROM pg_database WHERE datname = 'testdb'"
  register: result

- name: Assert DB is not present
  ansible.builtin.assert:
    that:
      - result.query_result | length == 0

- name: Create database in real mode
  community.postgresql.postgresql_db:
    name: testdb
    state: present
  register: result

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

- name: Verify DB exists in PostgreSQL
  community.postgresql.postgresql_query:
    query: "SELECT datname FROM pg_database WHERE datname = 'testdb'"
  register: result

- name: Assert DB is present
  ansible.builtin.assert:
    that:
      - result.query_result | length == 1

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.