Les assertions dans Vitest

Les assertions sont au cœur des tests unitaires et permettent de vérifier que le comportement de votre code est conforme à vos attentes. Vitest utilise une API d’assertions compatible avec Jest, ce qui facilite la transition si vous avez déjà utilisé Jest.

Assertions de base

Voici les assertions les plus couramment utilisées :

import { expect, test } from 'vitest'

test('assertions de base', () => {
  // Vérification d'égalité
  expect(2 + 2).toBe(4)

  // Vérification d'égalité pour les objets
  expect({ name: 'John' }).toEqual({ name: 'John' })

  // Vérification de type
  expect('hello').toBeTypeOf('string')
  expect(123).toBeTypeOf('number')

  // Vérification de présence dans un tableau
  expect([1, 2, 3]).toContain(2)

  // Vérification de vérité
  expect(true).toBeTruthy()
  expect(false).toBeFalsy()

  // Vérification de nullité
  expect(null).toBeNull()
  expect(undefined).toBeUndefined()

  // Comparaisons numériques
  expect(10).toBeGreaterThan(5)
  expect(5).toBeLessThan(10)
})

Négation des assertions

Vous pouvez inverser n’importe quelle assertion en utilisant .not :

test('assertions négatives', () => {
  expect(2 + 2).not.toBe(5)
  expect('hello').not.toBeTypeOf('number')
})

Assertions sur les exceptions

Pour tester qu’une fonction lève une exception :

test('exceptions', () => {
  // Vérifier qu'une fonction lève une exception
  expect(() => {
    throw new Error('Something went wrong')
  }).toThrow()

  // Vérifier le message d'erreur
  expect(() => {
    throw new Error('Specific message')
  }).toThrow('Specific message')

  // Vérifier le type d'erreur
  expect(() => {
    throw new TypeError('Type error message')
  }).toThrow(TypeError)
})

Assertions asynchrones

Pour tester du code asynchrone, utilisez des fonctions asynchrones :

test('async/await', async () => {
  const data = await fetchData() // fonction asynchrone
  expect(data).toBeDefined()
})

test('promesses', () => {
  return expect(Promise.resolve('success')).resolves.toBe('success')
})

test('rejets de promesses', () => {
  return expect(Promise.reject(new Error('failure'))).rejects.toThrow('failure')
})

Assertions sur les instantanés (snapshots)

Les instantanés permettent de capturer la sortie d’une fonction et de la comparer avec des exécutions futures :

test('snapshot', () => {
  const user = {
    name: 'John Doe',
    age: 30,
    createdAt: new Date()
  }

  // Exclure certains champs du snapshot
  expect(user).toMatchSnapshot({
    createdAt: expect.any(Date)
  })
})

Assertions personnalisées

Vous pouvez créer vos propres assertions :

import { expect, test } from 'vitest'

// Étendre l'API des assertions
expect.extend({
  toBeEven(received) {
    const pass = received % 2 === 0
    return {
      pass,
      message: () => `expected ${received} to be an even number`,
    }
  },
})

test('nombre pair', () => {
  expect(4).toBeEven()
  expect(3).not.toBeEven()
})

Utilisation de expect.any et expect.objectContaining

Pour des comparaisons plus flexibles :

test('comparaisons avancées', () => {
  // Vérifier le type sans se soucier de la valeur exacte
  expect({ name: 'John', age: 30 }).toEqual({
    name: 'John',
    age: expect.any(Number)
  })

  // Vérifier qu'un objet contient certaines propriétés
  expect({ name: 'John', age: 30, city: 'Paris' }).toEqual(
    expect.objectContaining({
      name: 'John',
      age: 30
    })
  )

  // Vérifier qu'un tableau contient certains éléments
  expect([1, 2, 3, 4]).toEqual(
    expect.arrayContaining([2, 3])
  )
})

En maîtrisant ces assertions, vous pourrez écrire des tests robustes qui vérifient précisément le comportement de votre code dans différentes situations.