Snímky

Naučte se o snímcích prostřednictvím videa z Vue School

Snímkové testy jsou velmi užitečným nástrojem, kdykoli chcete zajistit, že se výstup vašich funkcí neočekávaně nezmění.

Při použití snímků Vitest pořídí snímek dané hodnoty a poté jej porovná s referenčním souborem snímků uloženým vedle testu. Test selže, pokud se snímky neshodují: buď je změna neočekávaná, nebo je třeba referenční snímek aktualizovat na novou verzi výsledku.

Použití snímků

Pro pořízení snímku hodnoty můžete použít toMatchSnapshot() z API expect():

import { expect, it } from 'vitest';

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

Při prvním spuštění tohoto testu Vitest vytvoří soubor snímku, který vypadá takto:

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

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

Soubor se snímkem by měl být odevzdán spolu se změnami kódu a zkontrolován jako součást vašeho procesu revize kódu. Při následných spuštěních testů Vitest porovná výstup s předchozím snímkem. Pokud se shodují, test bude úspěšný. Pokud se neshodují, buď testovací nástroj našel chybu ve vašem kódu, kterou je třeba opravit, nebo se implementace změnila a snímek je třeba aktualizovat.

WARNING

Při použití snímků v asynchronních souběžných testech je nutné použít expect z lokálního Testovacího kontextu, aby bylo zajištěno, že je detekován správný test.

Inline snímky

Podobně můžete použít toMatchInlineSnapshot() k uložení snímku přímo v testovacím souboru.

import { expect, it } from 'vitest';

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

Místo vytváření souboru snímku Vitest přímo upraví testovací soubor, aby aktualizoval snímek jako řetězec:

import { expect, it } from 'vitest';

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

To vám umožní přímo vidět očekávaný výstup, aniž byste museli přeskakovat mezi různými soubory.

WARNING

Při použití snímků v asynchronních souběžných testech je nutné použít expect z lokálního Testovacího kontextu, aby bylo zajištěno, že je detekován správný test.

Aktualizace snímků

Když se přijatá hodnota neshoduje se snímkem, test selže a ukáže vám rozdíl mezi nimi. Když je změna snímku očekávaná, můžete snímek aktualizovat na aktuální stav.

V režimu sledování můžete v terminálu stisknout klávesu u pro přímou aktualizaci selhaného snímku.

Nebo můžete použít přepínač --update nebo -u v CLI, aby Vitest aktualizoval snímky.

vitest -u

Souborové snímky

Při volání toMatchSnapshot() ukládáme všechny snímky do formátovaného souboru .snap. To znamená, že musíme escapovat některé znaky (konkrétně dvojité uvozovky " a zpětný apostrof `) v řetězci snímku. Mezitím můžete ztratit zvýraznění syntaxe pro obsah snímku (pokud jsou v nějakém jazyce).

S ohledem na to jsme zavedli toMatchFileSnapshot() pro explicitní porovnání se souborem. To vám umožňuje přiřadit souboru snímku libovolnou příponu a činí je čitelnějšími.

import { expect, it } from 'vitest';

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

Porovná obsah s ./test/basic.output.html. A lze jej zapsat zpět s přepínačem --update.

Snímky obrázků

Je také možné pořizovat snímky obrázků pomocí jest-image-snapshot.

npm i -D jest-image-snapshot

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

Vlastní serializátor

Můžete přidat vlastní logiku pro úpravu způsobu, jakým jsou vaše snímky serializovány. Stejně jako Jest, Vitest má výchozí serializátory pro vestavěné typy JavaScriptu, HTML prvky, ImmutableJS a React prvky.

Můžete explicitně přidat vlastní serializátor pomocí API expect.addSnapshotSerializer.

expect.addSnapshotSerializer({
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` je funkce, která serializuje hodnotu pomocí existujících pluginů.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
});

Podporujeme také možnost snapshotSerializers pro implicitní přidání vlastních serializátorů.

import { SnapshotSerializer } from 'vitest';

export default {
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` je funkce, která serializuje hodnotu pomocí existujících pluginů.
    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'],
  },
});

Po přidání testu jako je tento:

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

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

Obdržíte následující snímek:

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

Pro serializaci snímků využíváme Jestův pretty-format. Více si o tom můžete přečíst zde: pretty-format.

Rozdíly oproti Jestu

Vitest poskytuje téměř kompatibilní funkci snímků s Jestem s několika výjimkami:

1. Hlavička komentáře v souboru snímku je odlišná

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

To ve skutečnosti neovlivňuje funkčnost, ale může ovlivnit váš commit diff při migraci z Jestu.

2. printBasicPrototype je ve výchozím nastavení false

Snímky Jestu i Vitestu jsou poháněny pretty-format. Ve Vitestu nastavujeme printBasicPrototype ve výchozím nastavení na false, abychom poskytli čistší výstup snímku, zatímco v Jestu <29.0.0 je ve výchozím nastavení true.

import { expect, test } from 'vitest';

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

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

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

Toto považujeme za rozumnější výchozí nastavení pro čitelnost a celkovou DX. Pokud stále preferujete chování Jestu, můžete změnit svou konfiguraci:

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

3. Znak > je použit jako oddělovač místo dvojtečky : pro vlastní zprávy

Vitest používá znak > jako oddělovač místo dvojtečky : pro lepší čitelnost, když je při vytváření souboru snímku předána vlastní zpráva.

Pro následující ukázku testovacího kódu:

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

V Jestu bude snímek:

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

Ve Vitestu bude ekvivalentní snímek:

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

4. Výchozí snímek Error je odlišný pro toThrowErrorMatchingSnapshot a toThrowErrorMatchingInlineSnapshot

import { expect, test } from 'vitest';

test('snapshot', () => {
  // v Jestu a Vitestu
  expect(new Error('error')).toMatchInlineSnapshot(`[Error: error]`);

  // Jest vytváří snímek `Error.message` pro instanci `Error`
  // Vitest tiskne stejnou hodnotu jako toMatchInlineSnapshot
  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingInlineSnapshot(`"error"`); 
  }).toThrowErrorMatchingInlineSnapshot(`[Error: error]`); 
});