Les tests de snapshot et de fichier de référence, et comment les garder honnêtes

Ce que c'est

Un test de snapshot (ou de fichier de référence) sérialise une sortie, par exemple un composant rendu, une réponse d'API, la sortie standard d'une commande ou un fichier généré, et la compare à une référence stockée. À la première exécution, la référence est écrite ; ensuite, toute différence fait échouer le test. La documentation de Jest décrit toMatchSnapshot(), qui écrit dans un fichier .snap situé dans un répertoire __snapshots__ à côté du test, les snapshots en ligne réécrits directement dans le code source du test, --updateSnapshot pour régénérer les références après un changement intentionnel, et la règle selon laquelle de nouveaux snapshots ne sont pas écrits automatiquement en CI sans cette option. L'outil insta de Rust suit le même schéma avec des fichiers .snap.new acceptés via cargo insta review, et propose des masquages (redactions) pour les champs volatils.

Pourquoi c'est important

Pour des sorties comportant de nombreux détails, des assertions écrites à la main vérifient quelques champs et laissent passer le reste ; un snapshot vérifie tout, au prix de n'énoncer aucune intention. Il transforme « quelque chose a-t-il changé ? » en un diff qu'un relecteur peut lire, ce qui est exactement ce qu'il faut pour les formats de sortie, les messages d'erreur et les artefacts générés. Bien utilisés, les snapshots sont des tests de caractérisation pour des formats ; mal utilisés, ce sont un tas de diffs approuvés que personne ne lit.

Comment l'appliquer

• Prendre en snapshot les sorties qui constituent des contrats : formes de réponse, configuration générée, texte d'aide, messages d'erreur. Garder chaque snapshot court et ciblé ; la documentation de Jest recommande des snapshots courts et des noms descriptifs, afin qu'un relecteur puisse juger, rien qu'au nom, si le contenu stocké est correct.
• Normaliser les données volatiles avant la sérialisation : horodatages, identifiants générés, ordre de collections non ordonnées, chemins absolus. Jest propose des matchers de propriété tels que expect.any(Date) ; insta propose des masquages.
• Relire les diffs de snapshot dans la pull request comme du code. La documentation de Jest met en garde contre l'habitude de régénérer les snapshots lorsque les suites échouent, au lieu d'en examiner la cause.
• Mettre à jour de façon sélective, par motif de nom de test ou de manière interactive, plutôt que par une mise à jour globale après un échec sans rapport.
• Committer les fichiers de snapshot et faire échouer la CI en cas de fichiers manquants ou obsolètes.

Pièges

Un snapshot qui change à chaque pull request ne teste plus rien et habitue les gens à approuver aveuglément. Des snapshots de pages entières couplent un test à des composants sans rapport. Un snapshot enregistre la sortie actuelle, pas la sortie correcte : un bug capturé lors de la première exécution reste approuvé jusqu'à ce que quelqu'un lise le fichier. La locale, les fins de ligne et le formatage des nombres flottants font différer les snapshots d'une machine à l'autre. Un snapshot ne remplace pas une assertion unique qui énonce l'exigence.