Test-Runner

[Historie]

Version	Änderungen
v20.0.0	Der Test-Runner ist jetzt stabil.
v18.0.0, v16.17.0	Hinzugefügt in: v18.0.0, v16.17.0

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/test.js

Das Modul node:test erleichtert die Erstellung von JavaScript-Tests. Um darauf zuzugreifen:

ESM

import test from 'node:test'

CJS

const test = require('node:test')

Dieses Modul ist nur unter dem Schema node: verfügbar.

Über das Modul test erstellte Tests bestehen aus einer einzelnen Funktion, die auf eine von drei Arten verarbeitet wird:

Das folgende Beispiel veranschaulicht, wie Tests mit dem Modul test geschrieben werden.

test('synchroner bestandener Test', t => {
  // Dieser Test besteht, weil er keine Ausnahme auslöst.
  assert.strictEqual(1, 1)
})

test('synchroner fehlgeschlagener Test', t => {
  // Dieser Test schlägt fehl, weil er eine Ausnahme auslöst.
  assert.strictEqual(1, 2)
})

test('asynchroner bestandener Test', async t => {
  // Dieser Test besteht, weil das von der asynchronen
  // Funktion zurückgegebene Promise erfüllt und nicht abgelehnt wird.
  assert.strictEqual(1, 1)
})

test('asynchroner fehlgeschlagener Test', async t => {
  // Dieser Test schlägt fehl, weil das von der asynchronen
  // Funktion zurückgegebene Promise abgelehnt wird.
  assert.strictEqual(1, 2)
})

test('fehlgeschlagener Test mit Promises', t => {
  // Promises können auch direkt verwendet werden.
  return new Promise((resolve, reject) => {
    setImmediate(() => {
      reject(new Error('dies wird dazu führen, dass der Test fehlschlägt'))
    })
  })
})

test('Callback-Bestandener Test', (t, done) => {
  // done() ist die Callback-Funktion. Wenn setImmediate() ausgeführt wird, ruft es
  // done() ohne Argumente auf.
  setImmediate(done)
})

test('Callback-Fehlgeschlagener Test', (t, done) => {
  // Wenn setImmediate() ausgeführt wird, wird done() mit einem Error-Objekt aufgerufen und
  // der Test schlägt fehl.
  setImmediate(() => {
    done(new Error('Callback-Fehler'))
  })
})

Wenn Tests fehlschlagen, wird der Exit-Code des Prozesses auf 1 gesetzt.

Untertests

Die test()-Methode des Testkontextes erlaubt die Erstellung von Untertests. Sie ermöglicht es, Ihre Tests hierarchisch zu strukturieren, wobei Sie verschachtelte Tests innerhalb eines größeren Tests erstellen können. Diese Methode verhält sich identisch zur Top-Level-Funktion test(). Das folgende Beispiel demonstriert die Erstellung eines Top-Level-Tests mit zwei Untertests.

test('Top-Level-Test', async t => {
  await t.test('Untertest 1', t => {
    assert.strictEqual(1, 1)
  })

  await t.test('Untertest 2', t => {
    assert.strictEqual(2, 2)
  })
})

In diesem Beispiel wird await verwendet, um sicherzustellen, dass beide Untertests abgeschlossen sind. Dies ist notwendig, da Tests nicht auf den Abschluss ihrer Untertests warten, anders als Tests, die innerhalb von Suiten erstellt wurden. Alle Untertests, die noch ausstehend sind, wenn ihr Elternteil beendet wird, werden abgebrochen und als Fehler behandelt. Alle Fehler in einem Untertest führen dazu, dass der übergeordnete Test fehlschlägt.

Tests überspringen

Einzelne Tests können übersprungen werden, indem die Option skip an den Test übergeben wird oder indem die skip()-Methode des Testkontextes aufgerufen wird, wie im folgenden Beispiel gezeigt.

// Die skip-Option wird verwendet, aber keine Nachricht bereitgestellt.
test('skip-Option', { skip: true }, t => {
  // Dieser Code wird niemals ausgeführt.
})

// Die skip-Option wird verwendet und eine Nachricht wird bereitgestellt.
test('skip-Option mit Nachricht', { skip: 'dies wird übersprungen' }, t => {
  // Dieser Code wird niemals ausgeführt.
})

test('skip()-Methode', t => {
  // Stellen Sie sicher, dass Sie hier ebenfalls zurückkehren, wenn der Test zusätzliche Logik enthält.
  t.skip()
})

test('skip()-Methode mit Nachricht', t => {
  // Stellen Sie sicher, dass Sie hier ebenfalls zurückkehren, wenn der Test zusätzliche Logik enthält.
  t.skip('dies wird übersprungen')
})

TODO-Tests

Einzelne Tests können als fehlerhaft oder unvollständig markiert werden, indem die Option todo an den Test übergeben wird oder indem die todo()-Methode des Testkontextes aufgerufen wird, wie im folgenden Beispiel gezeigt. Diese Tests stellen eine ausstehende Implementierung oder einen Fehler dar, der behoben werden muss. TODO-Tests werden ausgeführt, aber nicht als Testfehler behandelt und beeinflussen daher nicht den Prozess-Exit-Code. Wenn ein Test sowohl als TODO als auch als übersprungen markiert ist, wird die TODO-Option ignoriert.

// Die todo-Option wird verwendet, aber keine Nachricht bereitgestellt.
test('todo-Option', { todo: true }, t => {
  // Dieser Code wird ausgeführt, aber nicht als Fehler behandelt.
  throw new Error('dies schlägt den Test nicht fehl')
})

// Die todo-Option wird verwendet und eine Nachricht wird bereitgestellt.
test('todo-Option mit Nachricht', { todo: 'dies ist ein todo-Test' }, t => {
  // Dieser Code wird ausgeführt.
})

test('todo()-Methode', t => {
  t.todo()
})

test('todo()-Methode mit Nachricht', t => {
  t.todo('dies ist ein todo-Test und wird nicht als Fehler behandelt')
  throw new Error('dies schlägt den Test nicht fehl')
})

describe()- und it()-Aliase

Suites und Tests können auch mit den Funktionen describe() und it() geschrieben werden. describe() ist ein Alias für suite() und it() ist ein Alias für test().

describe('Eine Sache', () => {
  it('sollte funktionieren', () => {
    assert.strictEqual(1, 1)
  })

  it('sollte in Ordnung sein', () => {
    assert.strictEqual(2, 2)
  })

  describe('eine verschachtelte Sache', () => {
    it('sollte funktionieren', () => {
      assert.strictEqual(3, 3)
    })
  })
})

describe() und it() werden aus dem node:test-Modul importiert.

ESM

import { describe, it } from 'node:test'

CJS

const { describe, it } = require('node:test')

only-Tests

Wenn Node.js mit der Befehlszeilenoption --test-only gestartet wird oder die Testisolation deaktiviert ist, ist es möglich, alle Tests bis auf eine ausgewählte Teilmenge zu überspringen, indem die Option only an die Tests übergeben wird, die ausgeführt werden sollen. Wenn ein Test mit der Option only gesetzt ist, werden auch alle Untertests ausgeführt. Wenn für eine Suite die Option only gesetzt ist, werden alle Tests innerhalb der Suite ausgeführt, es sei denn, sie hat Nachfolger mit der Option only gesetzt, in diesem Fall werden nur diese Tests ausgeführt.

Bei Verwendung von Untertests innerhalb eines test()/it() ist es erforderlich, alle übergeordneten Tests mit der Option only zu markieren, um nur eine ausgewählte Teilmenge von Tests auszuführen.

Die runOnly()-Methode des Testkontexts kann verwendet werden, um das gleiche Verhalten auf der Ebene der Untertests zu implementieren. Tests, die nicht ausgeführt werden, werden in der Ausgabe des Testläufers weggelassen.

// Angenommen, Node.js wird mit der Befehlszeilenoption --test-only ausgeführt.
// Die Option 'only' der Suite ist gesetzt, also werden diese Tests ausgeführt.
test('Dieser Test wird ausgeführt', { only: true }, async t => {
  // Innerhalb dieses Tests werden standardmäßig alle Untertests ausgeführt.
  await t.test('Untertest wird ausgeführt')

  // Der Testkontext kann aktualisiert werden, um Untertests mit der Option 'only' auszuführen.
  t.runOnly(true)
  await t.test('Dieser Untertest wird nun übersprungen')
  await t.test('Dieser Untertest wird ausgeführt', { only: true })

  // Schalten Sie den Kontext zurück, um alle Tests auszuführen.
  t.runOnly(false)
  await t.test('Dieser Untertest wird nun ausgeführt')

  // Führen Sie diese Tests explizit nicht aus.
  await t.test('Übersprungener Untertest 3', { only: false })
  await t.test('Übersprungener Untertest 4', { skip: true })
})

// Die Option 'only' ist nicht gesetzt, also wird dieser Test übersprungen.
test('Dieser Test wird nicht ausgeführt', () => {
  // Dieser Code wird nicht ausgeführt.
  throw new Error('Fehler')
})

describe('eine Suite', () => {
  // Die Option 'only' ist gesetzt, also wird dieser Test ausgeführt.
  it('Dieser Test wird ausgeführt', { only: true }, () => {
    // Dieser Code wird ausgeführt.
  })

  it('Dieser Test wird nicht ausgeführt', () => {
    // Dieser Code wird nicht ausgeführt.
    throw new Error('Fehler')
  })
})

describe.only('eine Suite', () => {
  // Die Option 'only' ist gesetzt, also wird dieser Test ausgeführt.
  it('Dieser Test wird ausgeführt', () => {
    // Dieser Code wird ausgeführt.
  })

  it('Dieser Test wird ausgeführt', () => {
    // Dieser Code wird ausgeführt.
  })
})

Tests nach Name filtern

Die Kommandozeilenoption --test-name-pattern kann verwendet werden, um nur Tests auszuführen, deren Name mit dem bereitgestellten Muster übereinstimmt, und die Option --test-skip-pattern kann verwendet werden, um Tests zu überspringen, deren Name mit dem bereitgestellten Muster übereinstimmt. Testnamensmuster werden als reguläre JavaScript-Ausdrücke interpretiert. Die Optionen --test-name-pattern und --test-skip-pattern können mehrfach angegeben werden, um verschachtelte Tests auszuführen. Für jeden Test, der ausgeführt wird, werden auch alle entsprechenden Test-Hooks, wie z. B. beforeEach(), ausgeführt. Tests, die nicht ausgeführt werden, werden aus der Testrunner-Ausgabe weggelassen.

Angenommen, die folgende Testdatei, das Starten von Node.js mit der Option --test-name-pattern="test [1-3]" würde dazu führen, dass der Testrunner test 1, test 2 und test 3 ausführt. Wenn test 1 nicht mit dem Testnamensmuster übereinstimmte, würden seine Subtests nicht ausgeführt, obwohl sie mit dem Muster übereinstimmten. Derselbe Satz von Tests könnte auch durch mehrfaches Übergeben von --test-name-pattern ausgeführt werden (z. B. --test-name-pattern="test 1", --test-name-pattern="test 2", usw.).

test('test 1', async t => {
  await t.test('test 2')
  await t.test('test 3')
})

test('Test 4', async t => {
  await t.test('Test 5')
  await t.test('test 6')
})

Testnamensmuster können auch mit regulären Ausdrucks-Literalen angegeben werden. Dies ermöglicht die Verwendung von regulären Ausdrucks-Flags. Im vorherigen Beispiel würde das Starten von Node.js mit --test-name-pattern="/test [4-5]/i" (oder --test-skip-pattern="/test [4-5]/i") Test 4 und Test 5 übereinstimmen, da das Muster nicht zwischen Groß- und Kleinschreibung unterscheidet.

Um einen einzelnen Test mit einem Muster zu finden, können Sie ihm alle seine übergeordneten Testnamen, getrennt durch Leerzeichen, voranstellen, um sicherzustellen, dass er eindeutig ist. Angenommen, die folgende Testdatei:

describe('test 1', t => {
  it('some test')
})

describe('test 2', t => {
  it('some test')
})

Das Starten von Node.js mit --test-name-pattern="test 1 some test" würde nur some test in test 1 entsprechen.

Testnamensmuster ändern nicht die Menge der Dateien, die der Testrunner ausführt.

Wenn sowohl --test-name-pattern als auch --test-skip-pattern angegeben werden, müssen Tests beide Anforderungen erfüllen, um ausgeführt zu werden.

Externe asynchrone Aktivität

Sobald eine Testfunktion die Ausführung abgeschlossen hat, werden die Ergebnisse so schnell wie möglich gemeldet, während die Reihenfolge der Tests beibehalten wird. Es ist jedoch möglich, dass die Testfunktion asynchrone Aktivitäten erzeugt, die den Test selbst überdauern. Der Testrunner behandelt diese Art von Aktivität, verzögert aber nicht die Meldung der Testergebnisse, um sie zu berücksichtigen.

Im folgenden Beispiel wird ein Test mit zwei ausstehenden setImmediate()-Operationen abgeschlossen. Die erste setImmediate()-Operation versucht, einen neuen Untertest zu erstellen. Da der übergeordnete Test bereits abgeschlossen ist und seine Ergebnisse ausgegeben hat, wird der neue Untertest sofort als fehlgeschlagen markiert und später an den <TestsStream> gemeldet.

Die zweite setImmediate()-Operation erzeugt ein uncaughtException-Ereignis. uncaughtException- und unhandledRejection-Ereignisse, die von einem abgeschlossenen Test stammen, werden vom test-Modul als fehlgeschlagen markiert und als Diagnosewarnungen auf der obersten Ebene von der <TestsStream> gemeldet.

test('ein Test, der asynchrone Aktivitäten erzeugt', t => {
  setImmediate(() => {
    t.test('Untertest, der zu spät erstellt wird', t => {
      throw new Error('error1')
    })
  })

  setImmediate(() => {
    throw new Error('error2')
  })

  // Der Test ist nach dieser Zeile beendet.
})

Watch-Modus

Hinzugefügt in: v19.2.0, v18.13.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Der Node.js-Testrunner unterstützt die Ausführung im Watch-Modus durch Übergabe des --watch-Flags:

node --test --watch

Im Watch-Modus überwacht der Testrunner Änderungen an Testdateien und deren Abhängigkeiten. Wenn eine Änderung erkannt wird, führt der Testrunner die von der Änderung betroffenen Tests erneut aus. Der Testrunner wird so lange ausgeführt, bis der Prozess beendet wird.

Ausführen von Tests über die Befehlszeile

Der Node.js-Testrunner kann über die Befehlszeile aufgerufen werden, indem das --test-Flag übergeben wird:

node --test

Standardmäßig führt Node.js alle Dateien aus, die diesen Mustern entsprechen:

• **/*.test.{cjs,mjs,js}
• **/*-test.{cjs,mjs,js}
• **/*_test.{cjs,mjs,js}
• **/test-*.{cjs,mjs,js}
• **/test.{cjs,mjs,js}
• **/test/**/*.{cjs,mjs,js}

Wenn --experimental-strip-types angegeben wird, werden die folgenden zusätzlichen Muster abgeglichen:

• **/*.test.{cts,mts,ts}
• **/*-test.{cts,mts,ts}
• **/*_test.{cts,mts,ts}
• **/test-*.{cts,mts,ts}
• **/test.{cts,mts,ts}
• **/test/**/*.{cts,mts,ts}

Alternativ können ein oder mehrere Glob-Muster als letztes Argument(e) an den Node.js-Befehl übergeben werden, wie unten gezeigt. Glob-Muster folgen dem Verhalten von glob(7). Die Glob-Muster sollten in der Befehlszeile in doppelte Anführungszeichen gesetzt werden, um eine Shell-Erweiterung zu verhindern, die die Portabilität über verschiedene Systeme hinweg beeinträchtigen kann.

node --test "**/*.test.js" "**/*.spec.js"

Übereinstimmende Dateien werden als Testdateien ausgeführt. Weitere Informationen zur Ausführung von Testdateien finden Sie im Abschnitt Test Runner Execution Model.

Test Runner Ausführungsmodell

Wenn die Testisolierung auf Prozessebene aktiviert ist, wird jede übereinstimmende Testdatei in einem separaten untergeordneten Prozess ausgeführt. Die maximale Anzahl der gleichzeitig laufenden untergeordneten Prozesse wird durch das Flag --test-concurrency gesteuert. Wenn der untergeordnete Prozess mit einem Exit-Code von 0 beendet wird, gilt der Test als bestanden. Andernfalls gilt der Test als fehlgeschlagen. Testdateien müssen von Node.js ausführbar sein, müssen aber das Modul node:test nicht intern verwenden.

Jede Testdatei wird so ausgeführt, als wäre sie ein reguläres Skript. Das heißt, wenn die Testdatei selbst node:test verwendet, um Tests zu definieren, werden alle diese Tests innerhalb eines einzigen Anwendungs-Threads ausgeführt, unabhängig vom Wert der Option concurrency von test().

Wenn die Testisolierung auf Prozessebene deaktiviert ist, wird jede übereinstimmende Testdatei in den Test Runner Prozess importiert. Sobald alle Testdateien geladen wurden, werden die obersten Tests mit einer Gleichzeitigkeit von eins ausgeführt. Da die Testdateien alle im selben Kontext ausgeführt werden, ist es möglich, dass Tests auf eine Weise miteinander interagieren, die bei aktivierter Isolierung nicht möglich ist. Wenn beispielsweise ein Test von einem globalen Zustand abhängt, ist es möglich, dass dieser Zustand durch einen Test geändert wird, der aus einer anderen Datei stammt.

Codeabdeckung erfassen

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Wenn Node.js mit dem Befehlszeilenflag --experimental-test-coverage gestartet wird, wird die Codeabdeckung erfasst und Statistiken werden gemeldet, sobald alle Tests abgeschlossen sind. Wenn die Umgebungsvariable NODE_V8_COVERAGE verwendet wird, um ein Codeabdeckungsverzeichnis anzugeben, werden die generierten V8-Abdeckungsdateien in dieses Verzeichnis geschrieben. Node.js-Kernmodule und Dateien innerhalb von node_modules/-Verzeichnissen sind standardmäßig nicht im Abdeckungsbericht enthalten. Sie können jedoch explizit über das Flag --test-coverage-include aufgenommen werden. Standardmäßig sind alle übereinstimmenden Testdateien vom Abdeckungsbericht ausgeschlossen. Ausschlüsse können mithilfe des Flags --test-coverage-exclude außer Kraft gesetzt werden. Wenn die Abdeckung aktiviert ist, wird der Abdeckungsbericht über das Ereignis 'test:coverage' an alle Test-Reporter gesendet.

Die Abdeckung kann auf einer Reihe von Zeilen mit der folgenden Kommentar-Syntax deaktiviert werden:

/* node:coverage disable */
if (anAlwaysFalseCondition) {
  // Code in diesem Zweig wird niemals ausgeführt, aber die Zeilen werden
  // für Abdeckungszwecke ignoriert. Alle Zeilen, die auf den "disable"-Kommentar
  // folgen, werden ignoriert, bis ein entsprechender "enable"-Kommentar
  // gefunden wird.
  console.log('this is never executed')
}
/* node:coverage enable */

Die Abdeckung kann auch für eine angegebene Anzahl von Zeilen deaktiviert werden. Nach der angegebenen Anzahl von Zeilen wird die Abdeckung automatisch wieder aktiviert. Wenn die Anzahl der Zeilen nicht explizit angegeben wird, wird eine einzelne Zeile ignoriert.

/* node:coverage ignore next */
if (anAlwaysFalseCondition) {
  console.log('this is never executed')
}

/* node:coverage ignore next 3 */
if (anAlwaysFalseCondition) {
  console.log('this is never executed')
}

Coverage-Reporter

Die tap- und spec-Reporter geben eine Zusammenfassung der Coverage-Statistiken aus. Es gibt auch einen lcov-Reporter, der eine lcov-Datei generiert, die als detaillierter Coverage-Report verwendet werden kann.

node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info

• Dieser Reporter gibt keine Testergebnisse aus.
• Dieser Reporter sollte idealerweise zusammen mit einem anderen Reporter verwendet werden.

Mocking

Das Modul node:test unterstützt das Mocking während des Testens über ein Top-Level-Objekt mock. Das folgende Beispiel erstellt einen Spy für eine Funktion, die zwei Zahlen addiert. Der Spy wird dann verwendet, um zu bestätigen, dass die Funktion wie erwartet aufgerufen wurde.

ESM

import assert from 'node:assert'
import { mock, test } from 'node:test'

test('spioniert eine Funktion aus', () => {
  const sum = mock.fn((a, b) => {
    return a + b
  })

  assert.strictEqual(sum.mock.callCount(), 0)
  assert.strictEqual(sum(3, 4), 7)
  assert.strictEqual(sum.mock.callCount(), 1)

  const call = sum.mock.calls[0]
  assert.deepStrictEqual(call.arguments, [3, 4])
  assert.strictEqual(call.result, 7)
  assert.strictEqual(call.error, undefined)

  // Setzt die global verfolgten Mocks zurück.
  mock.reset()
})

CJS

'use strict'
const assert = require('node:assert')
const { mock, test } = require('node:test')

test('spioniert eine Funktion aus', () => {
  const sum = mock.fn((a, b) => {
    return a + b
  })

  assert.strictEqual(sum.mock.callCount(), 0)
  assert.strictEqual(sum(3, 4), 7)
  assert.strictEqual(sum.mock.callCount(), 1)

  const call = sum.mock.calls[0]
  assert.deepStrictEqual(call.arguments, [3, 4])
  assert.strictEqual(call.result, 7)
  assert.strictEqual(call.error, undefined)

  // Setzt die global verfolgten Mocks zurück.
  mock.reset()
})

Die gleiche Mocking-Funktionalität wird auch über das TestContext-Objekt jedes Tests verfügbar gemacht. Das folgende Beispiel erstellt einen Spy für eine Objektmethode mithilfe der API, die im TestContext verfügbar gemacht wird. Der Vorteil des Mockings über den Testkontext ist, dass der Testrunner automatisch alle gemockten Funktionalitäten wiederherstellt, sobald der Test beendet ist.

test('spioniert eine Objektmethode aus', t => {
  const number = {
    value: 5,
    add(a) {
      return this.value + a
    },
  }

  t.mock.method(number, 'add')
  assert.strictEqual(number.add.mock.callCount(), 0)
  assert.strictEqual(number.add(3), 8)
  assert.strictEqual(number.add.mock.callCount(), 1)

  const call = number.add.mock.calls[0]

  assert.deepStrictEqual(call.arguments, [3])
  assert.strictEqual(call.result, 8)
  assert.strictEqual(call.target, undefined)
  assert.strictEqual(call.this, number)
})

Timer

Das Mocken von Timern ist eine Technik, die häufig beim Softwaretest verwendet wird, um das Verhalten von Timern wie setInterval und setTimeout zu simulieren und zu steuern, ohne tatsächlich auf die angegebenen Zeitintervalle zu warten.

Eine vollständige Liste der Methoden und Funktionen finden Sie in der MockTimers-Klasse.

Dies ermöglicht es Entwicklern, zuverlässigere und vorhersehbarere Tests für zeitabhängige Funktionen zu schreiben.

Das folgende Beispiel zeigt, wie setTimeout gemockt wird. Mit .enable({ apis: ['setTimeout'] }); werden die setTimeout-Funktionen in den Modulen node:timers und node:timers/promises sowie aus dem globalen Node.js-Kontext gemockt.

Hinweis: Das Destrukturieren von Funktionen wie import { setTimeout } from 'node:timers' wird von dieser API derzeit nicht unterstützt.

ESM

import assert from 'node:assert'
import { mock, test } from 'node:test'

test('mockt setTimeout, sodass es synchron ausgeführt wird, ohne tatsächlich darauf warten zu müssen', () => {
  const fn = mock.fn()

  // Optional auswählen, was gemockt werden soll
  mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)

  // In der Zeit vorwärts gehen
  mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)

  // Die global verfolgten Mocks zurücksetzen.
  mock.timers.reset()

  // Wenn Sie die Mock-Instanz zurücksetzen, wird auch die Timer-Instanz zurückgesetzt
  mock.reset()
})

CJS

const assert = require('node:assert')
const { mock, test } = require('node:test')

test('mockt setTimeout, sodass es synchron ausgeführt wird, ohne tatsächlich darauf warten zu müssen', () => {
  const fn = mock.fn()

  // Optional auswählen, was gemockt werden soll
  mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)

  // In der Zeit vorwärts gehen
  mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)

  // Die global verfolgten Mocks zurücksetzen.
  mock.timers.reset()

  // Wenn Sie die Mock-Instanz zurücksetzen, wird auch die Timer-Instanz zurückgesetzt
  mock.reset()
})

Die gleiche Mocking-Funktionalität wird auch in der Mock-Eigenschaft des TestContext-Objekts jedes Tests bereitgestellt. Der Vorteil des Mockens über den Testkontext besteht darin, dass der Testrunner alle gemockten Timer-Funktionen automatisch wiederherstellt, sobald der Test abgeschlossen ist.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mockt setTimeout, sodass es synchron ausgeführt wird, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)

  // In der Zeit vorwärts gehen
  context.mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mockt setTimeout, sodass es synchron ausgeführt wird, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)

  // In der Zeit vorwärts gehen
  context.mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)
})

Daten

Die Mock-Timer-API ermöglicht auch das Mocken des Date-Objekts. Dies ist eine nützliche Funktion zum Testen zeitabhängiger Funktionalität oder zum Simulieren interner Kalenderfunktionen wie Date.now().

Die Datums-Implementierung ist auch Teil der Klasse MockTimers. Dort finden Sie eine vollständige Liste der Methoden und Funktionen.

Hinweis: Daten und Timer sind voneinander abhängig, wenn sie zusammen gemockt werden. Das bedeutet, dass, wenn sowohl Date als auch setTimeout gemockt sind, das Vorrücken der Zeit auch das gemockte Datum vorwärts bewegt, da sie eine einzige interne Uhr simulieren.

Das folgende Beispiel zeigt, wie man das Date-Objekt mockt und den aktuellen Date.now()-Wert erhält.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mockt das Date-Objekt', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'] })
  // Wenn nicht anders angegeben, basiert das Anfangsdatum auf 0 in der UNIX-Epoche
  assert.strictEqual(Date.now(), 0)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.tick(9999)
  assert.strictEqual(Date.now(), 9999)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mockt das Date-Objekt', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'] })
  // Wenn nicht anders angegeben, basiert das Anfangsdatum auf 0 in der UNIX-Epoche
  assert.strictEqual(Date.now(), 0)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.tick(9999)
  assert.strictEqual(Date.now(), 9999)
})

Wenn keine Anfangsepoche festgelegt ist, basiert das Anfangsdatum auf 0 in der Unix-Epoche. Das ist der 1. Januar 1970, 00:00:00 UTC. Sie können ein Anfangsdatum festlegen, indem Sie der Methode .enable() eine now-Eigenschaft übergeben. Dieser Wert wird als Anfangsdatum für das gemockte Date-Objekt verwendet. Es kann entweder eine positive Ganzzahl oder ein anderes Date-Objekt sein.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mockt das Date-Objekt mit der Anfangszeit', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'], now: 100 })
  assert.strictEqual(Date.now(), 100)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.tick(200)
  assert.strictEqual(Date.now(), 300)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mockt das Date-Objekt mit der Anfangszeit', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'], now: 100 })
  assert.strictEqual(Date.now(), 100)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.tick(200)
  assert.strictEqual(Date.now(), 300)
})

Sie können die Methode .setTime() verwenden, um das gemockte Datum manuell auf eine andere Zeit zu verschieben. Diese Methode akzeptiert nur eine positive Ganzzahl.

Hinweis: Diese Methode führt alle gemockten Timer aus, die aus der neuen Zeit in der Vergangenheit liegen.

Im folgenden Beispiel setzen wir eine neue Zeit für das gemockte Datum.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('setzt die Zeit eines Date-Objekts', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'], now: 100 })
  assert.strictEqual(Date.now(), 100)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.setTime(1000)
  context.mock.timers.tick(200)
  assert.strictEqual(Date.now(), 1200)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('setzt die Zeit eines Date-Objekts', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['Date'], now: 100 })
  assert.strictEqual(Date.now(), 100)

  // Das Vorrücken der Zeit bewegt auch das Datum vorwärts
  context.mock.timers.setTime(1000)
  context.mock.timers.tick(200)
  assert.strictEqual(Date.now(), 1200)
})

Wenn Sie einen Timer haben, der in der Vergangenheit ausgeführt werden soll, wird er so ausgeführt, als ob die Methode .tick() aufgerufen worden wäre. Dies ist nützlich, wenn Sie zeitabhängige Funktionalität testen möchten, die bereits in der Vergangenheit liegt.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('führt Timer aus, wenn setTime Ticks überschreitet', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const fn = context.mock.fn()
  setTimeout(fn, 1000)

  context.mock.timers.setTime(800)
  // Timer wird nicht ausgeführt, da die Zeit noch nicht erreicht ist
  assert.strictEqual(fn.mock.callCount(), 0)
  assert.strictEqual(Date.now(), 800)

  context.mock.timers.setTime(1200)
  // Timer wird ausgeführt, da die Zeit jetzt erreicht ist
  assert.strictEqual(fn.mock.callCount(), 1)
  assert.strictEqual(Date.now(), 1200)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('führt Timer aus, wenn setTime Ticks überschreitet', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const fn = context.mock.fn()
  setTimeout(fn, 1000)

  context.mock.timers.setTime(800)
  // Timer wird nicht ausgeführt, da die Zeit noch nicht erreicht ist
  assert.strictEqual(fn.mock.callCount(), 0)
  assert.strictEqual(Date.now(), 800)

  context.mock.timers.setTime(1200)
  // Timer wird ausgeführt, da die Zeit jetzt erreicht ist
  assert.strictEqual(fn.mock.callCount(), 1)
  assert.strictEqual(Date.now(), 1200)
})

Die Verwendung von .runAll() führt alle Timer aus, die sich derzeit in der Warteschlange befinden. Dadurch wird auch das gemockte Datum auf die Zeit des letzten ausgeführten Timers vorgerückt, als ob die Zeit vergangen wäre.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('führt Timer aus, wenn setTime Ticks überschreitet', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const fn = context.mock.fn()
  setTimeout(fn, 1000)
  setTimeout(fn, 2000)
  setTimeout(fn, 3000)

  context.mock.timers.runAll()
  // Alle Timer werden ausgeführt, da die Zeit jetzt erreicht ist
  assert.strictEqual(fn.mock.callCount(), 3)
  assert.strictEqual(Date.now(), 3000)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('führt Timer aus, wenn setTime Ticks überschreitet', context => {
  // Optional wählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const fn = context.mock.fn()
  setTimeout(fn, 1000)
  setTimeout(fn, 2000)
  setTimeout(fn, 3000)

  context.mock.timers.runAll()
  // Alle Timer werden ausgeführt, da die Zeit jetzt erreicht ist
  assert.strictEqual(fn.mock.callCount(), 3)
  assert.strictEqual(Date.now(), 3000)
})

Snapshot-Tests

[Stable: 1 - Experimentell]

Stable: 1 Stabilität: 1.0 - Frühe Entwicklung

Snapshot-Tests ermöglichen es, beliebige Werte in String-Werte zu serialisieren und mit einer Reihe bekannter guter Werte zu vergleichen. Die bekannten guten Werte werden als Snapshots bezeichnet und in einer Snapshot-Datei gespeichert. Snapshot-Dateien werden vom Test-Runner verwaltet, sind aber so konzipiert, dass sie zur Unterstützung des Debuggings für Menschen lesbar sind. Es ist Best Practice, Snapshot-Dateien zusammen mit Ihren Testdateien in die Quellcodeverwaltung einzuchecken.

Snapshot-Dateien werden generiert, indem Node.js mit dem Befehlszeilenflag --test-update-snapshots gestartet wird. Für jede Testdatei wird eine separate Snapshot-Datei generiert. Standardmäßig hat die Snapshot-Datei den gleichen Namen wie die Testdatei mit der Dateiendung .snapshot. Dieses Verhalten kann mit der Funktion snapshot.setResolveSnapshotPath() konfiguriert werden. Jede Snapshot-Assertion entspricht einem Export in der Snapshot-Datei.

Ein Beispiel für einen Snapshot-Test wird unten gezeigt. Wenn dieser Test zum ersten Mal ausgeführt wird, schlägt er fehl, da die entsprechende Snapshot-Datei nicht existiert.

// test.js
suite('Suite von Snapshot-Tests', () => {
  test('Snapshot-Test', t => {
    t.assert.snapshot({ value1: 1, value2: 2 })
    t.assert.snapshot(5)
  })
})

Generieren Sie die Snapshot-Datei, indem Sie die Testdatei mit --test-update-snapshots ausführen. Der Test sollte bestehen und eine Datei mit dem Namen test.js.snapshot wird im gleichen Verzeichnis wie die Testdatei erstellt. Der Inhalt der Snapshot-Datei wird unten angezeigt. Jeder Snapshot wird durch den vollständigen Namen des Tests und einen Zähler identifiziert, um zwischen Snapshots im selben Test zu unterscheiden.

exports[`Suite von Snapshot-Tests > Snapshot-Test 1`] = `
{
  "value1": 1,
  "value2": 2
}
`

exports[`Suite von Snapshot-Tests > Snapshot-Test 2`] = `
5
`

Sobald die Snapshot-Datei erstellt wurde, führen Sie die Tests erneut ohne das Flag --test-update-snapshots aus. Die Tests sollten nun bestehen.

Test-Reporter

[Geschichte]

Version	Änderungen
v19.9.0, v18.17.0	Reporter sind jetzt unter node:test/reporters verfügbar.
v19.6.0, v18.15.0	Hinzugefügt in: v19.6.0, v18.15.0

Das Modul node:test unterstützt das Übergeben von --test-reporter-Flags, damit der Testrunner einen bestimmten Reporter verwendet.

Die folgenden integrierten Reporter werden unterstützt:

• spec Der spec-Reporter gibt die Testergebnisse in einem für Menschen lesbaren Format aus. Dies ist der Standardreporter.
• tap Der tap-Reporter gibt die Testergebnisse im TAP-Format aus.
• dot Der dot-Reporter gibt die Testergebnisse in einem kompakten Format aus, wobei jeder bestandene Test durch einen . und jeder fehlgeschlagene Test durch ein X dargestellt wird.
• junit Der junit-Reporter gibt die Testergebnisse in einem jUnit-XML-Format aus.
• lcov Der lcov-Reporter gibt die Testabdeckung aus, wenn er mit dem Flag --experimental-test-coverage verwendet wird.

Die genaue Ausgabe dieser Reporter kann sich zwischen den Versionen von Node.js ändern und sollte nicht programmatisch verwendet werden. Wenn programmatischer Zugriff auf die Ausgabe des Testrunners erforderlich ist, verwenden Sie die von <TestsStream> ausgegebenen Ereignisse.

Die Reporter sind über das Modul node:test/reporters verfügbar:

ESM

import { tap, spec, dot, junit, lcov } from 'node:test/reporters'

CJS

const { tap, spec, dot, junit, lcov } = require('node:test/reporters')

Benutzerdefinierte Reporter

--test-reporter kann verwendet werden, um einen Pfad zu einem benutzerdefinierten Reporter anzugeben. Ein benutzerdefinierter Reporter ist ein Modul, das einen von stream.compose akzeptierten Wert exportiert. Reporter sollten Ereignisse transformieren, die von einem <TestsStream> ausgegeben werden.

Beispiel für einen benutzerdefinierten Reporter mit <stream.Transform>:

ESM

import { Transform } from 'node:stream'

const customReporter = new Transform({
  writableObjectMode: true,
  transform(event, encoding, callback) {
    switch (event.type) {
      case 'test:dequeue':
        callback(null, `test ${event.data.name} dequeued`)
        break
      case 'test:enqueue':
        callback(null, `test ${event.data.name} enqueued`)
        break
      case 'test:watch:drained':
        callback(null, 'test watch queue drained')
        break
      case 'test:start':
        callback(null, `test ${event.data.name} started`)
        break
      case 'test:pass':
        callback(null, `test ${event.data.name} passed`)
        break
      case 'test:fail':
        callback(null, `test ${event.data.name} failed`)
        break
      case 'test:plan':
        callback(null, 'test plan')
        break
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        callback(null, event.data.message)
        break
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals
        callback(null, `total line count: ${totalLineCount}\n`)
        break
      }
    }
  },
})

export default customReporter

CJS

const { Transform } = require('node:stream')

const customReporter = new Transform({
  writableObjectMode: true,
  transform(event, encoding, callback) {
    switch (event.type) {
      case 'test:dequeue':
        callback(null, `test ${event.data.name} dequeued`)
        break
      case 'test:enqueue':
        callback(null, `test ${event.data.name} enqueued`)
        break
      case 'test:watch:drained':
        callback(null, 'test watch queue drained')
        break
      case 'test:start':
        callback(null, `test ${event.data.name} started`)
        break
      case 'test:pass':
        callback(null, `test ${event.data.name} passed`)
        break
      case 'test:fail':
        callback(null, `test ${event.data.name} failed`)
        break
      case 'test:plan':
        callback(null, 'test plan')
        break
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        callback(null, event.data.message)
        break
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals
        callback(null, `total line count: ${totalLineCount}\n`)
        break
      }
    }
  },
})

module.exports = customReporter

Beispiel für einen benutzerdefinierten Reporter mit einer Generatorfunktion:

ESM

export default async function* customReporter(source) {
  for await (const event of source) {
    switch (event.type) {
      case 'test:dequeue':
        yield `test ${event.data.name} dequeued\n`
        break
      case 'test:enqueue':
        yield `test ${event.data.name} enqueued\n`
        break
      case 'test:watch:drained':
        yield 'test watch queue drained\n'
        break
      case 'test:start':
        yield `test ${event.data.name} started\n`
        break
      case 'test:pass':
        yield `test ${event.data.name} passed\n`
        break
      case 'test:fail':
        yield `test ${event.data.name} failed\n`
        break
      case 'test:plan':
        yield 'test plan\n'
        break
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        yield `${event.data.message}\n`
        break
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals
        yield `total line count: ${totalLineCount}\n`
        break
      }
    }
  }
}

CJS

module.exports = async function* customReporter(source) {
  for await (const event of source) {
    switch (event.type) {
      case 'test:dequeue':
        yield `test ${event.data.name} dequeued\n`
        break
      case 'test:enqueue':
        yield `test ${event.data.name} enqueued\n`
        break
      case 'test:watch:drained':
        yield 'test watch queue drained\n'
        break
      case 'test:start':
        yield `test ${event.data.name} started\n`
        break
      case 'test:pass':
        yield `test ${event.data.name} passed\n`
        break
      case 'test:fail':
        yield `test ${event.data.name} failed\n`
        break
      case 'test:plan':
        yield 'test plan\n'
        break
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        yield `${event.data.message}\n`
        break
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals
        yield `total line count: ${totalLineCount}\n`
        break
      }
    }
  }
}

Der Wert, der an --test-reporter übergeben wird, sollte ein String sein, wie er in einem import() in JavaScript-Code verwendet wird, oder ein Wert, der für --import angegeben wird.

Mehrere Reporter

Das Flag --test-reporter kann mehrfach angegeben werden, um Testergebnisse in mehreren Formaten zu melden. In dieser Situation ist es erforderlich, für jeden Reporter ein Ziel mit --test-reporter-destination anzugeben. Das Ziel kann stdout, stderr oder ein Dateipfad sein. Reporter und Ziele werden gemäß der Reihenfolge, in der sie angegeben wurden, zugeordnet.

Im folgenden Beispiel gibt der spec-Reporter auf stdout aus und der dot-Reporter auf file.txt:

node --test-reporter=spec --test-reporter=dot --test-reporter-destination=stdout --test-reporter-destination=file.txt

Wenn ein einzelner Reporter angegeben wird, ist das Ziel standardmäßig stdout, es sei denn, es wird explizit ein Ziel angegeben.

run([options])

[Verlauf]

Version	Änderungen
v23.0.0	Die Option cwd wurde hinzugefügt.
v23.0.0	Deckungsoptionen hinzugefügt.
v22.8.0	Die Option isolation wurde hinzugefügt.
v22.6.0	Die Option globPatterns wurde hinzugefügt.
v22.0.0, v20.14.0	Die Option forceExit wurde hinzugefügt.
v20.1.0, v18.17.0	Eine Option testNamePatterns hinzugefügt.
v18.9.0, v16.19.0	Hinzugefügt in: v18.9.0, v16.19.0

• options <Object> Konfigurationsoptionen zum Ausführen von Tests. Die folgenden Eigenschaften werden unterstützt:

  • concurrency <number> | <boolean> Wenn eine Zahl angegeben wird, werden so viele Testprozesse parallel ausgeführt, wobei jeder Prozess einer Testdatei entspricht. Wenn true, werden os.availableParallelism() - 1 Testdateien parallel ausgeführt. Wenn false, wird nur eine Testdatei gleichzeitig ausgeführt. Standard: false.

  • cwd: <string> Gibt das aktuelle Arbeitsverzeichnis an, das vom Test Runner verwendet werden soll. Dient als Basispfad für das Auflösen von Dateien gemäß dem Test Runner Ausführungsmodell. Standard: process.cwd().

  • files: <Array> Ein Array, das die Liste der auszuführenden Dateien enthält. Standard: Übereinstimmende Dateien aus Test Runner Ausführungsmodell.

  • forceExit: <boolean> Konfiguriert den Test Runner so, dass der Prozess beendet wird, sobald alle bekannten Tests abgeschlossen sind, auch wenn die Ereignisschleife ansonsten aktiv bleiben würde. Standard: false.

  • globPatterns: <Array> Ein Array, das die Liste der Glob-Muster enthält, die mit Testdateien übereinstimmen sollen. Diese Option kann nicht zusammen mit files verwendet werden. Standard: Übereinstimmende Dateien aus Test Runner Ausführungsmodell.

  • inspectPort <number> | <Function> Setzt den Inspektorport des Test-Child-Prozesses. Dies kann eine Zahl oder eine Funktion sein, die keine Argumente akzeptiert und eine Zahl zurückgibt. Wenn ein Nullwert angegeben wird, erhält jeder Prozess einen eigenen Port, der ab dem process.debugPort des Hauptprozesses inkrementiert wird. Diese Option wird ignoriert, wenn die Option isolation auf 'none' gesetzt ist, da keine Child-Prozesse erzeugt werden. Standard: undefined.

  • isolation <string> Konfiguriert die Art der Testisolation. Wenn auf 'process' gesetzt, wird jede Testdatei in einem separaten Child-Prozess ausgeführt. Wenn auf 'none' gesetzt, werden alle Testdateien im aktuellen Prozess ausgeführt. Standard: 'process'.

  • only: <boolean> Wenn truthy, führt der Testkontext nur Tests aus, die die Option only gesetzt haben

  • setup <Function> Eine Funktion, die die TestsStream-Instanz akzeptiert und zum Einrichten von Listenern verwendet werden kann, bevor Tests ausgeführt werden. Standard: undefined.

  • execArgv <Array> Ein Array von CLI-Flags, die an die node-Ausführungsdatei übergeben werden, wenn die Subprozesse erzeugt werden. Diese Option hat keine Auswirkung, wenn isolation 'none' ist. Standard: []

  • argv <Array> Ein Array von CLI-Flags, die an jede Testdatei übergeben werden, wenn die Subprozesse erzeugt werden. Diese Option hat keine Auswirkung, wenn isolation 'none' ist. Standard: [].

  • signal <AbortSignal> Ermöglicht das Abbrechen einer laufenden Testausführung.

  • testNamePatterns <string> | <RegExp> | <Array> Eine String, RegExp oder ein RegExp-Array, das verwendet werden kann, um nur Tests auszuführen, deren Name mit dem angegebenen Muster übereinstimmt. Testnamensmuster werden als reguläre JavaScript-Ausdrücke interpretiert. Für jeden ausgeführten Test werden auch alle entsprechenden Testhooks, wie z. B. beforeEach(), ausgeführt. Standard: undefined.

  • testSkipPatterns <string> | <RegExp> | <Array> Eine String, RegExp oder ein RegExp-Array, das verwendet werden kann, um das Ausführen von Tests auszuschließen, deren Name mit dem angegebenen Muster übereinstimmt. Testnamensmuster werden als reguläre JavaScript-Ausdrücke interpretiert. Für jeden ausgeführten Test werden auch alle entsprechenden Testhooks, wie z. B. beforeEach(), ausgeführt. Standard: undefined.

  • timeout <number> Eine Anzahl von Millisekunden, nach denen die Testausführung fehlschlägt. Wenn nicht anders angegeben, erben Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

  • watch <boolean> Ob im Überwachungsmodus ausgeführt werden soll oder nicht. Standard: false.

  • shard <Object> Ausführen von Tests in einem bestimmten Shard. Standard: undefined.

  • index <number> ist eine positive ganze Zahl zwischen 1 und \<total\>, die den Index des auszuführenden Shards angibt. Diese Option ist erforderlich.

  • total <number> ist eine positive ganze Zahl, die die Gesamtzahl der Shards angibt, in die die Testdateien aufgeteilt werden sollen. Diese Option ist erforderlich.

  • coverage <boolean> Aktiviert die Code Coverage-Erfassung. Standard: false.

  • coverageExcludeGlobs <string> | <Array> Schließt bestimmte Dateien mit einem Glob-Muster von der Code Coverage aus, das sowohl absolute als auch relative Dateipfade abgleichen kann. Diese Eigenschaft ist nur anwendbar, wenn coverage auf true gesetzt wurde. Wenn sowohl coverageExcludeGlobs als auch coverageIncludeGlobs angegeben werden, müssen Dateien beide Kriterien erfüllen, um in den Coverage-Bericht aufgenommen zu werden. Standard: undefined.

  • coverageIncludeGlobs <string> | <Array> Schließt bestimmte Dateien mit einem Glob-Muster in die Code Coverage ein, das sowohl absolute als auch relative Dateipfade abgleichen kann. Diese Eigenschaft ist nur anwendbar, wenn coverage auf true gesetzt wurde. Wenn sowohl coverageExcludeGlobs als auch coverageIncludeGlobs angegeben werden, müssen Dateien beide Kriterien erfüllen, um in den Coverage-Bericht aufgenommen zu werden. Standard: undefined.

  • lineCoverage <number> Erfordert einen minimalen Prozentsatz abgedeckter Zeilen. Wenn die Code Coverage den angegebenen Schwellenwert nicht erreicht, wird der Prozess mit dem Code 1 beendet. Standard: 0.

  • branchCoverage <number> Erfordert einen minimalen Prozentsatz abgedeckter Branches. Wenn die Code Coverage den angegebenen Schwellenwert nicht erreicht, wird der Prozess mit dem Code 1 beendet. Standard: 0.

  • functionCoverage <number> Erfordert einen minimalen Prozentsatz abgedeckter Funktionen. Wenn die Code Coverage den angegebenen Schwellenwert nicht erreicht, wird der Prozess mit dem Code 1 beendet. Standard: 0.

• Gibt zurück: <TestsStream>

Hinweis: shard wird verwendet, um Testausführungen horizontal über Maschinen oder Prozesse zu parallelisieren, ideal für groß angelegte Ausführungen in verschiedenen Umgebungen. Es ist inkompatibel mit dem watch-Modus, der auf schnelle Codeiteration zugeschnitten ist, indem Tests bei Dateiänderungen automatisch neu ausgeführt werden.

ESM

import { tap } from 'node:test/reporters'
import { run } from 'node:test'
import process from 'node:process'
import path from 'node:path'

run({ files: [path.resolve('./tests/test.js')] })
  .on('test:fail', () => {
    process.exitCode = 1
  })
  .compose(tap)
  .pipe(process.stdout)

CJS

const { tap } = require('node:test/reporters')
const { run } = require('node:test')
const path = require('node:path')

run({ files: [path.resolve('./tests/test.js')] })
  .on('test:fail', () => {
    process.exitCode = 1
  })
  .compose(tap)
  .pipe(process.stdout)

suite([name][, options][, fn])

Hinzugefügt in: v22.0.0, v20.13.0

• name <string> Der Name der Suite, der bei der Meldung von Testergebnissen angezeigt wird. Standard: Die name-Eigenschaft von fn oder '\<anonymous\>', wenn fn keinen Namen hat.
• options <Object> Optionale Konfigurationsoptionen für die Suite. Dies unterstützt die gleichen Optionen wie test([name][, options][, fn]).
• fn <Function> | <AsyncFunction> Die Suite-Funktion, die verschachtelte Tests und Suiten deklariert. Das erste Argument dieser Funktion ist ein SuiteContext-Objekt. Standard: Eine No-op-Funktion.
• Gibt zurück: <Promise> Wird sofort mit undefined erfüllt.

Die suite()-Funktion wird aus dem node:test-Modul importiert.

suite.skip([name][, options][, fn])

Hinzugefügt in: v22.0.0, v20.13.0

Abkürzung zum Überspringen einer Suite. Dies ist dasselbe wie suite([name], { skip: true }[, fn]).

suite.todo([name][, options][, fn])

Hinzugefügt in: v22.0.0, v20.13.0

Abkürzung zum Markieren einer Suite als TODO. Dies ist dasselbe wie suite([name], { todo: true }[, fn]).

suite.only([name][, options][, fn])

Hinzugefügt in: v22.0.0, v20.13.0

Abkürzung zum Markieren einer Suite als only. Dies ist dasselbe wie suite([name], { only: true }[, fn]).

test([name][, options][, fn])

[Verlauf]

Version	Änderungen
v20.2.0, v18.17.0	Die Kurzschreibweisen skip, todo und only wurden hinzugefügt.
v18.8.0, v16.18.0	Eine signal-Option wurde hinzugefügt.
v18.7.0, v16.17.0	Eine timeout-Option wurde hinzugefügt.
v18.0.0, v16.17.0	Hinzugefügt in: v18.0.0, v16.17.0

• name <string> Der Name des Tests, der bei der Meldung von Testergebnissen angezeigt wird. Standard: Die name-Eigenschaft von fn oder '\<anonymous\>', wenn fn keinen Namen hat.
• options <Object> Konfigurationsoptionen für den Test. Die folgenden Eigenschaften werden unterstützt:
  • concurrency <number> | <boolean> Wenn eine Zahl angegeben wird, werden so viele Tests parallel innerhalb des Anwendungsthreads ausgeführt. Wenn true, werden alle geplanten asynchronen Tests gleichzeitig innerhalb des Threads ausgeführt. Wenn false, wird nur ein Test gleichzeitig ausgeführt. Wenn nicht angegeben, erben Untertests diesen Wert von ihren Eltern. Standard: false.
  • only <boolean> Wenn wahrheitsgemäß und der Testkontext so konfiguriert ist, dass nur only-Tests ausgeführt werden, wird dieser Test ausgeführt. Andernfalls wird der Test übersprungen. Standard: false.
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Tests.
  • skip <boolean> | <string> Wenn wahrheitsgemäß, wird der Test übersprungen. Wenn eine Zeichenfolge angegeben wird, wird diese Zeichenfolge in den Testergebnissen als Grund für das Überspringen des Tests angezeigt. Standard: false.
  • todo <boolean> | <string> Wenn wahrheitsgemäß, wird der Test als TODO markiert. Wenn eine Zeichenfolge angegeben wird, wird diese Zeichenfolge in den Testergebnissen als Grund dafür angezeigt, warum der Test TODO ist. Standard: false.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Test fehlschlägt. Wenn nicht angegeben, erben Untertests diesen Wert von ihren Eltern. Standard: Infinity.
  • plan <number> Die Anzahl der Assertionen und Untertests, die voraussichtlich in dem Test ausgeführt werden. Wenn die Anzahl der in dem Test ausgeführten Assertionen nicht mit der in dem Plan angegebenen Anzahl übereinstimmt, schlägt der Test fehl. Standard: undefined.
• fn <Function> | <AsyncFunction> Die zu testende Funktion. Das erste Argument dieser Funktion ist ein TestContext-Objekt. Wenn der Test Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-op-Funktion.
• Gibt zurück: <Promise> Erfüllt mit undefined, sobald der Test abgeschlossen ist, oder sofort, wenn der Test innerhalb einer Suite ausgeführt wird.

Die Funktion test() ist der Wert, der aus dem Modul test importiert wird. Jeder Aufruf dieser Funktion führt dazu, dass der Test an den <TestsStream> gemeldet wird.

Das TestContext-Objekt, das an das fn-Argument übergeben wird, kann verwendet werden, um Aktionen im Zusammenhang mit dem aktuellen Test durchzuführen. Beispiele hierfür sind das Überspringen des Tests, das Hinzufügen zusätzlicher Diagnoseinformationen oder das Erstellen von Untertests.

test() gibt ein Promise zurück, das erfüllt wird, sobald der Test abgeschlossen ist. Wenn test() innerhalb einer Suite aufgerufen wird, wird es sofort erfüllt. Der Rückgabewert kann in der Regel für Tests auf oberster Ebene verworfen werden. Der Rückgabewert von Untertests sollte jedoch verwendet werden, um zu verhindern, dass der übergeordnete Test zuerst beendet wird und den Untertest abbricht, wie im folgenden Beispiel gezeigt.

test('top level test', async t => {
  // Das setTimeout() im folgenden Untertest würde dazu führen, dass er seinen
  // übergeordneten Test überlebt, wenn 'await' in der nächsten Zeile entfernt wird. Sobald der übergeordnete Test
  // abgeschlossen ist, werden alle ausstehenden Untertests abgebrochen.
  await t.test('länger laufender Untertest', async t => {
    return new Promise((resolve, reject) => {
      setTimeout(resolve, 1000)
    })
  })
})

Die Option timeout kann verwendet werden, um den Test zum Fehlschlagen zu bringen, wenn seine Ausführung länger als timeout Millisekunden dauert. Dies ist jedoch kein zuverlässiger Mechanismus zum Abbrechen von Tests, da ein laufender Test den Anwendungsthread blockieren und somit die geplante Abbrechung verhindern kann.

test.skip([name][, options][, fn])

Abkürzung zum Überspringen eines Tests, entspricht test([name], { skip: true }[, fn]).

test.todo([name][, options][, fn])

Abkürzung zum Markieren eines Tests als TODO, entspricht test([name], { todo: true }[, fn]).

test.only([name][, options][, fn])

Abkürzung zum Markieren eines Tests als only, entspricht test([name], { only: true }[, fn]).

describe([name][, options][, fn])

Alias für suite().

Die Funktion describe() wird aus dem node:test-Modul importiert.

describe.skip([name][, options][, fn])

Abkürzung zum Überspringen einer Suite. Dies entspricht describe([name], { skip: true }[, fn]).

describe.todo([name][, options][, fn])

Abkürzung zum Markieren einer Suite als TODO. Dies entspricht describe([name], { todo: true }[, fn]).

describe.only([name][, options][, fn])

Hinzugefügt in: v19.8.0, v18.15.0

Abkürzung zum Markieren einer Suite als only. Dies entspricht describe([name], { only: true }[, fn]).

it([name][, options][, fn])

[Verlauf]

Version	Änderungen
v19.8.0, v18.16.0	Der Aufruf von it() entspricht nun dem Aufruf von test().
v18.6.0, v16.17.0	Hinzugefügt in: v18.6.0, v16.17.0

Alias für test().

Die Funktion it() wird aus dem node:test-Modul importiert.

it.skip([name][, options][, fn])

Abkürzung zum Überspringen eines Tests, entspricht it([name], { skip: true }[, fn]).

it.todo([name][, options][, fn])

Abkürzung zum Markieren eines Tests als TODO, entspricht it([name], { todo: true }[, fn]).

it.only([name][, options][, fn])

Hinzugefügt in: v19.8.0, v18.15.0

Abkürzung zum Markieren eines Tests als only, entspricht it([name], { only: true }[, fn]).

before([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Function> | <AsyncFunction> Die Hook-Funktion. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Object> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion erstellt einen Hook, der vor der Ausführung einer Suite ausgeführt wird.

describe('tests', async () => {
  before(() => console.log('about to run some test'))
  it('is a subtest', () => {
    assert.ok('some relevant assertion here')
  })
})

after([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Function> | <AsyncFunction> Die Hook-Funktion. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Object> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion erstellt einen Hook, der nach der Ausführung einer Suite ausgeführt wird.

describe('tests', async () => {
  after(() => console.log('finished running tests'))
  it('is a subtest', () => {
    assert.ok('some relevant assertion here')
  })
})

Hinweis: Der after-Hook wird garantiert ausgeführt, auch wenn Tests innerhalb der Suite fehlschlagen.

beforeEach([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Function> | <AsyncFunction> Die Hook-Funktion. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Object> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <number> Die Anzahl der Millisekunden, nach denen der Hook fehlschlägt. Wenn nicht angegeben, erben Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion erstellt einen Hook, der vor jedem Test in der aktuellen Suite ausgeführt wird.

describe('tests', async () => {
  beforeEach(() => console.log('about to run a test'))
  it('is a subtest', () => {
    assert.ok('some relevant assertion here')
  })
})

afterEach([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Function> | <AsyncFunction> Die Hook-Funktion. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Object> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <number> Die Anzahl der Millisekunden, nach denen der Hook fehlschlägt. Wenn nicht angegeben, erben Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion erstellt einen Hook, der nach jedem Test in der aktuellen Suite ausgeführt wird. Der afterEach()-Hook wird auch dann ausgeführt, wenn der Test fehlschlägt.

describe('tests', async () => {
  afterEach(() => console.log('finished running a test'))
  it('is a subtest', () => {
    assert.ok('some relevant assertion here')
  })
})

snapshot

Hinzugefügt in: v22.3.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

Ein Objekt, dessen Methoden verwendet werden, um Standardeinstellungen für Snapshots im aktuellen Prozess zu konfigurieren. Es ist möglich, dieselbe Konfiguration auf alle Dateien anzuwenden, indem gemeinsamer Konfigurationscode in ein Modul platziert wird, das mit --require oder --import vorgeladen wird.

snapshot.setDefaultSnapshotSerializers(serializers)

Hinzugefügt in: v22.3.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

• serializers <Array> Ein Array von synchronen Funktionen, die als Standard-Serialisierer für Snapshot-Tests verwendet werden.

Diese Funktion wird verwendet, um den Standard-Serialisierungsmechanismus anzupassen, der vom Test-Runner verwendet wird. Standardmäßig führt der Test-Runner die Serialisierung durch Aufrufen von JSON.stringify(value, null, 2) auf dem bereitgestellten Wert durch. JSON.stringify() hat Einschränkungen in Bezug auf zirkuläre Strukturen und unterstützte Datentypen. Wenn ein robusterer Serialisierungsmechanismus erforderlich ist, sollte diese Funktion verwendet werden.

snapshot.setResolveSnapshotPath(fn)

Hinzugefügt in: v22.3.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

• fn <Funktion> Eine Funktion, die verwendet wird, um den Speicherort der Snapshot-Datei zu berechnen. Die Funktion empfängt den Pfad der Testdatei als einziges Argument. Wenn der Test keiner Datei zugeordnet ist (z. B. in der REPL), ist die Eingabe undefiniert. fn() muss einen String zurückgeben, der den Speicherort der Snapshot-Datei angibt.

Diese Funktion wird verwendet, um den Speicherort der Snapshot-Datei anzupassen, die für Snapshot-Tests verwendet wird. Standardmäßig ist der Snapshot-Dateiname derselbe wie der Name der Einstiegspunktdatei mit der Dateierweiterung .snapshot.

Klasse: MockFunctionContext

Hinzugefügt in: v19.1.0, v18.13.0

Die Klasse MockFunctionContext wird verwendet, um das Verhalten von Mocks zu inspizieren oder zu manipulieren, die über die MockTracker-APIs erstellt wurden.

ctx.calls

Hinzugefügt in: v19.1.0, v18.13.0

• <Array>

Ein Getter, der eine Kopie des internen Arrays zurückgibt, das verwendet wird, um Aufrufe des Mocks zu verfolgen. Jeder Eintrag im Array ist ein Objekt mit den folgenden Eigenschaften.

• arguments <Array> Ein Array der Argumente, die an die Mock-Funktion übergeben wurden.
• error <any> Wenn die Mock-Funktion eine Ausnahme ausgelöst hat, enthält diese Eigenschaft den ausgelösten Wert. Standard: undefined.
• result <any> Der Wert, der von der Mock-Funktion zurückgegeben wurde.
• stack <Error> Ein Error-Objekt, dessen Stack verwendet werden kann, um die Aufrufstelle des Aufrufs der Mock-Funktion zu bestimmen.
• target <Function> | <undefined> Wenn die Mock-Funktion ein Konstruktor ist, enthält dieses Feld die zu konstruierende Klasse. Andernfalls ist dies undefined.
• this <any> Der this-Wert der Mock-Funktion.

ctx.callCount()

Hinzugefügt in: v19.1.0, v18.13.0

• Gibt zurück: <integer> Die Anzahl, wie oft dieser Mock aufgerufen wurde.

Diese Funktion gibt die Anzahl zurück, wie oft dieser Mock aufgerufen wurde. Diese Funktion ist effizienter als die Überprüfung von ctx.calls.length, da ctx.calls ein Getter ist, der eine Kopie des internen Call-Tracking-Arrays erstellt.

ctx.mockImplementation(implementation)

Hinzugefügt in: v19.1.0, v18.13.0

• implementation <Funktion> | <AsyncFunction> Die Funktion, die als neue Implementierung des Mocks verwendet werden soll.

Diese Funktion wird verwendet, um das Verhalten eines vorhandenen Mocks zu ändern.

Das folgende Beispiel erstellt eine Mock-Funktion mit t.mock.fn(), ruft die Mock-Funktion auf und ändert dann die Mock-Implementierung in eine andere Funktion.

test('ändert das Verhalten eines Mocks', t => {
  let cnt = 0

  function addOne() {
    cnt++
    return cnt
  }

  function addTwo() {
    cnt += 2
    return cnt
  }

  const fn = t.mock.fn(addOne)

  assert.strictEqual(fn(), 1)
  fn.mock.mockImplementation(addTwo)
  assert.strictEqual(fn(), 3)
  assert.strictEqual(fn(), 5)
})

ctx.mockImplementationOnce(implementation[, onCall])

Hinzugefügt in: v19.1.0, v18.13.0

• implementation <Funktion> | <AsyncFunction> Die Funktion, die als Implementierung des Mocks für die durch onCall angegebene Aufrufnummer verwendet werden soll.
• onCall <Integer> Die Aufrufnummer, die implementation verwenden soll. Wenn der angegebene Aufruf bereits stattgefunden hat, wird eine Ausnahme ausgelöst. Standard: Die Nummer des nächsten Aufrufs.

Diese Funktion wird verwendet, um das Verhalten eines vorhandenen Mocks für einen einzelnen Aufruf zu ändern. Sobald der Aufruf onCall stattgefunden hat, kehrt der Mock zu dem Verhalten zurück, das er verwendet hätte, wenn mockImplementationOnce() nicht aufgerufen worden wäre.

Das folgende Beispiel erstellt eine Mock-Funktion mit t.mock.fn(), ruft die Mock-Funktion auf, ändert die Mock-Implementierung für den nächsten Aufruf in eine andere Funktion und nimmt dann das vorherige Verhalten wieder auf.

test('ändert das Verhalten eines Mocks einmal', t => {
  let cnt = 0

  function addOne() {
    cnt++
    return cnt
  }

  function addTwo() {
    cnt += 2
    return cnt
  }

  const fn = t.mock.fn(addOne)

  assert.strictEqual(fn(), 1)
  fn.mock.mockImplementationOnce(addTwo)
  assert.strictEqual(fn(), 3)
  assert.strictEqual(fn(), 4)
})

ctx.resetCalls()

Hinzugefügt in: v19.3.0, v18.13.0

Setzt die Aufrufhistorie der Mock-Funktion zurück.

ctx.restore()

Hinzugefügt in: v19.1.0, v18.13.0

Setzt die Implementierung der Mock-Funktion auf ihr ursprüngliches Verhalten zurück. Der Mock kann nach dem Aufruf dieser Funktion weiterhin verwendet werden.

Klasse: MockModuleContext

Hinzugefügt in: v22.3.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

Die Klasse MockModuleContext wird verwendet, um das Verhalten von Modul-Mocks zu manipulieren, die über die MockTracker-APIs erstellt wurden.

ctx.restore()

Hinzugefügt in: v22.3.0, v20.18.0

Setzt die Implementierung des Mock-Moduls zurück.

Klasse: MockTracker

Hinzugefügt in: v19.1.0, v18.13.0

Die Klasse MockTracker wird verwendet, um Mock-Funktionen zu verwalten. Das Test Runner-Modul stellt einen Top-Level-mock-Export bereit, der eine MockTracker-Instanz ist. Jeder Test stellt auch seine eigene MockTracker-Instanz über die mock-Eigenschaft des Testkontexts bereit.

mock.fn([original[, implementation]][, options])

Hinzugefügt in: v19.1.0, v18.13.0

• original <Funktion> | <AsyncFunction> Eine optionale Funktion, auf der ein Mock erstellt werden soll. Standard: Eine No-Op-Funktion.

• implementation <Funktion> | <AsyncFunction> Eine optionale Funktion, die als Mock-Implementierung für original verwendet wird. Dies ist nützlich für das Erstellen von Mocks, die ein bestimmtes Verhalten für eine angegebene Anzahl von Aufrufen aufweisen und dann das Verhalten von original wiederherstellen. Standard: Die von original angegebene Funktion.

• options <Objekt> Optionale Konfigurationsoptionen für die Mock-Funktion. Die folgenden Eigenschaften werden unterstützt:

  • times <Integer> Die Anzahl der Male, die der Mock das Verhalten von implementation verwendet. Sobald die Mock-Funktion times-mal aufgerufen wurde, wird das Verhalten von original automatisch wiederhergestellt. Dieser Wert muss eine ganze Zahl größer als Null sein. Standard: Infinity.

• Gibt zurück: <Proxy> Die gemockte Funktion. Die gemockte Funktion enthält eine spezielle mock-Eigenschaft, die eine Instanz von MockFunctionContext ist und zum Untersuchen und Ändern des Verhaltens der gemockten Funktion verwendet werden kann.

Diese Funktion wird verwendet, um eine Mock-Funktion zu erstellen.

Das folgende Beispiel erstellt eine Mock-Funktion, die bei jedem Aufruf einen Zähler um eins erhöht. Die Option times wird verwendet, um das Mock-Verhalten so zu ändern, dass die ersten beiden Aufrufe zwei zum Zähler addieren anstatt eins.

test('mocks a counting function', t => {
  let cnt = 0

  function addOne() {
    cnt++
    return cnt
  }

  function addTwo() {
    cnt += 2
    return cnt
  }

  const fn = t.mock.fn(addOne, addTwo, { times: 2 })

  assert.strictEqual(fn(), 2)
  assert.strictEqual(fn(), 4)
  assert.strictEqual(fn(), 5)
  assert.strictEqual(fn(), 6)
})

mock.getter(object, methodName[, implementation][, options])

Hinzugefügt in: v19.3.0, v18.13.0

Diese Funktion ist Syntaxzucker für MockTracker.method mit options.getter auf true gesetzt.

mock.method(object, methodName[, implementation][, options])

Hinzugefügt in: v19.1.0, v18.13.0

• object <Object> Das Objekt, dessen Methode gemockt wird.

• methodName <string> | <symbol> Der Bezeichner der Methode auf object, die gemockt werden soll. Wenn object[methodName] keine Funktion ist, wird ein Fehler ausgelöst.

• implementation <Function> | <AsyncFunction> Eine optionale Funktion, die als Mock-Implementierung für object[methodName] verwendet wird. Standard: Die ursprüngliche Methode, die von object[methodName] angegeben wird.

• options <Object> Optionale Konfigurationsoptionen für die Mock-Methode. Die folgenden Eigenschaften werden unterstützt:

  • getter <boolean> Wenn true, wird object[methodName] als Getter behandelt. Diese Option kann nicht mit der Option setter verwendet werden. Standard: false.
  • setter <boolean> Wenn true, wird object[methodName] als Setter behandelt. Diese Option kann nicht mit der Option getter verwendet werden. Standard: false.
  • times <integer> Die Anzahl der Male, die der Mock das Verhalten von implementation verwenden wird. Sobald die gemockte Methode times Mal aufgerufen wurde, wird das ursprüngliche Verhalten automatisch wiederhergestellt. Dieser Wert muss eine ganze Zahl größer als Null sein. Standard: Infinity.

• Gibt zurück: <Proxy> Die gemockte Methode. Die gemockte Methode enthält eine spezielle mock-Eigenschaft, die eine Instanz von MockFunctionContext ist und zum Überprüfen und Ändern des Verhaltens der gemockten Methode verwendet werden kann.

Diese Funktion wird verwendet, um einen Mock für eine vorhandene Objektmethode zu erstellen. Das folgende Beispiel demonstriert, wie ein Mock für eine vorhandene Objektmethode erstellt wird.

test('spioniert eine Objektmethode aus', t => {
  const number = {
    value: 5,
    subtract(a) {
      return this.value - a
    },
  }

  t.mock.method(number, 'subtract')
  assert.strictEqual(number.subtract.mock.callCount(), 0)
  assert.strictEqual(number.subtract(3), 2)
  assert.strictEqual(number.subtract.mock.callCount(), 1)

  const call = number.subtract.mock.calls[0]

  assert.deepStrictEqual(call.arguments, [3])
  assert.strictEqual(call.result, 2)
  assert.strictEqual(call.error, undefined)
  assert.strictEqual(call.target, undefined)
  assert.strictEqual(call.this, number)
})

mock.module(specifier[, options])

Hinzugefügt in: v22.3.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

• specifier <string> | <URL> Eine Zeichenkette, die das zu mockende Modul identifiziert.

• options <Object> Optionale Konfigurationsoptionen für das Mock-Modul. Die folgenden Eigenschaften werden unterstützt:

  • cache <boolean> Wenn false, erzeugt jeder Aufruf von require() oder import() ein neues Mock-Modul. Wenn true, geben nachfolgende Aufrufe dasselbe Mock-Modul zurück und das Mock-Modul wird in den CommonJS-Cache eingefügt. Standard: false.
  • defaultExport <any> Ein optionaler Wert, der als Standardexport des gemockten Moduls verwendet wird. Wenn dieser Wert nicht angegeben wird, enthalten ESM-Mocks keinen Standardexport. Wenn der Mock ein CommonJS- oder Builtin-Modul ist, wird diese Einstellung als Wert von module.exports verwendet. Wenn dieser Wert nicht angegeben wird, verwenden CJS- und Builtin-Mocks ein leeres Objekt als Wert von module.exports.
  • namedExports <Object> Ein optionales Objekt, dessen Schlüssel und Werte verwendet werden, um die benannten Exporte des Mock-Moduls zu erstellen. Wenn der Mock ein CommonJS- oder Builtin-Modul ist, werden diese Werte in module.exports kopiert. Wenn also ein Mock mit benannten Exporten und einem Nicht-Objekt-Standardexport erstellt wird, löst der Mock eine Ausnahme aus, wenn er als CJS- oder Builtin-Modul verwendet wird.

• Gibt zurück: <MockModuleContext> Ein Objekt, das zur Manipulation des Mocks verwendet werden kann.

Diese Funktion wird verwendet, um die Exporte von ECMAScript-Modulen, CommonJS-Modulen und Node.js-Builtin-Modulen zu mocken. Alle Verweise auf das ursprüngliche Modul vor dem Mocken werden nicht beeinflusst. Um Modul-Mocking zu aktivieren, muss Node.js mit dem Befehlszeilenflag --experimental-test-module-mocks gestartet werden.

Das folgende Beispiel demonstriert, wie ein Mock für ein Modul erstellt wird.

test('mockt ein eingebautes Modul in beiden Modulsystemen', async t => {
  // Erstellt einen Mock von 'node:readline' mit einem benannten Export namens 'fn', der
  // im ursprünglichen Modul 'node:readline' nicht existiert.
  const mock = t.mock.module('node:readline', {
    namedExports: {
      fn() {
        return 42
      },
    },
  })

  let esmImpl = await import('node:readline')
  let cjsImpl = require('node:readline')

  // cursorTo() ist ein Export des ursprünglichen Moduls 'node:readline'.
  assert.strictEqual(esmImpl.cursorTo, undefined)
  assert.strictEqual(cjsImpl.cursorTo, undefined)
  assert.strictEqual(esmImpl.fn(), 42)
  assert.strictEqual(cjsImpl.fn(), 42)

  mock.restore()

  // Der Mock ist wiederhergestellt, also wird das ursprüngliche Builtin-Modul zurückgegeben.
  esmImpl = await import('node:readline')
  cjsImpl = require('node:readline')

  assert.strictEqual(typeof esmImpl.cursorTo, 'function')
  assert.strictEqual(typeof cjsImpl.cursorTo, 'function')
  assert.strictEqual(esmImpl.fn, undefined)
  assert.strictEqual(cjsImpl.fn, undefined)
})

mock.reset()

Hinzugefügt in: v19.1.0, v18.13.0

Diese Funktion stellt das Standardverhalten aller Mocks wieder her, die zuvor von diesem MockTracker erstellt wurden, und trennt die Mocks von der MockTracker-Instanz. Nach der Trennung können die Mocks weiterhin verwendet werden, aber die MockTracker-Instanz kann nicht mehr verwendet werden, um ihr Verhalten zurückzusetzen oder anderweitig mit ihnen zu interagieren.

Nach Abschluss jedes Tests wird diese Funktion auf dem MockTracker des Testkontexts aufgerufen. Wenn der globale MockTracker ausgiebig verwendet wird, wird die manuelle Aufruf dieser Funktion empfohlen.

mock.restoreAll()

Hinzugefügt in: v19.1.0, v18.13.0

Diese Funktion stellt das Standardverhalten aller Mocks wieder her, die zuvor von diesem MockTracker erstellt wurden. Im Gegensatz zu mock.reset() trennt mock.restoreAll() die Mocks nicht von der MockTracker-Instanz.

mock.setter(object, methodName[, implementation][, options])

Hinzugefügt in: v19.3.0, v18.13.0

Diese Funktion ist Syntaxzucker für MockTracker.method mit options.setter auf true gesetzt.

Klasse: MockTimers

[Verlauf]

Version	Änderungen
v23.1.0	Die Mock Timers sind jetzt stabil.
v20.4.0, v18.19.0	Hinzugefügt in: v20.4.0, v18.19.0

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Das Mocking von Timern ist eine Technik, die häufig beim Softwaretesting verwendet wird, um das Verhalten von Timern, wie z. B. setInterval und setTimeout, zu simulieren und zu steuern, ohne tatsächlich auf die angegebenen Zeitintervalle zu warten.

MockTimers ist auch in der Lage, das Date-Objekt zu mocken.

Der MockTracker stellt einen Top-Level timers-Export bereit, der eine MockTimers-Instanz ist.

timers.enable([enableOptions])

[Verlauf]

Version	Änderungen
v21.2.0, v20.11.0	Parameter aktualisiert, um ein Options-Objekt mit verfügbaren APIs und der standardmäßigen initialen Epoche zu sein.
v20.4.0, v18.19.0	Hinzugefügt in: v20.4.0, v18.19.0

Aktiviert das Timer-Mocking für die angegebenen Timer.

• enableOptions <Object> Optionale Konfigurationsoptionen zum Aktivieren des Timer-Mockings. Die folgenden Eigenschaften werden unterstützt:
  • apis <Array> Ein optionales Array, das die zu mockenden Timer enthält. Die derzeit unterstützten Timer-Werte sind 'setInterval', 'setTimeout', 'setImmediate' und 'Date'. Standard: ['setInterval', 'setTimeout', 'setImmediate', 'Date']. Wenn kein Array angegeben wird, werden standardmäßig alle zeitbezogenen APIs ('setInterval', 'clearInterval', 'setTimeout', 'clearTimeout', 'setImmediate', 'clearImmediate' und 'Date') gemockt.
  • now <number> | <Date> Eine optionale Zahl oder ein Date-Objekt, die die Anfangszeit (in Millisekunden) darstellt, die als Wert für Date.now() verwendet werden soll. Standard: 0.

Hinweis: Wenn Sie das Mocking für einen bestimmten Timer aktivieren, wird die zugehörige Löschfunktion implizit ebenfalls gemockt.

Hinweis: Das Mocking von Date beeinflusst das Verhalten der gemockten Timer, da diese dieselbe interne Uhr verwenden.

Beispielhafte Verwendung ohne Festlegung der Anfangszeit:

ESM

import { mock } from 'node:test'
mock.timers.enable({ apis: ['setInterval'] })

CJS

const { mock } = require('node:test')
mock.timers.enable({ apis: ['setInterval'] })

Das obige Beispiel aktiviert das Mocking für den setInterval-Timer und mockt implizit die clearInterval-Funktion. Nur die setInterval- und clearInterval-Funktionen von node:timers, node:timers/promises und globalThis werden gemockt.

Beispielhafte Verwendung mit festgelegter Anfangszeit

ESM

import { mock } from 'node:test'
mock.timers.enable({ apis: ['Date'], now: 1000 })

CJS

const { mock } = require('node:test')
mock.timers.enable({ apis: ['Date'], now: 1000 })

Beispielhafte Verwendung mit initialem Date-Objekt als festgelegte Zeit

ESM

import { mock } from 'node:test'
mock.timers.enable({ apis: ['Date'], now: new Date() })

CJS

const { mock } = require('node:test')
mock.timers.enable({ apis: ['Date'], now: new Date() })

Alternativ werden alle Timer ('setInterval', 'clearInterval', 'setTimeout', 'clearTimeout', 'setImmediate' und 'clearImmediate') gemockt, wenn Sie mock.timers.enable() ohne Parameter aufrufen. Die Funktionen setInterval, clearInterval, setTimeout, clearTimeout, setImmediate und clearImmediate von node:timers, node:timers/promises und globalThis werden gemockt. Sowie das globale Date-Objekt.

timers.reset()

Hinzugefügt in: v20.4.0, v18.19.0

Diese Funktion stellt das Standardverhalten aller Mocks wieder her, die zuvor von dieser MockTimers-Instanz erstellt wurden, und trennt die Mocks von der MockTracker-Instanz.

Hinweis: Nachdem jeder Test abgeschlossen ist, wird diese Funktion auf dem MockTracker des Testkontexts aufgerufen.

ESM

import { mock } from 'node:test'
mock.timers.reset()

CJS

const { mock } = require('node:test')
mock.timers.reset()

timers[Symbol.dispose]()

Ruft timers.reset() auf.

timers.tick([Millisekunden])

Hinzugefügt in: v20.4.0, v18.19.0

Erhöht die Zeit für alle gemockten Timer.

• Millisekunden <number> Die Zeitspanne in Millisekunden, um die die Timer vorwärts bewegt werden sollen. Standard: 1.

Hinweis: Dies weicht davon ab, wie setTimeout in Node.js sich verhält, und akzeptiert nur positive Zahlen. In Node.js wird setTimeout mit negativen Zahlen nur aus Gründen der Webkompatibilität unterstützt.

Das folgende Beispiel mockt eine setTimeout-Funktion und erhöht durch die Verwendung von .tick die Zeit, wodurch alle ausstehenden Timer ausgelöst werden.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  context.mock.timers.enable({ apis: ['setTimeout'] })

  setTimeout(fn, 9999)

  assert.strictEqual(fn.mock.callCount(), 0)

  // Zeit vorwärts bewegen
  context.mock.timers.tick(9999)

  assert.strictEqual(fn.mock.callCount(), 1)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()
  context.mock.timers.enable({ apis: ['setTimeout'] })

  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)

  // Zeit vorwärts bewegen
  context.mock.timers.tick(9999)

  assert.strictEqual(fn.mock.callCount(), 1)
})

Alternativ kann die Funktion .tick auch mehrmals aufgerufen werden

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()
  context.mock.timers.enable({ apis: ['setTimeout'] })
  const nineSecs = 9000
  setTimeout(fn, nineSecs)

  const threeSeconds = 3000
  context.mock.timers.tick(threeSeconds)
  context.mock.timers.tick(threeSeconds)
  context.mock.timers.tick(threeSeconds)

  assert.strictEqual(fn.mock.callCount(), 1)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()
  context.mock.timers.enable({ apis: ['setTimeout'] })
  const nineSecs = 9000
  setTimeout(fn, nineSecs)

  const threeSeconds = 3000
  context.mock.timers.tick(threeSeconds)
  context.mock.timers.tick(threeSeconds)
  context.mock.timers.tick(threeSeconds)

  assert.strictEqual(fn.mock.callCount(), 1)
})

Das Vorwärtsbewegen der Zeit mit .tick bewegt auch die Zeit für jedes Date-Objekt vorwärts, das nach dem Aktivieren des Mocks erstellt wurde (wenn Date ebenfalls zum Mocken festgelegt wurde).

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  setTimeout(fn, 9999)

  assert.strictEqual(fn.mock.callCount(), 0)
  assert.strictEqual(Date.now(), 0)

  // Zeit vorwärts bewegen
  context.mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)
  assert.strictEqual(Date.now(), 9999)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })

  setTimeout(fn, 9999)
  assert.strictEqual(fn.mock.callCount(), 0)
  assert.strictEqual(Date.now(), 0)

  // Zeit vorwärts bewegen
  context.mock.timers.tick(9999)
  assert.strictEqual(fn.mock.callCount(), 1)
  assert.strictEqual(Date.now(), 9999)
})

Verwenden von Clear-Funktionen

Wie bereits erwähnt, werden alle Clear-Funktionen von Timern (clearTimeout, clearInterval und clearImmediate) implizit gemockt. Sehen Sie sich dieses Beispiel mit setTimeout an:

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  const id = setTimeout(fn, 9999)

  // Auch implizit gemockt
  clearTimeout(id)
  context.mock.timers.tick(9999)

  // Da dieses setTimeout gelöscht wurde, wird die Mock-Funktion niemals aufgerufen
  assert.strictEqual(fn.mock.callCount(), 0)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', context => {
  const fn = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  const id = setTimeout(fn, 9999)

  // Auch implizit gemockt
  clearTimeout(id)
  context.mock.timers.tick(9999)

  // Da dieses setTimeout gelöscht wurde, wird die Mock-Funktion niemals aufgerufen
  assert.strictEqual(fn.mock.callCount(), 0)
})

Arbeiten mit Node.js-Timer-Modulen

Sobald Sie das Mocken von Timern aktivieren, werden die Module node:timers, node:timers/promises und Timer aus dem globalen Kontext von Node.js aktiviert:

Hinweis: Das Destrukturieren von Funktionen wie import { setTimeout } from 'node:timers' wird von dieser API derzeit nicht unterstützt.

ESM

import assert from 'node:assert'
import { test } from 'node:test'
import nodeTimers from 'node:timers'
import nodeTimersPromises from 'node:timers/promises'

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', async context => {
  const globalTimeoutObjectSpy = context.mock.fn()
  const nodeTimerSpy = context.mock.fn()
  const nodeTimerPromiseSpy = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(globalTimeoutObjectSpy, 9999)
  nodeTimers.setTimeout(nodeTimerSpy, 9999)

  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy)

  // Zeit voranschreiten
  context.mock.timers.tick(9999)
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1)
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1)
  await promise
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')
const nodeTimers = require('node:timers')
const nodeTimersPromises = require('node:timers/promises')

test('mocks setTimeout, um synchron ausgeführt zu werden, ohne tatsächlich darauf warten zu müssen', async context => {
  const globalTimeoutObjectSpy = context.mock.fn()
  const nodeTimerSpy = context.mock.fn()
  const nodeTimerPromiseSpy = context.mock.fn()

  // Optional auswählen, was gemockt werden soll
  context.mock.timers.enable({ apis: ['setTimeout'] })
  setTimeout(globalTimeoutObjectSpy, 9999)
  nodeTimers.setTimeout(nodeTimerSpy, 9999)

  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy)

  // Zeit voranschreiten
  context.mock.timers.tick(9999)
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1)
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1)
  await promise
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1)
})

In Node.js ist setInterval von node:timers/promises ein AsyncGenerator und wird ebenfalls von dieser API unterstützt:

ESM

import assert from 'node:assert'
import { test } from 'node:test'
import nodeTimersPromises from 'node:timers/promises'
test('sollte fünfmal ticken, um einen realen Anwendungsfall zu testen', async context => {
  context.mock.timers.enable({ apis: ['setInterval'] })

  const expectedIterations = 3
  const interval = 1000
  const startedAt = Date.now()
  async function run() {
    const times = []
    for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
      times.push(time)
      if (times.length === expectedIterations) break
    }
    return times
  }

  const r = run()
  context.mock.timers.tick(interval)
  context.mock.timers.tick(interval)
  context.mock.timers.tick(interval)

  const timeResults = await r
  assert.strictEqual(timeResults.length, expectedIterations)
  for (let it = 1; it < expectedIterations; it++) {
    assert.strictEqual(timeResults[it - 1], startedAt + interval * it)
  }
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')
const nodeTimersPromises = require('node:timers/promises')
test('sollte fünfmal ticken, um einen realen Anwendungsfall zu testen', async context => {
  context.mock.timers.enable({ apis: ['setInterval'] })

  const expectedIterations = 3
  const interval = 1000
  const startedAt = Date.now()
  async function run() {
    const times = []
    for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
      times.push(time)
      if (times.length === expectedIterations) break
    }
    return times
  }

  const r = run()
  context.mock.timers.tick(interval)
  context.mock.timers.tick(interval)
  context.mock.timers.tick(interval)

  const timeResults = await r
  assert.strictEqual(timeResults.length, expectedIterations)
  for (let it = 1; it < expectedIterations; it++) {
    assert.strictEqual(timeResults[it - 1], startedAt + interval * it)
  }
})

timers.runAll()

Hinzugefügt in: v20.4.0, v18.19.0

Löst sofort alle ausstehenden simulierten Timer aus. Wenn das Date-Objekt ebenfalls simuliert wird, wird auch das Date-Objekt auf die Zeit des weitesten Timers vorverlegt.

Das folgende Beispiel löst alle ausstehenden Timer sofort aus und bewirkt, dass sie ohne Verzögerung ausgeführt werden.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('runAll-Funktionen in der angegebenen Reihenfolge', context => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const results = []
  setTimeout(() => results.push(1), 9999)

  // Beachten Sie, dass, wenn beide Timer die gleiche Auszeit haben,
  // die Ausführungsreihenfolge garantiert ist
  setTimeout(() => results.push(3), 8888)
  setTimeout(() => results.push(2), 8888)

  assert.deepStrictEqual(results, [])

  context.mock.timers.runAll()
  assert.deepStrictEqual(results, [3, 2, 1])
  // Das Date-Objekt wird ebenfalls auf die Zeit des weitesten Timers vorverlegt
  assert.strictEqual(Date.now(), 9999)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('runAll-Funktionen in der angegebenen Reihenfolge', context => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const results = []
  setTimeout(() => results.push(1), 9999)

  // Beachten Sie, dass, wenn beide Timer die gleiche Auszeit haben,
  // die Ausführungsreihenfolge garantiert ist
  setTimeout(() => results.push(3), 8888)
  setTimeout(() => results.push(2), 8888)

  assert.deepStrictEqual(results, [])

  context.mock.timers.runAll()
  assert.deepStrictEqual(results, [3, 2, 1])
  // Das Date-Objekt wird ebenfalls auf die Zeit des weitesten Timers vorverlegt
  assert.strictEqual(Date.now(), 9999)
})

Hinweis: Die runAll()-Funktion ist speziell für das Auslösen von Timern im Rahmen der Timer-Simulation konzipiert. Sie hat keine Auswirkungen auf Echtzeit-Systemuhren oder tatsächliche Timer außerhalb der Simulationsumgebung.

timers.setTime(milliseconds)

Hinzugefügt in: v21.2.0, v20.11.0

Setzt den aktuellen Unix-Zeitstempel, der als Referenz für alle simulierten Date-Objekte verwendet wird.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('runAll-Funktionen in der angegebenen Reihenfolge', context => {
  const now = Date.now()
  const setTime = 1000
  // Date.now ist nicht simuliert
  assert.deepStrictEqual(Date.now(), now)

  context.mock.timers.enable({ apis: ['Date'] })
  context.mock.timers.setTime(setTime)
  // Date.now ist jetzt 1000
  assert.strictEqual(Date.now(), setTime)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('setTime ersetzt die aktuelle Zeit', context => {
  const now = Date.now()
  const setTime = 1000
  // Date.now ist nicht simuliert
  assert.deepStrictEqual(Date.now(), now)

  context.mock.timers.enable({ apis: ['Date'] })
  context.mock.timers.setTime(setTime)
  // Date.now ist jetzt 1000
  assert.strictEqual(Date.now(), setTime)
})

Zusammenspiel von Datum und Timern

Datumsobjekte und Timerobjekte sind voneinander abhängig. Wenn Sie setTime() verwenden, um dem gemockten Date-Objekt die aktuelle Zeit zu übergeben, werden die mit setTimeout und setInterval gesetzten Timer nicht beeinflusst.

Die Methode tick wird jedoch das gemockte Date-Objekt vorwärts bewegen.

ESM

import assert from 'node:assert'
import { test } from 'node:test'

test('runAll-Funktionen in der vorgegebenen Reihenfolge ausführen', context => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const results = []
  setTimeout(() => results.push(1), 9999)

  assert.deepStrictEqual(results, [])
  context.mock.timers.setTime(12000)
  assert.deepStrictEqual(results, [])
  // Das Datum wird vorwärts bewegt, aber die Timer ticken nicht
  assert.strictEqual(Date.now(), 12000)
})

CJS

const assert = require('node:assert')
const { test } = require('node:test')

test('runAll-Funktionen in der vorgegebenen Reihenfolge ausführen', context => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
  const results = []
  setTimeout(() => results.push(1), 9999)

  assert.deepStrictEqual(results, [])
  context.mock.timers.setTime(12000)
  assert.deepStrictEqual(results, [])
  // Das Datum wird vorwärts bewegt, aber die Timer ticken nicht
  assert.strictEqual(Date.now(), 12000)
})

Klasse: TestsStream

[Historie]

Version	Änderungen
v20.0.0, v19.9.0, v18.17.0	Typ zu den Ereignissen test:pass und test:fail hinzugefügt, wenn der Test eine Suite ist.
v18.9.0, v16.19.0	Hinzugefügt in: v18.9.0, v16.19.0

• Erweitert <Readable>

Ein erfolgreicher Aufruf der Methode run() gibt ein neues <TestsStream>-Objekt zurück, das eine Reihe von Ereignissen streamt, die die Ausführung der Tests darstellen. TestsStream gibt Ereignisse in der Reihenfolge der Testdefinition aus.

Einige der Ereignisse werden garantiert in der gleichen Reihenfolge ausgegeben, in der die Tests definiert sind, während andere in der Reihenfolge ausgegeben werden, in der die Tests ausgeführt werden.

Ereignis: 'test:coverage'

• data <Object>

  • summary <Object> Ein Objekt, das den Coverage-Bericht enthält.

  • files <Array> Ein Array von Coverage-Berichten für einzelne Dateien. Jeder Bericht ist ein Objekt mit dem folgenden Schema:

  • path <string> Der absolute Pfad der Datei.

  • totalLineCount <number> Die Gesamtzahl der Zeilen.

  • totalBranchCount <number> Die Gesamtzahl der Verzweigungen.

  • totalFunctionCount <number> Die Gesamtzahl der Funktionen.

  • coveredLineCount <number> Die Anzahl der abgedeckten Zeilen.

  • coveredBranchCount <number> Die Anzahl der abgedeckten Verzweigungen.

  • coveredFunctionCount <number> Die Anzahl der abgedeckten Funktionen.

  • coveredLinePercent <number> Der Prozentsatz der abgedeckten Zeilen.

  • coveredBranchPercent <number> Der Prozentsatz der abgedeckten Verzweigungen.

  • coveredFunctionPercent <number> Der Prozentsatz der abgedeckten Funktionen.

  • functions <Array> Ein Array von Funktionen, das die Funktionsabdeckung darstellt.

  • name <string> Der Name der Funktion.

  • line <number> Die Zeilennummer, in der die Funktion definiert ist.

  • count <number> Die Anzahl, wie oft die Funktion aufgerufen wurde.

  • branches <Array> Ein Array von Verzweigungen, das die Verzweigungsabdeckung darstellt.

  • line <number> Die Zeilennummer, in der die Verzweigung definiert ist.

  • count <number> Die Anzahl, wie oft die Verzweigung genommen wurde.

  • lines <Array> Ein Array von Zeilen, das die Zeilennummern und die Anzahl, wie oft sie abgedeckt wurden, darstellt.

  • line <number> Die Zeilennummer.

  • count <number> Die Anzahl, wie oft die Zeile abgedeckt wurde.

  • thresholds <Object> Ein Objekt, das angibt, ob die Coverage für jeden Coverage-Typ erreicht wurde oder nicht.

  • function <number> Der Schwellenwert für die Funktionsabdeckung.

  • branch <number> Der Schwellenwert für die Verzweigungsabdeckung.

  • line <number> Der Schwellenwert für die Zeilenabdeckung.

  • totals <Object> Ein Objekt, das eine Zusammenfassung der Coverage für alle Dateien enthält.

  • totalLineCount <number> Die Gesamtzahl der Zeilen.

  • totalBranchCount <number> Die Gesamtzahl der Verzweigungen.

  • totalFunctionCount <number> Die Gesamtzahl der Funktionen.

  • coveredLineCount <number> Die Anzahl der abgedeckten Zeilen.

  • coveredBranchCount <number> Die Anzahl der abgedeckten Verzweigungen.

  • coveredFunctionCount <number> Die Anzahl der abgedeckten Funktionen.

  • coveredLinePercent <number> Der Prozentsatz der abgedeckten Zeilen.

  • coveredBranchPercent <number> Der Prozentsatz der abgedeckten Verzweigungen.

  • coveredFunctionPercent <number> Der Prozentsatz der abgedeckten Funktionen.

  • workingDirectory <string> Das Arbeitsverzeichnis, als die Codeabdeckung begann. Dies ist nützlich, um relative Pfadnamen anzuzeigen, falls die Tests das Arbeitsverzeichnis des Node.js-Prozesses geändert haben.

  • nesting <number> Die Schachtelungsebene des Tests.

Wird ausgelöst, wenn die Codeabdeckung aktiviert ist und alle Tests abgeschlossen wurden.

Ereignis: 'test:complete'

• data <Object>

  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.

  • details <Object> Zusätzliche Ausführungsmetadaten.

  • passed <boolean> Gibt an, ob der Test bestanden wurde oder nicht.

  • duration_ms <number> Die Dauer des Tests in Millisekunden.

  • error <Error> | <undefined> Ein Fehler, der den vom Test ausgelösten Fehler umschließt, wenn er nicht bestanden wurde.

  • cause <Error> Der tatsächliche vom Test ausgelöste Fehler.

  • type <string> | <undefined> Der Typ des Tests, der angibt, ob es sich um eine Suite handelt.

  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.

  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.

  • name <string> Der Name des Tests.

  • nesting <number> Die Schachtelungstiefe des Tests.

  • testNumber <number> Die Ordnungszahl des Tests.

  • todo <string> | <boolean> | <undefined> Vorhanden, wenn context.todo aufgerufen wird.

  • skip <string> | <boolean> | <undefined> Vorhanden, wenn context.skip aufgerufen wird.

Wird ausgelöst, wenn ein Test seine Ausführung abgeschlossen hat. Dieses Ereignis wird nicht in der gleichen Reihenfolge ausgelöst, in der die Tests definiert sind. Die entsprechenden deklarationsgeordneten Ereignisse sind 'test:pass' und 'test:fail'.

Ereignis: 'test:dequeue'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • name <string> Der Testname.
  • nesting <number> Die Verschachtelungsebene des Tests.

Wird ausgegeben, wenn ein Test aus der Warteschlange entfernt wird, unmittelbar bevor er ausgeführt wird. Es wird nicht garantiert, dass dieses Ereignis in der gleichen Reihenfolge ausgegeben wird, in der die Tests definiert sind. Das entsprechende Deklarationsereignis in der Reihenfolge ist 'test:start'.

Ereignis: 'test:diagnostic'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • message <string> Die Diagnosemeldung.
  • nesting <number> Die Verschachtelungsebene des Tests.

Wird ausgegeben, wenn context.diagnostic aufgerufen wird. Es wird garantiert, dass dieses Ereignis in der gleichen Reihenfolge ausgegeben wird, in der die Tests definiert sind.

Ereignis: 'test:enqueue'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • name <string> Der Name des Tests.
  • nesting <number> Die Verschachtelungsebene des Tests.

Wird ausgelöst, wenn ein Test zur Ausführung in die Warteschlange eingereiht wird.

Ereignis: 'test:fail'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • details <Object> Zusätzliche Ausführungsmetadaten.
  • duration_ms <number> Die Dauer des Tests in Millisekunden.
  • error <Error> Ein Fehler, der den vom Test ausgelösten Fehler umschließt.
  • cause <Error> Der tatsächliche Fehler, der vom Test ausgelöst wurde.
  • type <string> | <undefined> Der Typ des Tests, der verwendet wird, um anzugeben, ob es sich um eine Suite handelt.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • name <string> Der Name des Tests.
  • nesting <number> Die Verschachtelungsebene des Tests.
  • testNumber <number> Die Ordnungszahl des Tests.
  • todo <string> | <boolean> | <undefined> Vorhanden, wenn context.todo aufgerufen wird.
  • skip <string> | <boolean> | <undefined> Vorhanden, wenn context.skip aufgerufen wird.

Wird ausgelöst, wenn ein Test fehlschlägt. Dieses Ereignis wird garantiert in der gleichen Reihenfolge ausgelöst, in der die Tests definiert sind. Das entsprechende Ereignis mit Ausführungsreihenfolge ist 'test:complete'.

Ereignis: 'test:pass'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • details <Object> Zusätzliche Ausführungs-Metadaten.
  • duration_ms <number> Die Dauer des Tests in Millisekunden.
  • type <string> | <undefined> Der Typ des Tests, der verwendet wird, um anzugeben, ob es sich um eine Suite handelt.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • name <string> Der Testname.
  • nesting <number> Die Schachtelungsebene des Tests.
  • testNumber <number> Die Ordnungszahl des Tests.
  • todo <string> | <boolean> | <undefined> Vorhanden, wenn context.todo aufgerufen wird
  • skip <string> | <boolean> | <undefined> Vorhanden, wenn context.skip aufgerufen wird

Wird ausgegeben, wenn ein Test bestanden wurde. Es wird garantiert, dass dieses Ereignis in der gleichen Reihenfolge wie die Definition der Tests ausgegeben wird. Das entsprechende Ausführungsereignis in der Reihenfolge ist 'test:complete'.

Ereignis: 'test:plan'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • nesting <number> Die Verschachtelungsebene des Tests.
  • count <number> Die Anzahl der ausgeführten Untertests.

Wird ausgelöst, wenn alle Untertests für einen bestimmten Test abgeschlossen sind. Dieses Ereignis wird garantiert in der gleichen Reihenfolge wie die Definition der Tests ausgelöst.

Ereignis: 'test:start'

• data <Object>
  • column <number> | <undefined> Die Spaltennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • file <string> | <undefined> Der Pfad der Testdatei, undefined, wenn der Test über die REPL ausgeführt wurde.
  • line <number> | <undefined> Die Zeilennummer, in der der Test definiert ist, oder undefined, wenn der Test über die REPL ausgeführt wurde.
  • name <string> Der Name des Tests.
  • nesting <number> Die Verschachtelungsebene des Tests.

Wird ausgelöst, wenn ein Test mit der Meldung seines eigenen Status und dem seiner Untertests beginnt. Dieses Ereignis wird garantiert in der gleichen Reihenfolge wie die Definition der Tests ausgelöst. Das entsprechende ereignis in Ausführungsreihenfolge ist 'test:dequeue'.

Ereignis: 'test:stderr'

• data <Object>
  • file <string> Der Pfad der Testdatei.
  • message <string> Die an stderr geschriebene Nachricht.

Wird ausgelöst, wenn ein laufender Test an stderr schreibt. Dieses Ereignis wird nur ausgelöst, wenn das Flag --test übergeben wird. Es wird nicht garantiert, dass dieses Ereignis in der gleichen Reihenfolge ausgelöst wird, in der die Tests definiert sind.

Ereignis: 'test:stdout'

• data <Object>
  • file <string> Der Pfad der Testdatei.
  • message <string> Die an stdout geschriebene Nachricht.

Wird ausgelöst, wenn ein laufender Test an stdout schreibt. Dieses Ereignis wird nur ausgelöst, wenn das Flag --test übergeben wird. Es wird nicht garantiert, dass dieses Ereignis in der gleichen Reihenfolge ausgelöst wird, in der die Tests definiert sind.

Ereignis: 'test:summary'

• data <Object>

  • counts <Object> Ein Objekt, das die Anzahl der verschiedenen Testergebnisse enthält.

  • cancelled <number> Die Gesamtzahl der abgebrochenen Tests.

  • failed <number> Die Gesamtzahl der fehlgeschlagenen Tests.

  • passed <number> Die Gesamtzahl der bestandenen Tests.

  • skipped <number> Die Gesamtzahl der übersprungenen Tests.

  • suites <number> Die Gesamtzahl der ausgeführten Suiten.

  • tests <number> Die Gesamtzahl der ausgeführten Tests, ohne Suiten.

  • todo <number> Die Gesamtzahl der TODO-Tests.

  • topLevel <number> Die Gesamtzahl der Tests und Suiten auf oberster Ebene.

  • duration_ms <number> Die Dauer des Testlaufs in Millisekunden.

  • file <string> | <undefined> Der Pfad der Testdatei, die die Zusammenfassung generiert hat. Wenn die Zusammenfassung mehreren Dateien entspricht, ist dieser Wert undefined.

  • success <boolean> Gibt an, ob der Testlauf als erfolgreich betrachtet wird oder nicht. Wenn ein Fehlerzustand auftritt, z. B. ein fehlgeschlagener Test oder eine nicht erreichte Abdeckungsschwelle, wird dieser Wert auf false gesetzt.

Wird ausgelöst, wenn ein Testlauf abgeschlossen ist. Dieses Ereignis enthält Metriken zum abgeschlossenen Testlauf und ist nützlich, um festzustellen, ob ein Testlauf bestanden oder fehlgeschlagen ist. Wenn eine Testisolation auf Prozessebene verwendet wird, wird zusätzlich zu einer endgültigen kumulativen Zusammenfassung ein 'test:summary'-Ereignis für jede Testdatei generiert.

Ereignis: 'test:watch:drained'

Wird ausgelöst, wenn keine weiteren Tests in der Watch-Modus-Warteschlange zur Ausführung stehen.

Klasse: TestContext

[Verlauf]

Version	Änderungen
v20.1.0, v18.17.0	Die Funktion before wurde zu TestContext hinzugefügt.
v18.0.0, v16.17.0	Hinzugefügt in: v18.0.0, v16.17.0

Eine Instanz von TestContext wird an jede Testfunktion übergeben, um mit dem Testrunner zu interagieren. Der TestContext-Konstruktor wird jedoch nicht als Teil der API bereitgestellt.

context.before([fn][, options])

Hinzugefügt in: v20.1.0, v18.17.0

• fn <Funktion> | <AsyncFunction> Die Hook-Funktion. Das erste Argument für diese Funktion ist ein TestContext-Objekt. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-op-Funktion.
• options <Objekt> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <Zahl> Eine Anzahl von Millisekunden, nach denen der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Untertests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion wird verwendet, um einen Hook zu erstellen, der vor einem Untertest des aktuellen Tests ausgeführt wird.

context.beforeEach([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Funktion> | <AsyncFunction> Die Hook-Funktion. Das erste Argument für diese Funktion ist ein TestContext-Objekt. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-op-Funktion.
• options <Objekt> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Hooks.
  • timeout <Zahl> Eine Anzahl von Millisekunden, nach denen der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Untertests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion wird verwendet, um einen Hook zu erstellen, der vor jedem Untertest des aktuellen Tests ausgeführt wird.

test('Test auf oberster Ebene', async t => {
  t.beforeEach(t => t.diagnostic(`wird gleich ${t.name} ausführen`))
  await t.test('Dies ist ein Untertest', t => {
    assert.ok('hier eine relevante Assertion')
  })
})

context.after([fn][, options])

Hinzugefügt in: v19.3.0, v18.13.0

• fn <Funktion> | <AsyncFunction> Die Hook-Funktion. Das erste Argument dieser Funktion ist ein TestContext-Objekt. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Objekt> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Erlaubt das Abbrechen eines laufenden Hooks.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion wird verwendet, um einen Hook zu erstellen, der nach Abschluss des aktuellen Tests ausgeführt wird.

test('Test der obersten Ebene', async t => {
  t.after(t => t.diagnostic(`Beendet die Ausführung von ${t.name}`))
  assert.ok('Hier eine relevante Assertion')
})

context.afterEach([fn][, options])

Hinzugefügt in: v18.8.0, v16.18.0

• fn <Funktion> | <AsyncFunction> Die Hook-Funktion. Das erste Argument dieser Funktion ist ein TestContext-Objekt. Wenn der Hook Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.
• options <Objekt> Konfigurationsoptionen für den Hook. Die folgenden Eigenschaften werden unterstützt:
  • signal <AbortSignal> Erlaubt das Abbrechen eines laufenden Hooks.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Hook fehlschlägt. Wenn nicht angegeben, übernehmen Subtests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.

Diese Funktion wird verwendet, um einen Hook zu erstellen, der nach jedem Subtest des aktuellen Tests ausgeführt wird.

test('Test der obersten Ebene', async t => {
  t.afterEach(t => t.diagnostic(`Beendet die Ausführung von ${t.name}`))
  await t.test('Dies ist ein Subtest', t => {
    assert.ok('Hier eine relevante Assertion')
  })
})

context.assert

Hinzugefügt in: v22.2.0, v20.15.0

Ein Objekt, das Assertionsmethoden enthält, die an context gebunden sind. Die Top-Level-Funktionen des Moduls node:assert werden hier zur Erstellung von Testplänen bereitgestellt.

test('test', t => {
  t.plan(1)
  t.assert.strictEqual(true, true)
})

context.assert.snapshot(value[, options])

Hinzugefügt in: v22.3.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.0 - Frühe Entwicklung

• value <any> Ein Wert, der in eine Zeichenkette serialisiert werden soll. Wenn Node.js mit dem Flag --test-update-snapshots gestartet wurde, wird der serialisierte Wert in die Snapshot-Datei geschrieben. Andernfalls wird der serialisierte Wert mit dem entsprechenden Wert in der vorhandenen Snapshot-Datei verglichen.
• options <Object> Optionale Konfigurationsoptionen. Die folgenden Eigenschaften werden unterstützt:
  • serializers <Array> Ein Array von synchronen Funktionen, die verwendet werden, um value in eine Zeichenkette zu serialisieren. value wird als einziges Argument an die erste Serialisiererfunktion übergeben. Der Rückgabewert jedes Serialisierers wird als Eingabe an den nächsten Serialisierer übergeben. Sobald alle Serialisierer ausgeführt wurden, wird der resultierende Wert in eine Zeichenkette umgewandelt. Standard: Wenn keine Serialisierer angegeben werden, werden die Standardserialisierer des Test-Runners verwendet.

Diese Funktion implementiert Assertions für Snapshot-Tests.

test('Snapshot-Test mit Standardserialisierung', t => {
  t.assert.snapshot({ value1: 1, value2: 2 })
})

test('Snapshot-Test mit benutzerdefinierter Serialisierung', t => {
  t.assert.snapshot(
    { value3: 3, value4: 4 },
    {
      serializers: [value => JSON.stringify(value)],
    }
  )
})

context.diagnostic(message)

Hinzugefügt in: v18.0.0, v16.17.0

• message <string> Die zu meldende Nachricht.

Diese Funktion wird verwendet, um Diagnosen in die Ausgabe zu schreiben. Alle Diagnoseinformationen werden am Ende der Testergebnisse hinzugefügt. Diese Funktion gibt keinen Wert zurück.

test('top level test', t => {
  t.diagnostic('Eine diagnostische Meldung')
})

context.filePath

Hinzugefügt in: v22.6.0, v20.16.0

Der absolute Pfad der Testdatei, die den aktuellen Test erstellt hat. Wenn eine Testdatei zusätzliche Module importiert, die Tests generieren, geben die importierten Tests den Pfad der Root-Testdatei zurück.

context.fullName

Hinzugefügt in: v22.3.0

Der Name des Tests und jedes seiner Vorfahren, getrennt durch \>.

context.name

Hinzugefügt in: v18.8.0, v16.18.0

Der Name des Tests.

context.plan(count)

[Verlauf]

Version	Änderungen
v23.4.0	Diese Funktion ist nicht mehr experimentell.
v22.2.0, v20.15.0	Hinzugefügt in: v22.2.0, v20.15.0

• count <number> Die Anzahl der Assertionen und Subtests, die voraussichtlich ausgeführt werden.

Diese Funktion wird verwendet, um die Anzahl der Assertionen und Subtests festzulegen, die voraussichtlich innerhalb des Tests ausgeführt werden. Wenn die Anzahl der ausgeführten Assertionen und Subtests nicht mit der erwarteten Anzahl übereinstimmt, schlägt der Test fehl.

test('top level test', t => {
  t.plan(2)
  t.assert.ok('Einige relevante Assertion hier')
  t.test('Subtest', () => {})
})

Bei der Arbeit mit asynchronem Code kann die Funktion plan verwendet werden, um sicherzustellen, dass die korrekte Anzahl von Assertionen ausgeführt wird:

test('Planung mit Streams', (t, done) => {
  function* generate() {
    yield 'a'
    yield 'b'
    yield 'c'
  }
  const expected = ['a', 'b', 'c']
  t.plan(expected.length)
  const stream = Readable.from(generate())
  stream.on('data', chunk => {
    t.assert.strictEqual(chunk, expected.shift())
  })

  stream.on('end', () => {
    done()
  })
})

context.runOnly(shouldRunOnlyTests)

Hinzugefügt in: v18.0.0, v16.17.0

• shouldRunOnlyTests <boolean> Gibt an, ob only-Tests ausgeführt werden sollen oder nicht.

Wenn shouldRunOnlyTests einen Wahrheitwert hat, führt der Testkontext nur Tests aus, bei denen die Option only gesetzt ist. Andernfalls werden alle Tests ausgeführt. Wenn Node.js nicht mit der Befehlszeilenoption --test-only gestartet wurde, ist diese Funktion ein No-Op.

test('Test der obersten Ebene', t => {
  // Der Testkontext kann so eingestellt werden, dass Subtests mit der Option 'only' ausgeführt werden.
  t.runOnly(true)
  return Promise.all([
    t.test('Dieser Subtest wird jetzt übersprungen'),
    t.test('Dieser Subtest wird ausgeführt', { only: true }),
  ])
})

context.signal

Hinzugefügt in: v18.7.0, v16.17.0

• Typ: <AbortSignal>

Kann verwendet werden, um Test-Subtasks abzubrechen, wenn der Test abgebrochen wurde.

test('Test der obersten Ebene', async t => {
  await fetch('some/uri', { signal: t.signal })
})

context.skip([message])

Hinzugefügt in: v18.0.0, v16.17.0

• message <string> Optionale Übersprungsmeldung.

Diese Funktion bewirkt, dass die Ausgabe des Tests den Test als übersprungen kennzeichnet. Wenn message angegeben ist, wird diese in die Ausgabe aufgenommen. Das Aufrufen von skip() beendet die Ausführung der Testfunktion nicht. Diese Funktion gibt keinen Wert zurück.

test('Test der obersten Ebene', t => {
  // Stellen Sie sicher, dass Sie auch hier zurückkehren, wenn der Test zusätzliche Logik enthält.
  t.skip('Dieser wird übersprungen')
})

context.todo([message])

Hinzugefügt in: v18.0.0, v16.17.0

• message <string> Optionale TODO-Meldung.

Diese Funktion fügt der Testausgabe eine TODO-Direktive hinzu. Wenn message angegeben ist, wird diese in die Ausgabe aufgenommen. Das Aufrufen von todo() beendet die Ausführung der Testfunktion nicht. Diese Funktion gibt keinen Wert zurück.

test('Test der obersten Ebene', t => {
  // Dieser Test ist als `TODO` markiert.
  t.todo('Dies ist eine Todo')
})

context.test([name][, options][, fn])

[Historie]

Version	Änderungen
v18.8.0, v16.18.0	Füge eine signal-Option hinzu.
v18.7.0, v16.17.0	Füge eine timeout-Option hinzu.
v18.0.0, v16.17.0	Hinzugefügt in: v18.0.0, v16.17.0

• name <string> Der Name des Untertests, der bei der Meldung von Testergebnissen angezeigt wird. Standard: Die name-Eigenschaft von fn oder '\<anonymous\>', wenn fn keinen Namen hat.

• options <Object> Konfigurationsoptionen für den Untertest. Die folgenden Eigenschaften werden unterstützt:

  • concurrency <number> | <boolean> | <null> Wenn eine Zahl angegeben wird, werden so viele Tests parallel innerhalb des Anwendungsthreads ausgeführt. Wenn true, werden alle Untertests parallel ausgeführt. Wenn false, wird nur ein Test gleichzeitig ausgeführt. Wenn nicht angegeben, erben Untertests diesen Wert von ihrem übergeordneten Element. Standard: null.
  • only <boolean> Wenn wahrheitsgemäß und der Testkontext so konfiguriert ist, dass only-Tests ausgeführt werden, wird dieser Test ausgeführt. Andernfalls wird der Test übersprungen. Standard: false.
  • signal <AbortSignal> Ermöglicht das Abbrechen eines laufenden Tests.
  • skip <boolean> | <string> Wenn wahrheitsgemäß, wird der Test übersprungen. Wenn eine Zeichenkette angegeben wird, wird diese Zeichenkette in den Testergebnissen als Grund für das Überspringen des Tests angezeigt. Standard: false.
  • todo <boolean> | <string> Wenn wahrheitsgemäß, wird der Test als TODO markiert. Wenn eine Zeichenkette angegeben wird, wird diese Zeichenkette in den Testergebnissen als Grund dafür angezeigt, warum der Test TODO ist. Standard: false.
  • timeout <number> Eine Anzahl von Millisekunden, nach der der Test fehlschlägt. Wenn nicht angegeben, erben Untertests diesen Wert von ihrem übergeordneten Element. Standard: Infinity.
  • plan <number> Die Anzahl der Zusicherungen und Untertests, die voraussichtlich im Test ausgeführt werden. Wenn die Anzahl der im Test ausgeführten Zusicherungen nicht mit der im Plan angegebenen Anzahl übereinstimmt, schlägt der Test fehl. Standard: undefined.

• fn <Function> | <AsyncFunction> Die zu testende Funktion. Das erste Argument für diese Funktion ist ein TestContext-Objekt. Wenn der Test Callbacks verwendet, wird die Callback-Funktion als zweites Argument übergeben. Standard: Eine No-Op-Funktion.

• Gibt zurück: <Promise> Erfüllt mit undefined, sobald der Test abgeschlossen ist.

Diese Funktion wird verwendet, um Untertests unter dem aktuellen Test zu erstellen. Diese Funktion verhält sich auf die gleiche Weise wie die Top-Level-Funktion test().

test('Top-Level-Test', async t => {
  await t.test('Dies ist ein Untertest', { only: false, skip: false, concurrency: 1, todo: false, plan: 1 }, t => {
    t.assert.ok('hier eine relevante Zusicherung')
  })
})

Klasse: SuiteContext

Hinzugefügt in: v18.7.0, v16.17.0

Eine Instanz von SuiteContext wird an jede Suite-Funktion übergeben, um mit dem Testläufer zu interagieren. Der SuiteContext-Konstruktor ist jedoch nicht als Teil der API verfügbar.

context.filePath

Hinzugefügt in: v22.6.0

Der absolute Pfad der Testdatei, die die aktuelle Suite erstellt hat. Wenn eine Testdatei zusätzliche Module importiert, die Suiten generieren, geben die importierten Suiten den Pfad der Root-Testdatei zurück.

context.name

Hinzugefügt in: v18.8.0, v16.18.0

Der Name der Suite.

context.signal

Hinzugefügt in: v18.7.0, v16.17.0

• Typ: <AbortSignal>

Kann verwendet werden, um Testunteraufgaben abzubrechen, wenn der Test abgebrochen wurde.