Pillanatképek

Tanulj a pillanatképekről videóval a Vue School-on

A pillanatkép-tesztek rendkívül hasznosak annak biztosítására, hogy a függvényeid kimenete ne változzon váratlanul.

Pillanatkép készítésekor a Vitest rögzíti a megadott érték pillanatképét, majd összehasonlítja azt egy referencia pillanatkép fájllal, amely a teszt mellett található. A teszt akkor bukik el, ha a két pillanatkép nem egyezik: ez vagy váratlan változást jelez, vagy a referencia pillanatképet kell frissíteni.

Pillanatképek használata

Egy érték pillanatképének elkészítéséhez használd az toMatchSnapshot() függvényt az expect() API-ból:

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

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

A teszt első futtatásakor a Vitest létrehoz egy pillanatkép fájlt, amely valahogy így néz ki:

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

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

A pillanatkép fájlt a kódváltoztatásokkal együtt kell commitálni, és a kódellenőrzési folyamat részeként ellenőrizni kell. A későbbi tesztfuttatások során a Vitest összehasonlítja a generált kimenetet az előző pillanatképpel. Ha egyeznek, a teszt sikeres lesz. Ha nem egyeznek, akkor vagy a teszt futtató hibát talált a kódodban, amelyet ki kell javítani, vagy a megvalósítás megváltozott, és a pillanatképet frissíteni kell.

WARNING

Aszinkron, párhuzamos tesztek esetén a helyi Teszt Környezetből származó expect használata szükséges a megfelelő teszt azonosításához.

Beágyazott pillanatképek

Hasonlóképpen, használhatod a toMatchInlineSnapshot() függvényt a pillanatkép tárolására közvetlenül a tesztfájlban.

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

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

Ahelyett, hogy külön pillanatkép fájlt hozna létre, a Vitest közvetlenül módosítja a tesztfájlt a pillanatkép frissítésével.

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

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

Ez lehetővé teszi, hogy azonnal lásd a várt eredményt anélkül, hogy különböző fájlok között kellene navigálnod.

WARNING

Aszinkron, párhuzamos tesztek esetén a helyi Teszt Környezetből származó expect használata szükséges a megfelelő teszt azonosításához.

Pillanatképek frissítése

Ha a kapott érték nem egyezik a pillanatképpel, a teszt sikertelen lesz, és megjeleníti a különbséget a kettő között. Ha a pillanatkép változása várható, akkor frissítsd a pillanatképet a jelenlegi állapotra.

Figyelő módban nyomd meg az u billentyűt a terminálban a sikertelen pillanatképek azonnali frissítéséhez.

Vagy használd a --update vagy -u flag-et a CLI-ben, hogy a Vitest frissítse a pillanatképeket.

vitest -u

Fájl-pillanatképek

A toMatchSnapshot() hívásakor az összes pillanatképet egy formázott pillanatkép fájlban tároljuk. Ez azt jelenti, hogy a pillanatkép karakterláncban néhány karaktert (például a dupla idézőjelet (") és a backtick-et (`)) kódolnunk kell. Emellett elveszítheted a szintaxiskiemelést a pillanatkép tartalmához (ha az valamilyen nyelven van).

Ennek javítására bevezetjük a toMatchFileSnapshot() függvényt, amely lehetővé teszi a pillanatképek fájlba mentését. Ez lehetővé teszi, hogy bármilyen fájlkiterjesztést hozzárendelj a pillanatkép fájlhoz, és olvashatóbbá tegye azokat.

import { expect, it } from 'vitest';

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

Ez összehasonlítja az eredményt a ./test/basic.output.html tartalmával. A --update kapcsolóval frissítheted a fájlt.

Kép-pillanatképek

Képekről is készíthetsz pillanatképeket a jest-image-snapshot használatával.

npm i -D jest-image-snapshot

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

További információt a examples/image-snapshot példában találsz.

Egyéni szerializálók

Hozzáadhatod a saját logikádat a pillanatképek szerializálásának módosításához. A Jesthez hasonlóan a Vitest is rendelkezik alapértelmezett szerializálókkal a beépített JavaScript típusokhoz, HTML elemekhez, ImmutableJS-hez és React komponensekhez.

Explicit módon hozzáadhat egyéni szerializálót az expect.addSnapshotSerializer API használatával.

expect.addSnapshotSerializer({
  serialize(val, config, indentation, depth, refs, printer) {
    // A `printer` egy olyan függvény, amely a meglévő beépülő modulok használatával szerializál egy értéket.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
});

Támogatjuk a snapshotSerializers opciót is az egyéni szerializálók implicit hozzáadásához.

import { SnapshotSerializer } from 'vitest';

export default {
  serialize(val, config, indentation, depth, refs, printer) {
    // A `printer` egy olyan függvény, amely a meglévő beépülő modulok használatával szerializál egy értéket.
    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'],
  },
});

Miután hozzáadtál egy ilyen tesztet:

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

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

A következő pillanatképet kapod:

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

A Jest pretty-format csomagját használjuk a pillanatképek szerializálásához. További információt itt olvashatsz róla: pretty-format.

Különbségek a Jesthez képest

A Vitest szinte teljesen kompatibilis pillanatkép funkciót biztosít a Jest funkciójával, néhány kivétellel:

1. A megjegyzés fejléc a pillanatkép fájlban eltérő {#_1-comment-header-in-the-snapshot-file-is-different}

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

Ez nem befolyásolja a működést, de befolyásolhatja a commitok közötti különbségeket a Jest-ről való átállás során.

2. A printBasicPrototype alapértelmezett értéke false {#_2-printbasicprototype-is-default-to-false}

Mind a Jest, mind a Vitest pillanatképeit a pretty-format hajtja. A Vitestben a printBasicPrototype alapértelmezett értékét false-ra állítottuk a tisztább pillanatkép kimenet érdekében, míg a Jest <29.0.0 verziójában alapértelmezés szerint true volt.

import { expect, test } from 'vitest';

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

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

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

Úgy véljük, hogy ez jobb alapértelmezés az olvashatóság és az általános fejlesztői élmény szempontjából. Ha továbbra is a Jest viselkedését szeretnéd, módosíthatod a konfigurációdat:

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

3. A Chevron > szimbólumot használjuk elválasztóként a kettőspont : helyett az egyéni üzenetekhez {#_3-chevron-is-used-as-a-separator-instead-of-colon-for-custom-messages}

A Vitest az olvashatóság érdekében a kettőspont (😃 helyett a > szimbólumot használja elválasztóként, amikor egyéni üzenetet adunk meg a pillanatkép fájl létrehozásakor.

A következő példa tesztkódhoz:

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

A Jestben a pillanatkép a következő lesz:

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

A Vitestben a megfelelő pillanatkép a következő lesz:

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

4. A toThrowErrorMatchingSnapshot és a toThrowErrorMatchingInlineSnapshot esetén eltérő az alapértelmezett Error pillanatkép {#_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]`);

  // A Jest az `Error.message`-et pillanatképezi az `Error` példányhoz
  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingInlineSnapshot(`"error"`);

  //
  // in Vitest
  //

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

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