Testing

This page is for contributors. Every role is tested end to end on a real target, not only linted.

What is tested

Test	Roles	Target
tests/run.sh	traefik, portainer, pulsix_manager, pulsix_worker	A throwaway Docker-in-Docker host (docker:29-dind)
tests/host/run.sh	base, docker, fail2ban, crowdsec, tailscale	A systemd Ubuntu container, per release

Both follow the same sequence:

1. Converge. Apply the roles with the variables from tests/vars.yml.
2. Idempotence. Converge a second time. The run must report changed=0 unreachable=0 failed=0, or the test fails.
3. Verify. A verification playbook checks the result: files, services, configuration and behaviour.

The container test has one more step: a remote worker without a token must fail with the message No enrollment token for: edge-1, and must not start.

Prerequisites

• Docker running on your machine (the tests start privileged containers).
• ansible-core and the collections community.docker, community.general and ansible.posix.
• ansible-lint for the lint step.

Running the tests

ansible-lint                     # lint, configured in .ansible-lint (production profile)
tests/run.sh                     # container roles, Docker-in-Docker
UBUNTU=24.04 tests/host/run.sh   # host roles on Ubuntu 24.04
UBUNTU=26.04 tests/host/run.sh   # host roles on Ubuntu 26.04

The tests link the checkout into tests/output/ansible_collections/noixdev/infra and put that directory first on ANSIBLE_COLLECTIONS_PATH, so they run the code in your working tree rather than an installed copy.

Without UBUNTU, the host test uses 26.04.

Options

Variable	Effect
KEEP=1	Do not remove the test container when the script ends, so you can inspect it.
NOIXDEV_INFRA_TEST_HOST	Name of the test container.
UBUNTU	Ubuntu release of the host test (24.04 or 26.04).

Logs of the idempotence run are written to tests/output/.

The host container

tests/host/Dockerfile builds an Ubuntu image with systemd, D-Bus, OpenSSH, Python and iproute2. The container runs privileged with its own cgroup namespace, so services such as sshd, fail2ban and CrowdSec start as they would on a real server. The script waits until systemd reports running or degraded before it connects.

CI

The GitHub Actions workflow ci.yml runs three jobs: lint (ansible-lint), e2e (tests/run.sh) and hosts (tests/host/run.sh for Ubuntu 24.04 and 26.04 in a matrix). The last two run after the lint job passes.

Adding a role or a variable

• Declare every variable in meta/argument_specs.yml and give it a default in defaults/main.yml.
• Add the role to the converge playbook and a check for its result to the verify playbook.
• Make sure a second converge changes nothing.
• Put no private values, such as real host names, addresses or tokens, in the collection or its tests. Use documentation ranges (RFC 5737, RFC 3849) and example.com.