Tester un module Terraform avec terraform test

Depuis la 1.6, Terraform embarque son propre framework de tests : des fichiers .tftest.hcl décrivent des scénarios, Terraform les applique et vérifie vos assertions. C'est le seul moyen de prouver qu'un module fait ce qu'il annonce, valeurs par défaut comprises, et surtout qu'il refuse ce qu'il doit refuser.

Tout ce qui suit a été exécuté sur Terraform v1.15.4 : sorties, messages d'erreur, événements JSON et codes de retour compris. Deux idées répandues n'y survivent pas, celle du projet enveloppe obligatoire autour du module testé, et celle du terraform test qui ne créerait rien.

Ce que vous allez apprendre

• Où placer une suite pour tester un module, sans configuration autour
• Comment s'écrit un run, avec ses assert et ses variables
• Prouver un refus avec expect_failures, ce qu'aucune assertion ne fait
• Enchaîner des runs, et préparer le terrain avec un module de setup
• Automatiser : code de retour, flux JSON, et le piège du -filter
• Tester sans créer avec command = plan et le mocking

Prérequis

• Terraform 1.6 ou plus récent pour terraform test, 1.7 pour le mocking (installer Terraform).
• Savoir écrire l'interface d'un module, variables, validation et outputs compris.

Où vit une suite de tests

terraform test s'exécute contre la configuration du répertoire courant. Or le répertoire d'un module est une configuration : posez-y un dossier tests/, et vous testez le module lui-même, sans projet enveloppe.

etiquette/
├── main.tf
├── variables.tf
├── outputs.tf
└── tests/
    └── etiquette.tftest.hcl

cd etiquette
terraform test

C'est la forme à privilégier pour un module publié : la suite voyage avec lui, et un consommateur peut la rejouer. Une configuration racine qui appelle le module reste utile pour tester une intégration, pas le module isolé.

Les sorties se lisent directement

Dans une suite posée dans le module, output.<nom> désigne les sorties du module. Depuis un projet enveloppe, il faudrait d'abord republier chaque sortie à la racine pour pouvoir l'assérer, ce qui ajoute du code sans rien prouver de plus.

L'anatomie d'un fichier de test

variables {
  prefixe = "atelier"
}

run "defaut_sans_suffixe" {
  assert {
    condition     = output.etiquette == "atelier"
    error_message = "Sans suffixe, l'etiquette doit valoir le prefixe seul."
  }

  assert {
    condition     = output.longueur == 7
    error_message = "La longueur doit correspondre a l'etiquette produite."
  }
}

Trois niveaux à distinguer, et c'est le point compris de travers le plus souvent. Le bloc variables de niveau fichier s'applique à tous les runs. Un bloc variables dans un run l'emporte, pour ce run seulement. Et chaque run porte autant d'assert que nécessaire, chacun avec son error_message, qui est exactement ce que vous lirez en cas d'échec.

apply par défaut, et de la vraie infrastructure

Un run applique par défaut : « By default, each run block executes with command = apply ». Ce n'est pas un détail, c'est une création réelle de ressources, suivie d'une destruction :

tests/plaque.tftest.hcl... in progress
  run "creation"... pass
tests/plaque.tftest.hcl... tearing down
tests/plaque.tftest.hcl... pass

Après ce passage, le fichier créé par le module a bien disparu, mais le répertoire qui le contenait, lui, reste : le teardown défait ce que le run a créé, pas ses effets de bord. La documentation est explicite sur le risque : « This command creates real infrastructure and will attempt to clean up the testing infrastructure on completion. Monitor the output carefully to ensure this cleanup process is successful. »

Quand seul le plan vous intéresse, dites-le, et rien ne sera créé :

run "verifie_sans_creer" {
  command = plan

  assert {
    condition     = output.etiquette == "atelier"
    error_message = "L'etiquette calculee au plan doit deja etre correcte."
  }
}

Un test sur un vrai fournisseur coûte

Sur un provider cloud, un run en apply crée des ressources facturées, et un teardown en échec les laisse en place. Réservez apply à ce qui exige un attribut calculé après création, et traitez le reste en plan ou en mocking.

Prouver un refus : expect_failures

Un module sérieux refuse les entrées invalides. Ce comportement ne s'asserte pas, puisque rien ne doit être produit : il se déclare.

run "prefixe_trop_court_refuse" {
  command = plan

  variables {
    prefixe = "ab"
  }

  expect_failures = [var.prefixe]
}

Le run passe parce que la validation du module a rejeté la valeur, et pour aucune autre raison. Retirez cette validation, et le même run échoue, avec un message qui nomme l'objet :

Error: Missing expected failure

The checkable object, var.prefixe, was expected to report an error but did
not.

C'est le seul mécanisme qui teste la garde d'un module, et il distingue une suite décrivant un chemin heureux d'une suite décrivant un contrat. Une réserve mesurée : expect_failures ne couvre que les objets de la configuration testée, pas ceux d'un module enfant appelé par elle.

Enchaîner les runs, et préparer le terrain

Les run d'un fichier s'exécutent en séquence et partagent leur contexte. Un run peut donc exécuter une autre configuration pour préparer une valeur :

run "prepare_le_prefixe" {
  module {
    source = "./prefixe"
  }
}

run "utilise_le_prefixe_prepare" {
  variables {
    prefixe = run.prepare_le_prefixe.valeur
  }

  assert {
    condition     = output.etiquette == "ATELIER"
    error_message = "L'etiquette doit reprendre le prefixe prepare."
  }
}

Deux règles à retenir. Le bloc module d'un run n'accepte que source et version, tout autre argument étant refusé sur An argument named "..." is not expected here. Et les sorties d'un run précédent se lisent par run.<nom>.<sortie>, ce qui permet de chaîner un module de préparation et le module testé.

Tester sans créer : le mocking

Depuis la 1.7, un fichier de test peut simuler un provider entier, ce qui répond au besoin « tester sans infrastructure » bien mieux qu'un command = plan :

mock_provider "local" {}

run "sans_provider_reel" {
  assert {
    condition     = output.chemin == "./plaques/atelier.txt"
    error_message = "Le chemin doit etre calcule meme avec un provider simule."
  }
}

Vérifié en 1.15.4 : le run passe, en apply, et aucun fichier réel n'est créé. Les blocs override_resource, override_data et override_module permettent de descendre plus finement, jusqu'à figer les attributs d'une ressource précise.

Automatiser : code de retour et flux JSON

C'est ici que se joue l'intégration continue, et c'est ce que la sortie humaine ne donne pas.

Situation	Code de retour
tous les runs passent	0
un run échoue	1
aucun fichier de test trouvé	0

Glissez pour voir

Le flux JSONL est fait pour être consommé :

terraform test -json

{"type":"test_summary","test_summary":{"status":"pass","passed":4,"failed":0,"errored":0,"skipped":0}}

Les cinq types d'événements observés sont version, test_abstract, test_file, test_run et test_summary. L'option -verbose ajoute test_state pour les runs en apply et test_plan pour ceux en plan, ce qui permet de vérifier qu'une suite emploie bien les deux commandes.

Le filtre qui ne teste rien

Un -filter dont le chemin ne correspond à aucun fichier ne produit ni erreur ni avertissement : Success! 0 passed, 0 failed. et un code de retour 0. Une CI qui se fie à ce seul code peut donc rester verte en n'ayant rien testé. Le chemin est relatif au répertoire de travail, préfixe tests/ compris, et une chaîne sérieuse vérifie aussi le nombre de runs exécutés.

Lire un échec, et ce qui se passe ensuite

Une assertion fausse affiche la condition, un diff et votre message :

  run "defaut_sans_suffixe"... fail

Error: Test assertion failed

  on tests/etiquette.tftest.hcl line 7, in run "defaut_sans_suffixe":
   7:     condition     = output.etiquette == "PAS-CA"
    ├────────────────
    │ Diff:
    │ --- actual
    │ +++ expected
    │ - "atelier"
    │ + "PAS-CA"

Sans suffixe, l'etiquette doit valoir le prefixe seul.

Le sort de la suite du fichier dépend ensuite de la nature du problème, et la nuance est mesurable :

Ce qui arrive	Les runs suivants
une assertion est fausse	s'exécutent quand même
une erreur survient (référence inconnue, plan refusé)	passent en skip

Glissez pour voir

  run "defaut"... fail        ← assertion fausse
  run "avec_suffixe"... pass

  run "defaut"... fail        ← Reference to undeclared output value
  run "avec_suffixe"... skip

Un skipped non nul dans le résumé JSON est donc un signal, jamais un détail : quelque chose a cassé plus tôt, et une partie de la suite n'a rien vérifié.

Une suite se prouve en la faisant échouer

Voici la question qui décide de la valeur d'une suite : détecte-t-elle une régression ? Une suite de quatre runs sans la moindre assertion passe au vert et sort en 0. Le contrôle qui tranche est celui de tout test unitaire, la mutation :

1. Copier le module dans un répertoire temporaire.

2. Casser un seul comportement : retirer une validation, changer une valeur par défaut, remplacer un séparateur.

3. Rejouer la suite contre cette copie, et exiger un code de retour 1.

4. Recommencer pour chaque comportement que la suite prétend couvrir.

Une suite qui survit à une mutation ne teste pas ce qu'elle prétend tester. C'est un contrôle bon marché, et le seul qui distingue une suite utile d'une suite décorative.

init reste nécessaire, parfois

Sur un module autonome, sans provider ni module appelé, terraform test fonctionne sans init. Dès que la configuration appelle un module ou déclare un provider, il faut l'installer d'abord :

Error: Module not installed

This module is not yet installed. Run "terraform init" to install all modules
required by this configuration.

Dépannage

Symptôme	Cause probable	Correction
Success! 0 passed, 0 failed.	aucun fichier trouvé, ou -filter hors cible	vérifier le chemin, relatif au répertoire courant
Error: Module not installed	init non joué sur une configuration qui appelle un module	terraform init
Reference to undeclared output value	l'output asséré n'existe pas dans le module	corriger le nom, les runs suivants étaient en skip
Missing expected failure	la garde attendue n'a pas rejeté la valeur	rétablir la validation, ou corriger l'objet listé
An argument named "..." is not expected here	argument interdit dans le bloc module d'un run	ne garder que source et version
des ressources subsistent après un test	le teardown a échoué	lire la fin de la sortie, nettoyer à la main
Terraform has no command named "test"	binaire antérieur à la 1.6	mettre Terraform à jour

Glissez pour voir

Mettre en pratique

Le lab tester un module vous fait écrire la suite d'un module complet : son défaut, ses deux options, et son refus d'une entrée invalide. La validation ne lit pas votre suite, elle la mute : quatre comportements du module sont cassés à tour de rôle dans une copie, et votre suite doit tomber à chaque fois. Une suite de quatre runs sans assertion passe terraform test et échoue sur cinq contrôles. Il se joue hors ligne.

À retenir

• Une suite posée dans <module>/tests/ teste le module lui-même, sans projet enveloppe.
• Un run applique par défaut : terraform test crée de la vraie infrastructure, puis la détruit.
• Le bloc variables du fichier s'applique à tous les runs, celui d'un run l'emporte.
• expect_failures est le seul moyen de prouver qu'un module refuse une entrée, et il ne couvre que la configuration testée.
• Les runs s'enchaînent : run.<nom>.<sortie>, avec un bloc module limité à source et version.
• Le mocking (1.7+) teste contre un provider simulé, sans rien créer.
• Le code de retour vaut 0 ou 1, et le flux -json porte test_summary.
• Un -filter hors cible rend 0 passed et un code 0 : une CI verte peut n'avoir rien testé.
• Une assertion fausse laisse la suite continuer, une erreur met les runs suivants en skip.
• Une suite ne vaut que ce qu'elle détecte : mutez le module pour le vérifier.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui casse en pratique : la suite qui passe sans rien tester, le refus qu'on ne sait pas prouver, et le test qui crée des ressources bien réelles.

Où placer les fichiers .tftest.hcl d'un module Terraform ?

Dans un dossier tests/ à l'intérieur du module lui-même. terraform test s'exécute contre la configuration du répertoire courant, et le répertoire d'un module en est une : aucune configuration racine enveloppante n'est nécessaire pour assérer ses sorties.

terraform test crée-t-il vraiment des ressources ?

Oui. Chaque bloc run applique par défaut, donc crée l'infrastructure décrite, puis la détruit au teardown. La documentation le dit explicitement et recommande de surveiller la sortie, car un teardown en échec laisse les ressources en place.

Comment tester qu'un module refuse une valeur invalide ?

Avec expect_failures, qui liste les objets censés produire une erreur. Le run passe parce que la validation a rejeté la valeur. Une assertion ne convient pas ici : quand rien ne doit être produit, il n'y a rien à assérer.

Pourquoi mon terraform test affiche-t-il Success! 0 passed, 0 failed ?

Parce qu'aucun fichier de test n'a été trouvé, souvent à cause d'un -filter dont le chemin ne correspond à rien. Terraform ne produit ni erreur ni avertissement et sort en code 0 : une CI qui se fie à ce code seul peut rester verte sans avoir rien testé.

Comment exploiter terraform test dans une CI ?

En lisant le code de retour, 0 si tout passe et 1 dès qu'un run échoue, et en consommant le flux JSONL de l'option -json. L'événement test_summary porte status, passed, failed, errored et skipped, ce que la sortie humaine ne fournit pas.

Un run peut-il réutiliser le résultat du run précédent ?

Oui, les runs d'un même fichier s'exécutent en séquence et partagent leur contexte. Un run peut exécuter une autre configuration via un bloc module, et le suivant lit ses sorties par run.nom.sortie. Ce bloc module n'accepte que source et version.

Une assertion en échec interrompt-elle les runs suivants ?

Non. Une assertion fausse marque le run en fail, et les runs suivants s'exécutent quand même. En revanche une erreur, comme une référence à une sortie inexistante, fait passer les runs suivants en skip : un skipped non nul signale donc qu'une partie de la suite n'a rien vérifié.

Comment savoir si ma suite de tests Terraform sert à quelque chose ?

En mutant le module. Copiez-le, cassez un seul comportement, rejouez la suite et exigez un code de retour 1. Une suite de plusieurs runs sans aucune assertion passe au vert et sort en 0 : seule la mutation distingue une suite utile d'une suite décorative.

Pour aller plus loin

• Anti-patterns des modules : les défauts qu'une suite de tests attrape avant l'appelant.
• Quiz Modules Terraform : un contrôle des acquis sur la conception et le test des modules.
• Le framework de tests : la référence officielle : blocs run, variables, provider et expect_failures.
• Le mocking : la référence officielle : mock_provider, override_resource et override_module.
• La commande test : la référence officielle : toutes les options, -filter, -json et -verbose comprises.

×

📖 Voir la documentation →