Ansible Collection ansible-test Sanity and Unit Setup Prompt
Stand up ansible-test sanity and unit testing for a collection so module and plugin changes are validated in CI before they ship to Galaxy.
- Target user
- Maintainers of an internal or published Ansible collection who have modules/plugins but no test gate
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior Ansible collection maintainer who ships modules and plugins that other teams depend on. You know `ansible-test` is the canonical way to validate a collection — sanity tests catch documentation and import problems, unit tests cover module logic — and that a collection without these gates rots fast. I will give you a collection layout and the modules/plugins it contains. Set up `ansible-test` sanity and unit testing with a CI gate. Steps: 1. **Sanity tests**: list the sanity checks that matter for this collection (validate-modules, import, pep8, yamllint, the `DOCUMENTATION`/`EXAMPLES`/`RETURN` checks) and show the `ansible-test sanity --docker` invocation, including how to scope it to changed files locally. 2. **Unit tests**: scaffold `tests/unit/` with a sample test that imports a module and asserts behavior on argument validation, mocking `AnsibleModule` so no real system calls happen. 3. **Ignore files**: explain `tests/sanity/ignore-<version>.txt`, when adding an ignore is legitimate versus when it's hiding a real bug, and how to keep the ignore list from growing unbounded. 4. **Matrix**: recommend which ansible-core / Python versions to test against based on the collection's stated support, and lay out a CI matrix. 5. **CI wiring**: produce a CI job (GitHub Actions or GitLab CI) that runs `ansible-test sanity` and `ansible-test units` in containers, failing the build on any failure. 6. **Local parity**: give the exact commands a developer runs locally so CI never surprises them. Fill in: - Collection namespace.name and layout: [DESCRIBE] - Modules/plugins to cover: [LIST] - ansible-core versions to support: [e.g. 2.16, 2.17] - CI system: [GitHub Actions / GitLab CI / other] Output format: the `tests/` directory layout, a sample unit test, the sanity invocation, a CI workflow file, and a short policy on when adding a sanity ignore is acceptable. Do not weaken tests to make CI green. If a sanity check fails, prefer fixing the code over adding an ignore; call out any ignore you propose and why it's safe.
Why this prompt works
A collection is a contract: other teams import its modules and plugins and expect them to keep working across ansible-core upgrades. ansible-test is the tool the wider Ansible community actually uses to enforce that contract, and a collection without a sanity-and-unit gate degrades quietly until a documentation field or an import breaks for downstream users. This prompt sets up exactly the gate that matters — sanity checks for the structural and documentation problems, unit tests for module logic — and wires it into CI so the gate runs on every change rather than living in a maintainer’s memory.
The sanity and ignore-file steps are where this prompt earns its keep. ansible-test sanity runs a battery of checks, and the easy escape hatch when one fails is to add a line to ignore-<version>.txt. That file is necessary sometimes, but it is also where collections hide real bugs from themselves. By making the prompt distinguish a legitimate ignore from a paper-over, and by refusing to weaken tests just to turn CI green, it keeps the test suite meaningful instead of decorative.
The unit-test scaffolding insists on mocking AnsibleModule and system calls, which is the line that keeps unit tests fast, deterministic, and safe to run anywhere — including in a contributor’s PR pipeline. Combined with a version matrix tied to the collection’s stated support and a set of local commands that mirror CI exactly, the result is a test setup that catches regressions before they reach Galaxy and never surprises a developer with a CI failure they could not reproduce.