feat: add ansible task testing infrastructure based on Docker and pytest

This complements the existing AMI tests in testinfra by providing
a faster feedback loops for Ansible development without requiring a full
VM.

Also as it is based on Docker, it can be run locally (e.g. macOS) or in CI.

Note that this approach is not intended to replace the AMI tests, but
rather to provide a more efficient way to test Ansible tasks during
development.

Docker is used outside of the Nix sandbox for the moment.

You can run the tests using `nix run -L .\#ansible-test`

Author: jfroche

ansible/tasks/files

@@ -0,0 +1 @@
+../files

ansible/tests/conftest.py

@@ -0,0 +1,12 @@
+def pytest_addoption(parser):
+    parser.addoption(
+        "--ansible-dir",
+        action="store",
+        help="Directory containing Ansible playbooks and roles",
+    )
+
+    parser.addoption(
+        "--docker-image",
+        action="store",
+        help="Docker image and tag to use for testing",
+    )

ansible/tests/nginx.yaml

@@ -0,0 +1,14 @@
+---
+- hosts: localhost
+  tasks:
+  - name: Install dependencies
+    apt:
+      pkg:
+        - build-essential
+      update_cache: yes
+  - import_tasks: ../tasks/setup-nginx.yml
+  - name: Start Nginx service
+    service:
+      name: nginx
+      state: started
+      enabled: yes

ansible/tests/test_nginx.py

@@ -0,0 +1,61 @@
+import pytest
+import subprocess
+import testinfra
+from rich.console import Console
+
+console = Console()
+
+
+@pytest.fixture(scope="session")
+def host(request):
+    ansible_dir = request.config.getoption("--ansible-dir")
+    docker_id = (
+        subprocess.check_output(
+            [
+                "docker",
+                "run",
+                "--privileged",
+                "--cap-add",
+                "SYS_ADMIN",
+                "--security-opt",
+                "seccomp=unconfined",
+                "--cgroup-parent=docker.slice",
+                "--cgroupns",
+                "private",
+                "-v",
+                f"{ansible_dir}/:/ansible/",
+                "-d",
+                "ubuntu-cloudimg-with-tools:0.1",
+            ]
+        )
+        .decode()
+        .strip()
+    )
+    yield testinfra.get_host("docker://" + docker_id)
+    subprocess.check_call(["docker", "rm", "-f", docker_id], stdout=subprocess.DEVNULL)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def run_ansible(host):
+    cmd = [
+        "ANSIBLE_HOST_KEY_CHECKING=False",
+        "ansible-playbook",
+        "--connection=local",
+        "-i",
+        "localhost,",
+        "--extra-vars",
+        "@/ansible/vars.yml",
+        "/ansible/tests/nginx.yaml",
+    ]
+    result = host.run(" ".join(cmd))
+    if result.failed:
+        console.log(result.stdout)
+        console.log(result.stderr)
+        raise pytest.fail(
+            "Ansible playbook nginx.yaml failed with return code {}".format(result.rc)
+        )
+
+
+def test_nginx_service(host):
+    assert host.service("nginx.service").is_valid
+    assert host.service("nginx.service").is_running

nix/packages/ansible-test.nix

@@ -0,0 +1,90 @@
+{
+  pkgs,
+  lib,
+}:
+let
+  ubuntu-cloudimg =
+    let
+      cloudImg = builtins.fetchurl {
+        url = "http://cloud-images-archive.ubuntu.com/releases/noble/release-20250430/ubuntu-24.04-server-cloudimg-amd64-root.tar.xz";
+        sha256 = "sha256:0rfi3qqs0sqarixfic7pzjpx7d4vldv2d98c5zjv7b90mirznvf9";
+      };
+    in
+    pkgs.runCommand "ubuntu-cloudimg" { nativeBuildInputs = [ pkgs.xz ]; } ''
+      mkdir -p $out
+      tar --exclude='dev/*' \
+          --exclude='etc/systemd/system/network-online.target.wants/systemd-networkd-wait-online.service' \
+          --exclude='etc/systemd/system/multi-user.target.wants/systemd-resolved.service' \
+          --exclude='usr/lib/systemd/system/tpm-udev.service' \
+          --exclude='usr/lib/systemd/system/systemd-remount-fs.service' \
+          --exclude='usr/lib/systemd/system/systemd-resolved.service' \
+          --exclude='var/lib/apt/lists/*' \
+          -xJf ${cloudImg} -C $out
+      rm $out/bin $out/lib $out/lib64 $out/sbin
+      mkdir -p $out/run/systemd && echo 'docker' > $out/run/systemd/container
+      mkdir $out/var/lib/apt/lists/partial
+    '';
+
+  dockerImageUbuntu = pkgs.dockerTools.buildImage {
+    name = "ubuntu-cloudimg";
+    tag = "0.1";
+    created = "now";
+    extraCommands = ''
+      ln -s usr/bin
+      ln -s usr/lib
+      ln -s usr/lib64
+      ln -s usr/sbin
+    '';
+    copyToRoot = pkgs.buildEnv {
+      name = "image-root";
+      pathsToLink = [ "/" ];
+      paths = [ ubuntu-cloudimg ];
+    };
+    config.Cmd = [ "/lib/systemd/systemd" ];
+  };
+
+  dockerImageUbuntuWithTools =
+    let
+      tools = [ pkgs.ansible ];
+    in
+    pkgs.dockerTools.buildLayeredImage {
+      name = "ubuntu-cloudimg-with-tools";
+      tag = "0.1";
+      created = "now";
+      maxLayers = 30;
+      fromImage = dockerImageUbuntu;
+      config = {
+        Env = [
+          "PATH=${lib.makeBinPath tools}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+        ];
+        Cmd = [ "/lib/systemd/systemd" ];
+      };
+    };
+in
+pkgs.writeShellApplication {
+  name = "ansible-test";
+  runtimeInputs = with pkgs; [
+    (python3.withPackages (
+      ps: with ps; [
+        requests
+        pytest
+        pytest-testinfra
+        rich
+      ]
+    ))
+  ];
+  text = ''
+    echo "Running Ansible tests..."
+    export DOCKER_IMAGE=${dockerImageUbuntuWithTools.imageName}:${dockerImageUbuntuWithTools.imageTag}
+    if ! docker image inspect $DOCKER_IMAGE > /dev/null; then
+      echo "Loading Docker image..."
+      docker load < ${dockerImageUbuntuWithTools}
+    fi
+    ANSIBLE_DIR=${../../ansible}
+    pytest -p no:cacheprovider -s -v "$@" $ANSIBLE_DIR/tests --ansible-dir=$ANSIBLE_DIR --docker-image=$DOCKER_IMAGE
+  '';
+  meta = with pkgs.lib; {
+    description = "Ansible test runner";
+    platforms = platforms.linux;
+  };
+}

nix/packages/default.nix

@@ -31,6 +31,7 @@
       packages = (
         {
           build-test-ami = pkgs.callPackage ./build-test-ami.nix { };
+          ansible-test = pkgs.callPackage ./ansible-test.nix { };
           cleanup-ami = pkgs.callPackage ./cleanup-ami.nix { };
           dbmate-tool = pkgs.callPackage ./dbmate-tool.nix { inherit (self.supabase) defaults; };
           docs = pkgs.callPackage ./docs.nix { };