Snapshot

Lerne Snapshots mit einem Video von Vue School

Snapshot-Tests sind ein äußerst nützliches Werkzeug, um sicherzustellen, dass sich die Ausgabe deiner Funktionen nicht unerwartet ändert.

Bei der Verwendung von Snapshots erstellt Vitest einen Snapshot des gegebenen Wertes und vergleicht ihn dann mit einer Referenz-Snapshot-Datei, die neben dem Test gespeichert ist. Der Test schlägt fehl, wenn die Snapshots nicht übereinstimmen: Entweder ist die Änderung unerwartet, oder der Referenz-Snapshot muss auf die neue Version des Ergebnisses aktualisiert werden.

Snapshots verwenden

Um einen Snapshot eines Wertes zu erstellen, kannst du toMatchSnapshot() aus der expect()-API verwenden:

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

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

Beim ersten Ausführen dieses Tests erstellt Vitest eine Snapshot-Datei mit folgendem Inhalt:

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

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

Das Snapshot-Artefakt sollte zusammen mit den Codeänderungen übertragen und im Rahmen der Codeüberprüfung geprüft werden. Bei nachfolgenden Testläufen vergleicht Vitest die gerenderte Ausgabe mit dem vorherigen Snapshot. Wenn sie übereinstimmen, besteht der Test. Wenn sie nicht übereinstimmen, hat der Testrunner möglicherweise einen Fehler in deinem Code gefunden, der behoben werden sollte, oder die Implementierung hat sich geändert und der Snapshot muss aktualisiert werden.

WARNING

Bei der Verwendung von Snapshots mit asynchronen, gleichzeitigen Tests muss expect aus dem lokalen Testkontext verwendet werden, um sicherzustellen, dass der richtige Test erkannt wird.

Inline-Snapshots

Alternativ kannst du toMatchInlineSnapshot() verwenden, um den Snapshot direkt in der Testdatei zu speichern.

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

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

Statt eine Snapshot-Datei zu erstellen, ändert Vitest die Testdatei direkt, um den Snapshot zu aktualisieren:

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

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

So kannst du die erwartete Ausgabe direkt sehen, ohne zwischen verschiedenen Dateien hin- und herzuspringen.

WARNING

Bei der Verwendung von Snapshots mit asynchronen, gleichzeitigen Tests muss expect aus dem lokalen Testkontext verwendet werden, um sicherzustellen, dass der richtige Test erkannt wird.

Snapshots aktualisieren

Wenn der empfangene Wert nicht mit dem Snapshot übereinstimmt, schlägt der Test fehl und zeigt dir den Unterschied zwischen den Werten. Wenn die Änderung des Snapshots erwartet wird, solltest du den Snapshot aktualisieren.

Im Watch-Modus kannst du die Taste u im Terminal drücken, um den fehlgeschlagenen Snapshot direkt zu aktualisieren.

Alternativ kannst du das Flag --update oder -u in der CLI verwenden, um Vitest anzuweisen, Snapshots zu aktualisieren.

bash

vitest -u

Datei-Snapshots

Beim Aufruf von toMatchSnapshot() werden alle Snapshots in einer formatierten SNAP-Datei gespeichert. Dies bedeutet, dass bestimmte Zeichen (insbesondere das doppelte Anführungszeichen " und Backtick ```) in der Snapshot-Zeichenkette maskiert werden müssen. Zudem kann möglicherweise die Syntaxhervorhebung für den Snapshot-Inhalt verloren gehen (wenn er in einer bestimmten Sprache vorliegt).

Um dies zu verbessern, führen wir toMatchFileSnapshot() ein. Dies ermöglicht es dir, der Snapshot-Datei eine beliebige Dateiendung zuzuweisen und sie dadurch lesbarer zu machen.

import { expect, it } from 'vitest';

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

Der Test vergleicht das Ergebnis mit dem Inhalt von ./test/basic.output.html. Die Datei kann mit dem Flag --update zurückgeschrieben werden.

Bild-Snapshots

Es ist ebenfalls möglich, Bilder mit jest-image-snapshot als Snapshot zu speichern.

bash

npm i -D jest-image-snapshot

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

Weitere Informationen findest du im Beispiel examples/image-snapshot.

Benutzerdefinierte Serialisierer

Du kannst eigene Logik hinzufügen, um zu ändern, wie deine Snapshots serialisiert werden. Wie Jest verfügt Vitest über Standard-Serialisierer für integrierte JavaScript-Typen, HTML-Elemente, ImmutableJS und für React-Elemente.

Sie können explizit einen benutzerdefinierten Serialisierer hinzufügen, indem Sie die expect.addSnapshotSerializer API verwenden.

expect.addSnapshotSerializer({
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` ist eine Funktion, die einen Wert mithilfe vorhandener Plugins serialisiert.
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },
  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
});

Wir unterstützen auch die Option snapshotSerializers, um benutzerdefinierte Serialisierer implizit hinzuzufügen.

import { SnapshotSerializer } from 'vitest';

export default {
  serialize(val, config, indentation, depth, refs, printer) {
    // `printer` ist eine Funktion, die einen Wert mithilfe vorhandener Plugins serialisiert.
    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'],
  },
});

Nach dem Hinzufügen eines Tests wie diesem:

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

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

Erhältst du folgenden Snapshot:

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

Zum Serialisieren von Snapshots verwenden wir Jests pretty-format. Weitere Informationen dazu findest du hier: pretty-format.

Unterschied zu Jest

Vitest bietet eine nahezu kompatible Snapshot-Funktion mit Jest mit einigen Ausnahmen:

1. Kommentar-Header in der Snapshot-Datei ist unterschiedlich {#_1-comment-header-in-the-snapshot-file-is-different}

diff

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

Dies hat keine Auswirkungen auf die Funktionalität, kann sich aber auf die Commit-Historie auswirken, wenn von Jest migriert wird.

2. `printBasicPrototype` ist standardmäßig auf `false` gesetzt {#_2-printbasicprototype-is-default-to-false}

Sowohl die Snapshots von Jest als auch die von Vitest werden von pretty-format unterstützt. In Vitest setzen wir printBasicPrototype standardmäßig auf false, um eine sauberere Snapshot-Ausgabe zu erzielen, während es in Jest <29.0.0 standardmäßig true ist.

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

Wir halten dies für einen vernünftigeren Standard für die Lesbarkeit und die gesamte Entwicklererfahrung. Wenn du das Verhalten von Jest bevorzugst, kannst du deine Konfiguration ändern:

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

3. Chevron `>` wird als Trennzeichen anstelle von Doppelpunkt `:` für benutzerdefinierte Nachrichten verwendet {#_3-chevron-is-used-as-a-separator-instead-of-colon-for-custom-messages}

Vitest verwendet zur besseren Lesbarkeit Chevron > anstelle von Doppelpunkt : als Trennzeichen, wenn beim Erstellen einer Snapshot-Datei eine benutzerdefinierte Meldung übergeben wird.

Für folgenden Beispiel-Testcode:

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

In Jest sieht der Snapshot wie folgt aus:

console

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

In Vitest sieht der entsprechende Snapshot so aus:

console

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

4. Der Standard-`Error`-Snapshot unterscheidet sich für `toThrowErrorMatchingSnapshot` und `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 erstellt einen Snapshot von `Error.message` für `Error`-Instanzen
  expect(() => {
    throw new Error('error');
  }).toThrowErrorMatchingInlineSnapshot(`"error"`);

  //
  // in Vitest
  //

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

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

Snapshot ​

Snapshots verwenden ​

Inline-Snapshots ​

Snapshots aktualisieren ​

Datei-Snapshots ​

Bild-Snapshots ​

Benutzerdefinierte Serialisierer ​

Unterschied zu Jest ​

1. Kommentar-Header in der Snapshot-Datei ist unterschiedlich {#_1-comment-header-in-the-snapshot-file-is-different} ​

2. printBasicPrototype ist standardmäßig auf false gesetzt {#_2-printbasicprototype-is-default-to-false} ​

3. Chevron > wird als Trennzeichen anstelle von Doppelpunkt : für benutzerdefinierte Nachrichten verwendet {#_3-chevron-is-used-as-a-separator-instead-of-colon-for-custom-messages} ​

4. Der Standard-Error-Snapshot unterscheidet sich für toThrowErrorMatchingSnapshot und toThrowErrorMatchingInlineSnapshot {#_4-default-error-snapshot-is-different-for-tothrowerrormatchingsnapshot-and-tothrowerrormatchinginlinesnapshot} ​