Test par instantanés

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Les tests par instantanés sont un outil très utile lorsque vous souhaitez vous assurer que votre interface utilisateur ne change pas de manière inattendue.

Un scénario typique de test par instantanés consiste à :

1. Rendre un composant d'interface
2. Prendre un instantané
3. Le comparer à un fichier de référence stocké avec le test. Le test échouera si les deux instantanés ne correspondent pas : soit le changement est inattendu, soit l'instantané de référence doit être mis à jour vers la nouvelle version du composant.

Test par instantanés avec Jest

Cette approche peut être adaptée pour tester vos composants React. Plutôt que de rendre l'interface graphique (ce qui nécessiterait de construire toute l'application), vous pouvez utiliser un moteur de rendu de test pour générer rapidement une valeur sérialisable de votre arbre React. Consultez cet exemple de test pour un composant Link :

import renderer from 'react-test-renderer';
import Link from '../Link';

it('renders correctly', () => {
  const tree = renderer
    .create(<Link page="http://www.facebook.com">Facebook</Link>)
    .toJSON();
  expect(tree).toMatchSnapshot();
});

Lors du premier exécution, Jest crée un fichier d'instantané ressemblant à ceci :

exports[`renders correctly 1`] = `
<a
  className="normal"
  href="http://www.facebook.com"
  onMouseEnter={[Function]}
  onMouseLeave={[Function]}
>
  Facebook
</a>
`;

L'artefact d'instantané doit être versionné avec les modifications de code et examiné pendant la revue de code. Jest utilise pretty-format pour rendre les instantanés lisibles pendant les revues. Lors des exécutions suivantes, Jest compare le rendu avec l'instantané précédent. S'ils correspondent, le test réussit. Sinon, soit le test a détecté un bogue (dans le composant <Link> ici) à corriger, soit l'implémentation a changé et l'instantané doit être mis à jour.

note

L'instantané concerne uniquement les données que vous rendez – dans notre exemple le composant <Link> avec la prop page. Cela signifie que même si un autre fichier (comme App.js) utilise <Link> avec des props manquantes, le test réussira car il ne connaît pas l'usage du composant <Link> et se limite à Link.js. De plus, rendre le même composant avec différentes props dans d'autres tests n'affectera pas le premier, les tests étant isolés.

info

Plus d'informations sur le fonctionnement et la conception des tests par instantanés sont disponibles dans le billet de publication. Nous recommandons de lire cet article pour comprendre quand utiliser cette technique. Regardez aussi cette vidéo egghead sur les tests par instantanés avec Jest.

Mise à jour des instantanés

Il est facile de repérer un échec de test après l'introduction d'un bogue. Dans ce cas, corrigez le problème pour rétablir les tests. Voyons maintenant le cas où un test échoue suite à une modification intentionnelle de l'implémentation.

Cela peut se produire si nous modifions intentionnellement l'adresse ciblée par le composant Link dans notre exemple.

// Updated test case with a Link to a different address
it('renders correctly', () => {
  const tree = renderer
    .create(<Link page="http://www.instagram.com">Instagram</Link>)
    .toJSON();
  expect(tree).toMatchSnapshot();
});

Dans ce cas, Jest affichera ce résultat :

Puisque nous avons mis à jour notre composant pour pointer vers une adresse différente, il est normal que l'instantané change. Le test échoue car l'instantané du composant mis à jour ne correspond plus à l'artefact de référence.

Pour résoudre ceci, nous devons mettre à jour nos artefacts d'instantanés. Exécutez Jest avec un drapeau qui lui indique de régénérer les instantanés :

jest --updateSnapshot

Allez-y et acceptez les modifications en exécutant la commande ci-dessus. Vous pouvez également utiliser l'équivalent en version raccourcie avec le flag -u pour régénérer les snapshots si vous préférez. Cela régénérera les artefacts de snapshot pour tous les tests de snapshot en échec. Si vous aviez d'autres tests de snapshot en échec suite à un bogue non intentionnel, vous devriez corriger ce bogue avant de régénérer les snapshots pour éviter d'enregistrer des snapshots du comportement erroné.

Si vous souhaitez limiter les cas de test de snapshot à régénérer, vous pouvez passer un flag supplémentaire --testNamePattern pour réenregistrer les snapshots uniquement pour les tests correspondant au motif spécifié.

Vous pouvez tester cette fonctionnalité en clonant l'exemple de snapshot, en modifiant le composant Link et en exécutant Jest.

Mode interactif des snapshots

Les snapshots en échec peuvent également être mis à jour de manière interactive en mode watch :

Une fois entré dans le mode interactif des snapshots, Jest vous guidera à travers les snapshots en échec un test à la fois et vous donnera la possibilité d'examiner le résultat défaillant.

De là, vous pouvez choisir de mettre à jour ce snapshot ou passer au suivant :

Une fois terminé, Jest vous fournira un récapitulatif avant de revenir en mode watch :

Snapshots en ligne

Les snapshots en ligne fonctionnent de manière identique aux snapshots externes (fichiers .snap), sauf que les valeurs des snapshots sont écrites automatiquement dans le code source. Cela signifie que vous bénéficiez des avantages des snapshots générés automatiquement sans avoir à basculer vers un fichier externe pour vérifier que la valeur correcte a été écrite.

Exemple :

Commencez par écrire un test en appelant .toMatchInlineSnapshot() sans arguments :

it('renders correctly', () => {
  const tree = renderer
    .create(<Link page="https://example.com">Example Site</Link>)
    .toJSON();
  expect(tree).toMatchInlineSnapshot();
});

Lors de la prochaine exécution de Jest, tree sera évalué et un snapshot sera écrit comme argument de toMatchInlineSnapshot :

it('renders correctly', () => {
  const tree = renderer
    .create(<Link page="https://example.com">Example Site</Link>)
    .toJSON();
  expect(tree).toMatchInlineSnapshot(`
    <a
      className="normal"
      href="https://example.com"
      onMouseEnter={[Function]}
      onMouseLeave={[Function]}
    >
      Example Site
    </a>
  `);
});

C'est tout ! Vous pouvez même mettre à jour les snapshots avec --updateSnapshot ou en utilisant la touche u en mode --watch.

Par défaut, Jest gère l'écriture des snapshots dans votre code source. Cependant, si vous utilisez prettier dans votre projet, Jest le détectera et déléguera le travail à prettier (en respectant votre configuration).

Comparateurs de propriétés (Property Matchers)

Souvent, des champs dans l'objet que vous souhaitez snapshot sont générés dynamiquement (comme des ID ou des dates). Si vous essayez de snapshot ces objets, ils feront échouer le snapshot à chaque exécution :

it('will fail every time', () => {
  const user = {
    createdAt: new Date(),
    id: Math.floor(Math.random() * 20),
    name: 'LeBron James',
  };

  expect(user).toMatchSnapshot();
});

// Snapshot
exports[`will fail every time 1`] = `
{
  "createdAt": 2018-05-19T23:36:09.816Z,
  "id": 3,
  "name": "LeBron James",
}
`;

Pour ces cas, Jest permet de fournir un comparateur asymétrique pour n'importe quelle propriété. Ces comparateurs sont vérifiés avant l'écriture ou le test du snapshot, puis enregistrés dans le fichier snapshot à la place de la valeur reçue :

it('will check the matchers and pass', () => {
  const user = {
    createdAt: new Date(),
    id: Math.floor(Math.random() * 20),
    name: 'LeBron James',
  };

  expect(user).toMatchSnapshot({
    createdAt: expect.any(Date),
    id: expect.any(Number),
  });
});

// Snapshot
exports[`will check the matchers and pass 1`] = `
{
  "createdAt": Any<Date>,
  "id": Any<Number>,
  "name": "LeBron James",
}
`;

Toute valeur fournie qui n'est pas un comparateur sera vérifiée exactement et sauvegardée dans le snapshot :

it('will check the values and pass', () => {
  const user = {
    createdAt: new Date(),
    name: 'Bond... James Bond',
  };

  expect(user).toMatchSnapshot({
    createdAt: expect.any(Date),
    name: 'Bond... James Bond',
  });
});

// Snapshot
exports[`will check the values and pass 1`] = `
{
  "createdAt": Any<Date>,
  "name": 'Bond... James Bond',
}
`;

astuce

Si le cas concerne une chaîne de caractères plutôt qu'un objet, vous devez remplacer vous-même la partie aléatoire de cette chaîne avant de tester le snapshot.
Vous pouvez utiliser par exemple replace() et les expressions régulières.

const randomNumber = Math.round(Math.random() * 100);
const stringWithRandomData = `<div id="${randomNumber}">Lorem ipsum</div>`;
const stringWithConstantData = stringWithRandomData.replace(/id="\d+"/, 123);
expect(stringWithConstantData).toMatchSnapshot();

D'autres méthodes incluent l'utilisation d'un sérialiseur de snapshot ou le mock de la bibliothèque responsable de générer la partie aléatoire du code que vous snapshottez.

Bonnes pratiques

Les instantanés sont un outil fantastique pour détecter les modifications inattendues d'interface dans votre application – qu'il s'agisse d'une réponse d'API, d'UI, de logs ou de messages d'erreur. Comme pour toute stratégie de test, il existe des bonnes pratiques à connaître et des recommandations à suivre pour les utiliser efficacement.

1. Traitez les instantanés comme du code

Validez les instantanés et examinez-les dans le cadre de votre processus de revue de code habituel. Cela signifie les traiter comme tout autre test ou code dans votre projet.

Assurez-vous que vos instantanés restent lisibles en les gardant ciblés, concis, et en utilisant des outils qui imposent ces conventions stylistiques.

Comme mentionné précédemment, Jest utilise pretty-format pour rendre les instantanés lisibles, mais vous pouvez compléter avec des outils comme eslint-plugin-jest et son option no-large-snapshots, ou snapshot-diff avec sa fonction de comparaison d'instantanés de composants, pour favoriser des assertions courtes et ciblées.

L'objectif est de faciliter l'examen des instantanés dans les demandes de tirage, et de lutter contre l'habitude de régénérer les instantanés lors d'échecs de tests plutôt que d'analyser leurs causes profondes.

2. Les tests doivent être déterministes

Vos tests doivent être déterministes. L'exécution répétée des mêmes tests sur un composant inchangé doit produire systématiquement les mêmes résultats. Il est de votre responsabilité de garantir que vos instantanés générés ne contiennent pas de données spécifiques à une plateforme ou non déterministes.

Par exemple, un composant Clock utilisant Date.now() générera un instantané différent à chaque exécution. Dans ce cas, nous pouvons simuler la méthode Date.now() pour retourner une valeur cohérente :

Date.now = jest.fn(() => 1_482_363_367_071);

Désormais, Date.now() retournera systématiquement 1482363367071 lors de chaque exécution du test, produisant un instantané identique quel que soit le moment du test.

3. Utilisez des noms d'instantanés descriptifs

Privilégiez toujours des noms de tests et/ou d'instantanés descriptifs. Les meilleurs noms décrivent le contenu attendu de l'instantané. Cela aide les relecteurs à vérifier les instantanés et permet à chacun d'identifier si un instantané obsolète correspond au comportement attendu avant sa mise à jour.

Par exemple, comparez :

exports[`<UserName /> should handle some test case`] = `null`;

exports[`<UserName /> should handle some other test case`] = `
<div>
  Alan Turing
</div>
`;

À :

exports[`<UserName /> should render null`] = `null`;

exports[`<UserName /> should render Alan Turing`] = `
<div>
  Alan Turing
</div>
`;

Avec :

exports[`<UserName /> should render null`] = `
<div>
  Alan Turing
</div>
`;

exports[`<UserName /> should render Alan Turing`] = `null`;

Foire aux questions

Les instantanés sont-ils générés automatiquement en intégration continue (CI) ?

Non. Depuis Jest 20, les instantanés ne sont pas générés automatiquement dans les systèmes CI sans l'option explicite --updateSnapshot. Tous les instantanés doivent faire partie du code exécuté en CI. Comme les nouveaux instantanés passent automatiquement les tests, ils ne devraient pas valider une exécution en CI. Nous recommandons de toujours valider les instantanés et de les versionner.

Faut-il versionner les fichiers d'instantanés ?

Oui. Tous les fichiers d'instantanés doivent être versionnés avec les modules correspondants et leurs tests. Ils doivent être considérés comme faisant partie du test, au même titre que toute autre assertion dans Jest. Les instantanés représentent l'état des modules sources à un instant donné. Ainsi, lorsque les modules sources sont modifiés, Jest détecte les changements par rapport à la version précédente. Ils fournissent également un contexte précieux lors des revues de code.

Le test par instantanés fonctionne-t-il uniquement avec les composants React ?

Les composants React et React Native sont de bons cas d'utilisation pour les tests par instantanés. Cependant, les instantanés peuvent capturer n'importe quelle valeur sérialisable et doivent être utilisés chaque fois que l'objectif est de vérifier que la sortie est correcte. Le dépôt Jest contient de nombreux exemples de tests portant sur la sortie de Jest lui-même, la sortie de sa bibliothèque d'assertions ainsi que les messages de journalisation de diverses parties de la codebase. Consultez un exemple de capture de sortie CLI dans le dépôt Jest.

Quelle est la différence entre les tests par instantané et les tests de régression visuelle ?

Les tests par instantané et les tests de régression visuelle sont deux approches distinctes pour tester les interfaces utilisateur, avec des objectifs différents. Les outils de régression visuelle capturent des captures d'écran de pages web et comparent les images obtenues pixel par pixel. Avec les tests par instantané, les valeurs sont sérialisées, stockées dans des fichiers texte et comparées via un algorithme de diff. Il existe différents compromis à considérer, et nous avons listé les raisons de la création des tests par instantané dans le blog Jest.

Les tests par instantané remplacent-ils les tests unitaires ?

Les tests par instantané ne sont qu'une des plus de 20 assertions fournies avec Jest. Leur but n'est pas de remplacer les tests unitaires existants, mais d'apporter une valeur supplémentaire et de simplifier les tests. Dans certains scénarios, ils peuvent potentiellement supprimer le besoin de tests unitaires pour des fonctionnalités spécifiques (ex. composants React), mais les deux approches peuvent aussi fonctionner ensemble.

Quelle est la performance des tests par instantané en termes de vitesse et taille des fichiers générés ?

Jest a été réécrit en priorisant la performance, et les tests par instantané ne font pas exception. Comme les instantanés sont stockés dans des fichiers texte, cette méthode de test est rapide et fiable. Jest génère un nouveau fichier pour chaque fichier de test utilisant le matcher toMatchSnapshot. La taille des instantanés est assez réduite : à titre indicatif, la taille totale des fichiers d'instantanés dans le codebase de Jest lui-même est inférieure à 300 Ko.

Comment résoudre les conflits dans les fichiers d'instantanés ?

Les fichiers d'instantanés doivent toujours refléter l'état actuel des modules qu'ils couvrent. Ainsi, si vous fusionnez deux branches et rencontrez un conflit dans ces fichiers, vous pouvez soit résoudre le conflit manuellement, soit mettre à jour le fichier d'instantané en exécutant Jest et en inspectant le résultat.

Est-il possible d'appliquer les principes du développement piloté par les tests avec les instantanés ?

Bien qu'il soit possible d'écrire manuellement des fichiers d'instantanés, cette approche n'est généralement pas recommandée. Les instantanés aident à détecter les changements dans la sortie des modules testés, plutôt que de guider la conception initiale du code.

La couverture de code fonctionne-t-elle avec les tests par instantané ?

Oui, exactement comme avec tout autre test.