Tests tox multi-versions : valider un rôle sur ansible-core 2.16, 2.17, 2.18

Un rôle publié doit fonctionner sur plusieurs versions d’ansible-core (votre utilisateur peut être en 2.16, vous développez en 2.18). tox automatise les tests sur la matrice de versions : tox lance molecule test dans un environnement Python isolé pour chaque version d’Ansible.

Cette page utilise un tox.ini classique (sans le plugin tox-ansible) — pattern stable, lisible, et utilisé sur les rôles de production.

Ce que vous allez apprendre

Écrire un tox.ini classique pour rôle Ansible.
Définir une matrice de versions ansible-core (envlist = ansible-2.{16,17,18}).
Configurer Python par version d’Ansible.
Ajouter un env lint séparé pour fail-fast.
Lancer tox complet ou un environnement ciblé.

Prérequis

tox installé : pipx install tox.
Molecule + Podman opérationnels.
Avoir un rôle avec un scénario Molecule fonctionnel.

Structure `tox.ini`

; tox.ini — pattern classique multi-versions ansible-core
[tox]
envlist = ansible-2.{16,17,18}
skipsdist = true

[testenv]
commands = molecule test
setenv =
    TOX_ENVNAME={envname}
    PY_COLORS=1
    ANSIBLE_FORCE_COLOR=1
    ANSIBLE_ROLES_PATH=../
passenv = *

[testenv:ansible-2.16]
basepython = python3.10
deps =
    ansible-core==2.16.*
    ansible-lint==24.*
    molecule>=25.0
    molecule-plugins[podman]>=25.0
    requests
    pytest

[testenv:ansible-2.17]
basepython = python3.10
deps =
    ansible-core==2.17.*
    ansible-lint==24.*
    molecule>=25.0
    molecule-plugins[podman]>=25.0
    requests
    pytest

[testenv:ansible-2.18]
basepython = python3.12
deps =
    ansible-core==2.18.*
    ansible-lint==25.*
    molecule>=26.0
    molecule-plugins[podman]>=25.0
    requests
    pytest

; Lint séparé — fail-fast (s'exécute en premier, isolé)
[testenv:lint]
basepython = python3.12
deps =
    ansible-lint==25.*
    yamllint
commands =
    yamllint roles/
    ansible-lint --profile=production roles/

Anatomie

`[tox]` — section globale

envlist = ansible-2.{16,17,18}
skipsdist = true

envlist = matrice. La syntaxe 2.{16,17,18} génère 3 environnements : ansible-2.16, ansible-2.17, ansible-2.18.
skipsdist = true = pas de package Python à distribuer (un rôle n’a pas de setup.py).

`[testenv]` — config commune

commands = molecule test
setenv =
    ANSIBLE_ROLES_PATH=../
passenv = *

commands : ce qui s’exécute (molecule test pour le cycle complet).
setenv : variables d’env exposées à Ansible.
passenv = * : laisse passer toutes les variables d’env (utile pour tokens, etc.).

`[testenv:ansible-2.X]` — par version

basepython = python3.10
deps =
    ansible-core==2.16.*
    molecule>=25.0

basepython : version Python compatible avec ansible-core ciblée. Ansible 2.16 exige Python 3.10+, Ansible 2.18 exige 3.12+.
deps : pinning des versions exactes.

Lancer les tests

Complet — toutes les versions

tox

Tox crée 3 environnements virtuels Python, installe les deps, lance molecule test dans chacun.

Une seule version

tox -e ansible-2.18

Cible une version spécifique — utile en dev.

Lint seul (fail-fast)

tox -e lint

Lance ansible-lint --profile=production + yamllint. À mettre en premier dans une CI (s’il échoue, pas la peine de lancer Molecule).

Pattern CI/CD typique

# Étape 1 : lint (rapide)
tox -e lint

# Étape 2 : matrice complète
tox

# Étape 3 (sur tag Git) : publication Galaxy
tox -e publish

Comparaison avec d’autres outils

Outil	Périmètre	Recommandation 2026
`tox` classique	Rôles standalone	✅ Recommandé
`tox-ansible`	Collections Ansible	Quand vous publiez une collection
`nox`	Alternative Python à tox	Utilisable mais moins courant en Ansible
GitHub Actions matrix	CI/CD natif	Complémentaire (voir page CI)

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/tests/tox-multiversion/ dans stephrobert/ansible-training.

Le lab fournit un tox.ini complet avec 3 envs ansible-core + 1 env lint. 6 tests structure validés (envlist, deps, lint env).

cd ~/Projets/ansible-training/labs/tests/tox-multiversion/

cat tox.ini
tox -e lint                            # lint rapide
pytest -v challenge/tests/             # tests structure

Pour lancer la matrice complète (long — 5-10 min/env) :

tox

Pièges courants

Symptôme	Cause	Fix
`Python 3.10 not found`	basepython absent du système	Installer Python 3.10 ou utiliser pyenv
`ansible-core 2.16 incompatible avec Python 3.13`	Trop récent	Utiliser Python 3.10 pour Ansible 2.16/2.17
Lent à chaque run	tox recrée les venv	Utiliser `tox -r` (recreate) seulement si deps changent
Tests passent locallement mais ratent en CI	Variables d’env manquantes	Ajouter `passenv = *` ou lister les vars critiques
`molecule test` lent en local	Container recreate à chaque env	Cycle dev : `molecule converge` puis `molecule verify`

À retenir

tox.ini classique > tox-ansible pour rôles standalone.
envlist = ansible-2.{16,17,18} = matrice de versions.
basepython par version d’Ansible (2.16 → 3.10, 2.18 → 3.12).
Env lint séparé pour fail-fast en CI.
tox -e <env> pour cibler une version en dev.

Prochaines étapes

Intégration CI GitHub Actions Workflow GHA qui appelle tox — matrice multi-distro × multi-version

Intégration GitLab CI Pipeline GitLab CI équivalent avec parallel:matrix

ansible-lint profile production Configuration du linter strict appelé par tox -e lint

Versionner et publier Une fois tox vert sur 3 versions, tagger et publier sur Galaxy