Jedes Test-Framework, das Sie verwendet haben, sei es Jest, Mocha oder node:test, basiert auf einer einfachen Idee: Sagen Sie, was Sie erwarten, und werfen Sie dann einen Fehler, wenn die Realität nicht übereinstimmt. Node.js liefert diese Idee als eingebautes Modul namens assert. Keine Installation, keine Abhängigkeit, einfach require es und beginnen Sie, Annahmen zu überprüfen.
Das assert-Modul ist an sich schon wissenswert. Es ermöglicht schnelle Plausibilitätsprüfungen in Skripten, es untermauert viele Test-Runner und es lehrt Sie, was eine Assertion tatsächlich ist, bevor ein Framework sie ausschmückt. Dieser Leitfaden behandelt die wichtigen Methoden, den Unterschied zwischen Strict- und Legacy-Modus, der viele stolpern lässt, wie man Fehler und asynchronen Code überprüft und wie dasselbe Modul Ihnen hilft, API-Antworten zu validieren.
Was das assert-Modul tut
Eine Assertion ist eine Aussage, die wahr sein muss, damit Ihr Programm als korrekt gilt. Wenn Sie assert.strictEqual(total, 100) schreiben, erklären Sie, dass total gleich 100 sein sollte. Wenn dies der Fall ist, passiert nichts und die Ausführung wird fortgesetzt. Wenn nicht, wirft assert einen AssertionError, der die Ausführung stoppt und Ihnen mitteilt, was schiefgelaufen ist.
Importieren Sie das Modul. Die moderne, empfohlene Form ist die strikte Version:
const assert = require('node:assert/strict');
// or with ES modules:
// import assert from 'node:assert/strict';
Die einfachste Assertion prüft, ob ein Wert wahr (truthy) ist:
const user = getUser(42);
assert(user, 'getUser should return a user object');
Das erste Argument ist der zu testende Wert. Das zweite, optionale, ist eine Meldung, die angezeigt wird, wenn die Assertion fehlschlägt. Schreiben Sie diese Meldung immer. Ein Fehler, der besagt „getUser sollte ein Benutzerobjekt zurückgeben“, ist weitaus nützlicher als ein bloßer AssertionError. Das Verständnis von Assertions hilft auch, wenn Sie zu dedizierten API-Assertions in einem Testwerkzeug übergehen.
Strikter Modus versus Legacy-Modus
Dies ist das Wichtigste, was man richtig machen muss. Das assert-Modul hat zwei Modi.
Der Legacy-Modus, den Sie mit require('node:assert') erhalten, verwendet lose Gleichheit (==) für assert.equal und assert.deepEqual. Das bedeutet, dass assert.equal(1, '1') durchgeht, weil 1 == '1' in JavaScript wahr ist. Lose Gleichheit ist eine bekannte Fehlerquelle.
Der strikte Modus, den Sie mit require('node:assert/strict') erhalten, verwendet für alles strikte Gleichheit (===). assert.equal(1, '1') schlägt fehl, wie es sein sollte, weil die Typen unterschiedlich sind.
const looseAssert = require('node:assert');
looseAssert.equal(1, '1'); // passes, surprising and dangerous
const strict = require('node:assert/strict');
strict.equal(1, '1'); // throws AssertionError, correct
Verwenden Sie den strikten Modus. Es gibt keinen guten Grund, lose Gleichheit in Tests zu akzeptieren. Der Rest dieses Leitfadens geht von node:assert/strict aus, wobei assert.equal sich wie assert.strictEqual verhält.
Werte vergleichen: equal und strictEqual
assert.strictEqual(actual, expected) prüft, ob zwei Werte mit === identisch sind. Es ist das „Arbeitspferd“ für Primitive wie Zahlen, Zeichenketten und Booleans.
const assert = require('node:assert/strict');
function priceWithTax(price, rate) {
return price + price * rate;
}
assert.strictEqual(priceWithTax(100, 0.08), 108, 'tax calc should add 8 percent');
assert.strictEqual(typeof priceWithTax(100, 0.08), 'number', 'result should be a number');
Es gibt auch assert.notStrictEqual, das bestanden wird, wenn die beiden Werte nicht identisch sind. Verwenden Sie es, um zu bestätigen, dass ein Wert geändert wurde:
const before = getCacheKey();
refreshCache();
const after = getCacheKey();
assert.notStrictEqual(before, after, 'cache key should change after refresh');
Für Objekte und Arrays ist strictEqual nicht hilfreich. Zwei Objektliterale mit demselben Inhalt sind unterschiedliche Referenzen, daher gibt === false zurück. Dafür ist tiefe Gleichheit da.
Objekte vergleichen: deepStrictEqual
assert.deepStrictEqual(actual, expected) vergleicht Struktur und Werte rekursiv. Zwei Objekte bestehen, wenn jeder Schlüssel einen strikt gleichen Wert enthält, und das durch alle Ebenen.
const assert = require('node:assert/strict');
function buildOrder(id, items) {
return { id, items, status: 'pending' };
}
assert.deepStrictEqual(
buildOrder(7, ['keyboard', 'mouse']),
{ id: 7, items: ['keyboard', 'mouse'], status: 'pending' },
'order object should match expected shape'
);
Dies ist die Methode, die Sie am häufigsten verwenden werden, wenn Sie Funktionen testen, die Objekte zurückgeben, und insbesondere beim Testen von API-Antworten, da JSON-Bodies Objekte sind. Ihr Gegenstück assert.notDeepStrictEqual besteht, wenn die Strukturen unterschiedlich sind.
Ein Vorbehalt: deepStrictEqual prüft auch die Typen. Eine Eigenschaft, die die Zahl 7 enthält, stimmt nicht mit einer Eigenschaft überein, die die Zeichenkette '7' enthält. Diese Strenge ist ein Feature; sie fängt Typen-Drift in Ihren Daten ab. Wenn Sie Funktionen mit vielen Eingabekombinationen testen, zeigt unser Leitfaden zu datengesteuertem Testen mit CSV und JSON, wie Sie Assertions über Datensätze hinweg skalieren können.
Wenn deepStrictEqual fehlschlägt, gibt Node einen Diff aus, der genau hervorhebt, welche Eigenschaften nicht übereinstimmen. Dieser Diff ist eine der nützlichsten Funktionen des Moduls. Anstatt zwei große Objekte anzustarren, um den Unterschied zu erkennen, lesen Sie ein paar hervorgehobene Zeilen. Für verschachtelte Daten rechtfertigt das allein die Verwendung von deepStrictEqual gegenüber dem manuellen Prüfen jedes Feldes mit strictEqual.
Partielles Matching mit assert.match und assert.ok
Nicht jede Prüfung erfordert volle Gleichheit. Manchmal interessiert es Sie nur, ob ein Wert ungefähr richtig aussieht. assert.ok(value) besteht, wann immer der Wert wahr (truthy) ist, was das richtige Werkzeug für „dies sollte existieren“-Prüfungen ist: eine nicht-leere Zeichenkette, ein definiertes Objekt, eine nicht-null Anzahl.
assert.match(string, regexp) prüft, ob eine Zeichenkette einem regulären Ausdruck entspricht, und assert.doesNotMatch prüft das Gegenteil. Diese sind nützlich für Werte, deren genauer Inhalt variiert, deren Form aber fest ist.
const assert = require('node:assert/strict');
function generateOrderId() {
return 'ORD-' + Date.now();
}
const id = generateOrderId();
// the exact timestamp changes, so assert the format, not the value
assert.match(id, /^ORD-\d+$/, 'order id should be ORD- followed by digits');
assert.ok(id.length > 4, 'order id should not be empty');
Dieses Muster ist besonders wichtig für API-Tests, bei denen Antworten Zeitstempel, generierte IDs und Token enthalten, die Sie nicht vorhersagen können. Sie überprüfen das Format mit match und die Existenz mit ok, und Sie reservieren strictEqual für die Werte, die Sie tatsächlich kontrollieren.
Prüfen, ob Code Fehler wirft
Manchmal bedeutet korrektes Verhalten das Werfen eines Fehlers. assert.throws(fn, expectedError) führt eine Funktion aus und besteht nur, wenn diese einen Fehler wirft.
const assert = require('node:assert/strict');
function parsePort(value) {
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new RangeError('port must be an integer between 1 and 65535');
}
return port;
}
// passes: invalid input should throw a RangeError
assert.throws(
() => parsePort('70000'),
RangeError,
'out-of-range port should throw RangeError'
);
// you can also match the error message with a regex
assert.throws(
() => parsePort('abc'),
/must be an integer/,
'non-numeric port should throw a descriptive error'
);
// passes: valid input should not throw
assert.doesNotThrow(
() => parsePort('8080'),
'a valid port should not throw'
);
Beachten Sie, dass Sie eine Funktion übergeben, nicht einen Aufruf. assert.throws(parsePort('70000')) würde parsePort ausführen, bevor assert es jemals sieht, und der Fehler würde unaufgefangen entweichen. Wickeln Sie es immer ein: () => parsePort('70000').
Prüfen von asynchronem Code: rejects
Moderner Node.js-Code ist voller Promises, und eine abgelehnte Promise ist das asynchrone Äquivalent eines geworfenen Fehlers. assert.rejects und assert.doesNotReject behandeln diesen Fall. Beide geben Promises zurück, daher müssen Sie sie awaiten.
const assert = require('node:assert/strict');
async function fetchUser(id) {
if (typeof id !== 'number') {
throw new TypeError('id must be a number');
}
// ... real lookup would go here
return { id, name: 'Dana Lee' };
}
async function runTests() {
// passes: bad input rejects with a TypeError
await assert.rejects(
fetchUser('not-a-number'),
TypeError,
'string id should reject'
);
// passes: good input resolves without rejecting
await assert.doesNotReject(
fetchUser(101),
'valid id should resolve cleanly'
);
}
runTests();
Das Vergessen, einen assert.rejects-Aufruf zu awaiten, ist ein häufiger Fehler. Ohne await wird die Testfunktion beendet, bevor die Assertion abgeschlossen ist, und ein Fehlschlag wird zu einer unbehandelten Ablehnung anstelle eines klaren Testfehlers.
Assert zur Überprüfung von API-Antworten verwenden
Das assert-Modul ist wirklich nützlich, um die Ausgabe einer HTTP-Anfrage zu überprüfen. Nachdem Sie einen Endpunkt abgerufen haben, erhalten Sie einen Statuscode und einen JSON-Body, und beides sind Dinge, auf die Sie Assertions anwenden können.
const assert = require('node:assert/strict');
async function testGetUser() {
const res = await fetch('https://api.example.com/users/101');
// check the status code
assert.strictEqual(res.status, 200, 'GET /users/101 should return 200');
const body = await res.json();
// check the shape and types of the response
assert.strictEqual(typeof body.id, 'number', 'id should be a number');
assert.strictEqual(body.id, 101, 'id should match the requested user');
assert.ok(body.name, 'response should include a name');
assert.ok(Array.isArray(body.roles), 'roles should be an array');
}
testGetUser().then(
() => console.log('API test passed'),
(err) => { console.error('API test failed:', err.message); process.exitCode = 1; }
);
Dieses Muster funktioniert und lehrt die Grundlagen. Für eine echte API-Testsuite benötigen Sie jedoch strukturierte Ausführungen, Wiederholungen, Umgebungsbehandlung und Berichte, die reines assert nicht bietet. Unsere Leitfäden zum Schreiben automatisierter Testskripte und zum pytest API-Automatisierungsframework behandeln diesen nächsten Schritt.
Wenn Sie lieber kein Test-Framework von Hand erstellen möchten, können Sie mit Apidog API-Anfragen definieren und visuelle Assertions für Statuscodes, Header und JSON-Felder anfügen, ohne überhaupt Assertion-Code schreiben zu müssen. Sie können Anfragen zu automatisierten Testszenarien verketten, diese in CI/CD ausführen und immer noch auf benutzerdefinierte Skripte zurückgreifen, wenn Sie die Kontrolle benötigen, die assert Ihnen bietet. Es ist ein schnellerer Weg von „Ich habe einen Endpunkt“ zu „Ich habe eine Testsuite“, und Sie können Apidog herunterladen und kostenlos nutzen. Zusammen mit Apidog deckt das Node.js assert-Modul sowohl schnelle Prüfungen als auch vollständige Suiten ab.
Häufig gestellte Fragen
Muss ich das assert-Modul installieren?
Nein. assert ist in Node.js eingebaut. Importieren Sie es mit require('node:assert/strict') oder require('node:assert'). Es gibt kein npm-Paket zu installieren und keine Abhängigkeit zu verwalten. Das Präfix node: macht explizit, dass Sie ein Kernmodul laden.
Was ist der Unterschied zwischen assert.equal und assert.strictEqual?
Im Legacy-Modus verwendet assert.equal lose Gleichheit (==) und assert.strictEqual verwendet strikte Gleichheit (===). Im strikten Modus, geladen über node:assert/strict, verhält sich assert.equal identisch zu assert.strictEqual. Verwenden Sie immer den strikten Modus, damit Typumwandlung niemals stillschweigend einen Test besteht.
Wann sollte ich deepStrictEqual anstelle von strictEqual verwenden?
Verwenden Sie strictEqual für Primitive: Zahlen, Zeichenketten, Booleans. Verwenden Sie deepStrictEqual für Objekte und Arrays, da strictEqual Referenzen vergleicht und zwei getrennte Objekte niemals referenzgleich sind. Jedes Mal, wenn Sie eine Assertion auf einen JSON-Body oder ein zurückgegebenes Objekt anwenden, greifen Sie zu deepStrictEqual.
Sollte ich das assert-Modul oder ein Test-Framework wie Jest verwenden?
Für schnelle Skripte und zum Lernen ist reines assert in Ordnung. Für eine echte Testsuite verwenden Sie ein Framework. Node.js liefert auch einen eingebauten Test-Runner, node:test, der natürlich mit assert zusammenarbeitet und Ihnen Testorganisation, Berichterstattung und Parallelität ohne externe Abhängigkeit bietet.
Wie prüfe ich, ob eine asynchrone Funktion abgelehnt wird?
Verwenden Sie assert.rejects und denken Sie daran, es zu awaiten. Übergeben Sie die Promise oder einen asynchronen Funktionsaufruf, optional mit einem erwarteten Fehlertyp oder einer Fehlermeldungs-Regex. assert.rejects(somePromise, TypeError) besteht nur, wenn die Promise mit einem TypeError abgelehnt wird. Ohne await wird ein Fehlschlag zu einer unbehandelten Ablehnung anstatt eines klaren Assertionsfehlers.