Capturas instantáneas

Aprende sobre las Capturas instantáneas a través de este video de Vue School

Las pruebas de capturas instantáneas son una herramienta muy útil para asegurar que la salida de tus funciones no cambie inesperadamente.

Cuando se utilizan capturas instantáneas, Vitest toma una captura del valor dado y la compara con un archivo de captura de referencia almacenado junto con la prueba. La prueba fallará si las dos capturas no coinciden: ya sea porque el cambio es inesperado o porque la captura de referencia debe actualizarse a la nueva versión del resultado.

Usar Capturas instantáneas

Para crear una captura instantánea de un valor, puedes usar toMatchSnapshot() de la API expect():

function toUpperCase(str: string) {
  return str;
}
// ---cut---
import { expect, it } from 'vitest';

it('toUpperCase', () => {
  const result = toUpperCase('foobar');
  expect(result).toMatchSnapshot();
});

La primera vez que se ejecuta esta prueba, Vitest crea un archivo de captura con un contenido similar a este:

// Vitest Snapshot v1, https://www.getbook.com/es/book/vitest-1/guide/snapshot

exports['toUpperCase 1'] = '"FOOBAR"';

El archivo de la captura instantánea debe guardarse junto con los cambios de código y revisarse como parte de tu proceso de revisión de código. En las ejecuciones de prueba posteriores, Vitest comparará la salida generada con la captura instantánea anterior. Si coinciden, la prueba pasará. Si no coinciden, el ejecutor de pruebas ha encontrado un error en tu código que debe corregirse, o la implementación ha cambiado y la captura debe actualizarse.

WARNING

Cuando uses Capturas instantáneas con pruebas concurrentes asíncronas, debes usar expect del Contexto de Prueba local para asegurar que se detecte la prueba correcta.

Capturas en línea (Inline Snapshots)

De manera similar, puedes usar toMatchInlineSnapshot() para almacenar la captura directamente dentro del archivo de prueba.

function toUpperCase(str: string) {
  return str;
}
// ---cut---
import { expect, it } from 'vitest';

it('toUpperCase', () => {
  const result = toUpperCase('foobar');
  expect(result).toMatchInlineSnapshot();
});

En lugar de crear un archivo de captura, Vitest modificará el archivo de prueba directamente para actualizar la captura como una cadena:

function toUpperCase(str: string) {
  return str;
}
// ---cut---
import { expect, it } from 'vitest';

it('toUpperCase', () => {
  const result = toUpperCase('foobar');
  expect(result).toMatchInlineSnapshot('"FOOBAR"');
});

Esto te permite ver la salida esperada directamente sin tener que alternar entre diferentes archivos.

WARNING

Cuando uses Capturas instantáneas con pruebas concurrentes asíncronas, debes usar expect del Contexto de Prueba local para asegurar que se detecte la prueba correcta.

Actualizar Capturas instantáneas

Cuando el valor recibido no coincide con la captura, la prueba falla y se muestra la diferencia entre ambos. Cuando el cambio en la captura es esperado, es posible que desees actualizar la captura a su estado actual.

En el modo de observación (watch mode), puedes presionar la tecla u en la terminal para actualizar la captura fallida directamente.

O puedes usar el flag --update o -u en la CLI para indicar a Vitest que actualice las capturas.

vitest -u

Capturas de Archivo (File Snapshots)

Cuando se llama a toMatchSnapshot(), almacenamos todas las capturas en un archivo de instantáneas formateado. Esto implica que necesitamos escapar algunos caracteres (específicamente, las comillas dobles " y el backtick ```) en la cadena de la captura. Sin embargo, esto podría provocar la pérdida del resaltado de sintaxis para el contenido de la captura (si está en algún lenguaje).

Para mejorar esta situación, presentamos toMatchFileSnapshot() para crear capturas explícitamente en un archivo. Esto te permite asignar cualquier extensión de archivo a la captura, haciéndolas más legibles.

import { expect, it } from 'vitest';

it('render basic', async () => {
  const result = renderHTML(h('div', { class: 'foo' }));
  await expect(result).toMatchFileSnapshot('./test/basic.output.html');
});

Se comparará con el contenido de ./test/basic.output.html. Y se puede reescribir con el flag --update.

Capturas de Imagen (Image Snapshots)

También es posible crear capturas de imágenes usando jest-image-snapshot.

npm i -D jest-image-snapshot

test('image snapshot', () => {
  expect(readFileSync('./test/stubs/input-image.png')).toMatchImageSnapshot();
});

Puedes obtener más información en el ejemplo examples/image-snapshot.

Serializador Personalizado (Custom Serializer)

Puedes agregar tu propia lógica para alterar cómo se serializan tus capturas. Al igual que Jest, Vitest tiene serializadores predeterminados para tipos de JavaScript incorporados, elementos HTML, ImmutableJS y elementos React.

Puede agregar explícitamente un serializador personalizado mediante la API expect.addSnapshotSerializer.

expect.addSnapshotSerializer({
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` es una función que serializa un valor utilizando complementos existentes.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
});

También admitimos la opción snapshotSerializers para agregar implícitamente serializadores personalizados.

import { SnapshotSerializer } from 'vitest';

export default {
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` es una función que serializa un valor utilizando complementos existentes.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
} satisfies SnapshotSerializer;

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    snapshotSerializers: ['path/to/custom-serializer.ts'],
  },
});

Después de agregar una prueba como esta:

test('foo snapshot test', () => {
  const bar = {
    foo: {
      x: 1,
      y: 2,
    },
  };

  expect(bar).toMatchSnapshot();
});

Obtendrás la siguiente captura:

Pretty foo: Object {
  "x": 1,
  "y": 2,
}

Estamos usando pretty-format de Jest para serializar capturas. Puedes leer más al respecto aquí: pretty-format.

Diferencia con Jest

Vitest proporciona una característica de Capturas instantáneas casi compatible con Jest con algunas excepciones:

1. El encabezado del comentario en el archivo de captura es diferente {#_1-comment-header-in-the-snapshot-file-is-different}

- // Jest Snapshot v1, https://goo.gl/fbAQLP
+ // Vitest Snapshot v1, https://www.getbook.com/es/book/vitest-1/guide/snapshot

Esto no afecta realmente la funcionalidad, pero podría afectar el diff de tu commit al migrar desde Jest.

2. printBasicPrototype está predeterminado en false {#_2-printbasicprototype-is-default-to-false}

Tanto las capturas de Jest como las de Vitest están impulsadas por pretty-format. En Vitest, establecemos printBasicPrototype predeterminado en false para proporcionar una salida de captura más limpia, mientras que en Jest <29.0.0 es true de forma predeterminada.

import { expect, test } from 'vitest';

test('snapshot', () => {
  const bar = [
    {
      foo: 'bar',
    },
  ];

  // en Jest
  expect(bar).toMatchInlineSnapshot(`
    Array [
      Object {
        "foo": "bar",
      },
    ]
  `);

  // en Vitest
  expect(bar).toMatchInlineSnapshot(`
    [
      {
        "foo": "bar",
      },
    ]
  `);
});

Consideramos que este es un valor predeterminado más razonable para la legibilidad y la experiencia del desarrollador en general. Si aún prefieres el comportamiento de Jest, puedes cambiar tu configuración:

// vitest.config.js
export default defineConfig({
  test: {
    snapshotFormat: {
      printBasicPrototype: true,
    },
  },
});

3. El símbolo > se usa como separador en lugar de dos puntos : para mensajes personalizados {#_3-chevron-is-used-as-a-separator-instead-of-colon-for-custom-messages}

Vitest usa el símbolo > como separador en lugar de dos puntos : para mejorar la legibilidad, cuando se pasa un mensaje personalizado durante la creación de un archivo de captura.

Para el siguiente código de prueba de ejemplo:

test('toThrowErrorMatchingSnapshot', () => {
  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingSnapshot('hint');
});

En Jest, la captura será:

exports[`toThrowErrorMatchingSnapshot: hint 1`] = `"error"`;

En Vitest, la instantánea equivalente será:

exports[`toThrowErrorMatchingSnapshot > hint 1`] = `[Error: error]`;

4. La instantánea Error predeterminada es diferente para toThrowErrorMatchingSnapshot y toThrowErrorMatchingInlineSnapshot {#_4-default-error-snapshot-is-different-for-tothrowerrormatchingsnapshot-and-tothrowerrormatchinginlinesnapshot}

import { expect, test } from 'vitest';
// ---cut---
test('snapshot', () => {
  //
  // in Jest
  //

  expect(new Error('error')).toMatchInlineSnapshot(`[Error: error]`);

  // Jest toma una instantánea de `Error.message` para la instancia `Error`
  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingInlineSnapshot(`"error"`);

  //
  // in Vitest
  //

  expect(new Error('error')).toMatchInlineSnapshot(`[Error: error]`);

  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingInlineSnapshot(`[Error: error]`);
});