Utilisation des comparateurs

Jest utilise des « comparateurs » (NdT « matchers ») pour vous permettre de tester des valeurs de différentes manières. Ce document présente quelques comparateurs couramment utilisés. Pour la liste complète, consultez la documentation de l'API de expect.

Comparateurs courants

La façon la plus simple de tester une valeur est de garantir une égalité exacte.

test('deux plus deux font quatre', () => {
  expect(2 + 2).toBe(4);
});

Dans ce code, expect(2 + 2) retourne un objet « attendu ». En règle générale, vous ne ferez pas grand-chose avec ces objets d'attente, si ce n'est appeler des comparateurs sur ces mêmes objets. Dans ce code, .toBe(4) est le comparateur. Lorsque Jest s'exécute, il repère toutes les comparateurs qui échouent afin de vous afficher de jolis messages d'erreur.

toBe utilise Object.is pour tester l'égalité exacte. Si vous voulez tester la valeur d'un objet, utilisez toEqual :

test('object assignment', () => {
  const data = {one: 1};
  data['two'] = 2;
  expect(data).toEqual({one: 1, two: 2});
});

toEqual vérifie récursivement chaque champ d'un objet ou d'un tableau.

astuce

toEqual ignore les clés d'objets avec des propriétés undefined, les éléments undefined dans les tableaux, les trous dans les tableaux, ou les incompatibilités de types d'objets. Pour prendre en compte ces éléments, utilisez toStrictEqual à la place.

Vous pouvez également tester pour le contraire d'un comparateur en utilisant not:

test('l\'addition de nombres positifs n\'est pas égale à zéro', () => {
  for (let a = 1; a < 10; a++) {
    for (let b = 1; b < 10; b++) {
      expect(a + b).not.toBe(0);
    }
  }
});

Valeur de vérité

Dans les tests, vous devez parfois faire la distinction entre undefined, null et false, mais dans d'autres cas, vous ne souhaitez pas les traiter différemment. Jest dispose d'outils qui vous permettent d'être plus précis sur ce que vous voulez.

• toBeNull correspond uniquement à null
• toBeUndefined correspond uniquement à undefined
• toBeDefined est le contraire de toBeUndefined
• toBeTruthy correspond à tout ce qu'une instruction if traite comme vrai
• toBeFalsy correspond à tout ce qu'une instruction if traite comme faux

Par exemple :

test('null', () => {
  const n = null;
  expect(n).toBeNull();
  expect(n).toBeDefined();
  expect(n).not.toBeUndefined();
  expect(n).not.toBeTruthy();
  expect(n).toBeFalsy();
});

test('zero', () => {
  const z = 0;
  expect(z).not.toBeNull();
  expect(z).toBeDefined();
  expect(z).not.toBeUndefined();
  expect(z).not.toBeTruthy();
  expect(z).toBeFalsy();
});

Vous devez utiliser le comparateur qui correspond le plus précisément à ce que vous voulez que votre code fasse.

Nombres

La plupart des méthodes de comparaison de nombres ont des comparateurs équivalents.

test('deux plus deux', () => {
  const value = 2 + 2;
  expect(value).toBeGreaterThan(3);
  expect(value).toBeGreaterThanOrEqual(3.5);
  expect(value).toBeLessThan(5);
  expect(value).toBeLessThanOrEqual(4.5);

  // toBe et toEqual sont équivalents pour les nombres
  expect(value).toBe(4);
  expect(value).toEqual(4);
});

Pour l'égalité en virgule flottante, utilisez toBeCloseTo au lieu de toEqual, car vous ne voulez pas qu'un test dépende d'une minuscule erreur d'arrondi.

test('ajout de nombres à virgule flottantes', () => {
  const value = 0.1 + 0.2;
  //expect(value).toBe(0.3);           Cela ne fonctionnera pas en raison d'une erreur d'arrondi
  expect(value).toBeCloseTo(0.3); // Cela fonctionne.
});

Chaines de caractères (Strings)

Vous pouvez vérifier les chaînes de caractères par rapport aux expressions régulières avec toMatch :

test("il n'y a pas de I dans team", () => {
  expect('team').not.toMatch(/I/);
});

test('mais il y a "stop" dans Christoph', () => {
  expect('Christoph').toMatch(/stop/);
});

Tableaux et itérables

Vous pouvez vérifier si un tableau ou une itérable contient un élément particulier en utilisant toContain :

const shoppingList = [
  'diapers',
  'kleenex',
  'trash bags',
  'paper towels',
  'milk',
];

test('la liste de course possède du lait', () => {
  expect(shoppingList).toContain('milk');
  expect(new Set(shoppingList)).toContain('milk');
});

Exceptions

Si vous voulez tester si une fonction particulière lève une erreur lorsqu'elle est appelée, utilisez toThrow.

function compileAndroidCode() {
  throw new Error('vous utilisez le mauvais JDK!');
}

test('la compilation d'android se déroule comme prévue', () => {
  expect(() => compileAndroidCode()).toThrow();
  expect(() => compileAndroidCode()).toThrow(Error);

  // Vous pouvez aussi utiliser une chaîne de caractère qui doit être contenue dans le message d'erreur, ou un RegExp
  expect(() => compileAndroidCode()).toThrow('vous utilisez le mauvais JDK!');
  expect(() => compileAndroidCode()).toThrow(/JDK/);

  // Ou vous pouvez faire correspondre un message d'erreur spécifique en utilisant un RegExp comme ci-dessous
  expect(() => compileAndroidCode()).toThrow(/^vous utilisez le mauvais JDK$/); // Test échoué
  expect(() => compileAndroidCode()).toThrow(/^vous utilisez le mauvais JDK!$/); // Test passé
});

astuce

The function that throws an exception needs to be invoked within a wrapping function otherwise the toThrow assertion will fail.

Et bien plus encore

Ce n'est qu'un avant-goût. Pour une liste complète des comparateurs, consultez les docs de référence.

Une fois que vous avez pris connaissance des comparateurs disponibles, la prochaine étape consiste à découvrir comment Jest vous permet de tester du code asynchrone .