Instantáneas

Aprende sobre Instantáneas en video con Vue School

Las pruebas de instantáneas son una herramienta muy útil cuando se desea asegurar que la salida de las funciones no cambie inesperadamente.

Al utilizar instantáneas, Vitest captura el valor proporcionado y lo compara con un archivo de instantánea de referencia almacenado junto a la prueba. La prueba fallará si las dos instantáneas no coinciden. Esto puede deberse a un cambio inesperado o a que la instantánea de referencia necesita ser actualizada para reflejar la nueva versión del resultado.

Usar Instantáneas

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

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 instantánea con el siguiente contenido:

// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html

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

El artefacto de la instantánea debe ser confirmado junto con los cambios de código y revisado como parte de tu proceso de revisión de código. En ejecuciones de prueba posteriores, Vitest comparará la salida renderizada con la instantánea previamente guardada. Si coinciden, la prueba pasará. Si no coinciden, significa que el ejecutor de pruebas detectó un error en tu código que debe ser corregido, o que la implementación ha cambiado y la instantánea necesita ser actualizada.

WARNING

Al usar Instantáneas con pruebas asíncronas concurrentes, se debe utilizar expect del Contexto de Prueba local para asegurar que la instantánea correcta sea asociada a la prueba.

Instantáneas en Línea

También puedes usar toMatchInlineSnapshot() para almacenar la instantánea directamente en el archivo de prueba.

import { expect, it } from 'vitest';

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

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

import { expect, it } from 'vitest';

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

Esto te permite ver la salida esperada directamente, sin necesidad de navegar entre diferentes archivos.

WARNING

Al usar Instantáneas con pruebas asíncronas concurrentes, se debe utilizar expect del Contexto de Prueba local para asegurar que la instantánea correcta sea asociada a la prueba.

Actualizar Instantáneas

Cuando el valor recibido no coincide con la instantánea, la prueba falla y muestra la diferencia entre ambos. Si el cambio en la instantánea es esperado, es posible que desees actualizarla al estado actual.

En el modo de observación, puedes presionar u en la terminal para actualizar directamente la instantánea fallida.

Alternativamente, puedes usar la opción --update o -u en la CLI para que Vitest actualice las instantáneas.

vitest -u

Instantáneas de Archivos

Al llamar a toMatchSnapshot(), todas las instantáneas se almacenan en un archivo de instantáneas formateado. Esto implica que debemos escapar ciertos caracteres, como las comillas dobles " y los backticks `, dentro de la cadena de la instantánea. Además, podrías perder el resaltado de sintaxis para el contenido de la instantánea (si está en algún idioma específico).

Por esta razón, introdujimos toMatchFileSnapshot() para validar explícitamente contra un archivo. Esto te permite asignar cualquier extensión de archivo a la instantánea, mejorando su legibilidad.

import { expect, it } from 'vitest';

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

Esto comparará el resultado con el contenido de ./test/basic.output.html. Y puede ser actualizado con la opción --update.

Instantáneas de Imágenes

También es posible crear instantáneas de imágenes utilizando jest-image-snapshot.

npm i -D jest-image-snapshot

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

Serializador Personalizado

Puedes añadir tu propia lógica para modificar la serialización de tus instantáneas. Al igual que Jest, Vitest tiene serializadores predeterminados para tipos de JavaScript incorporados, elementos HTML, ImmutableJS y elementos React.

Puedes añadir 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 usando plugins existentes.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
});

También se soporta la opción snapshotSerializers para añadir serializadores personalizados de forma implícita.

import { SnapshotSerializer } from 'vitest';

export default {
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` es una función que serializa un valor usando plugins 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 'vitest/config';

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

Después de añadir una prueba como esta:

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

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

Obtendrás la siguiente instantánea:

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

Estamos utilizando pretty-format de Jest para serializar instantáneas. Puedes leer más sobre ello aquí: pretty-format.

Diferencia con Jest

Vitest proporciona una característica de Instantáneas casi compatible con la de Jest, con algunas excepciones:

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

- // Jest Snapshot v1, https://goo.gl/fbAQLP
+ // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html

Esto no afecta la funcionalidad, pero podría generar diferencias en tu commit al migrar desde Jest.

2. printBasicPrototype es false por defecto {#_2-printbasicprototype-is-default-to-false}

Tanto las instantáneas de Jest como las de Vitest son generadas por pretty-format. En Vitest, establecemos printBasicPrototype en false por defecto para proporcionar una salida de instantánea más limpia, mientras que en Jest <29.0.0 es true por defecto.

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",
      },
    ]
  `);
});

Creemos que este es un valor predeterminado más razonable para la legibilidad y la experiencia de desarrollo (DX) general. Si aún prefieres el comportamiento de Jest, puedes cambiar tu configuración:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    snapshotFormat: {
      printBasicPrototype: true,
    },
  },
});

3. El símbolo de mayor que > 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 de mayor que > como separador en lugar de dos puntos : para mayor legibilidad, cuando se pasa un mensaje personalizado durante la creación de un archivo de instantánea.

Para el siguiente código de prueba de ejemplo:

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

En Jest, la instantánea será:

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

En Vitest, la instantánea equivalente será:

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

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

import { expect, test } from 'vitest'

test('snapshot', () => {
  // en Jest y Vitest
  expect(new Error('error')).toMatchInlineSnapshot(`[Error: error]`)

  // Jest serializa `Error.message` para la instancia de `Error`
  // Vitest muestra el mismo valor que toMatchInlineSnapshot
  expect(() => {
    throw new Error('error')
  }).toThrowErrorMatchingInlineSnapshot(`"error"`) 
  }).toThrowErrorMatchingInlineSnapshot(`[Error: error]`) 
})