9 Assertion API

9.1 Assertions in der Softwareentwicklung

In der Softwareentwicklung besagen Assertions Fakten über Werte oder Codeabschnitte, die wahr sein müssen. Wenn sie nicht wahr sind, wird eine Ausnahme ausgelöst. Node.js unterstützt Assertions über sein eingebautes Modul assert – zum Beispiel:

import * as assert from 'assert/strict';
assert.equal(3 + 5, 8);

Diese Assertion besagt, dass das erwartete Ergebnis von 3 plus 5 gleich 8 ist. Die Importanweisung verwendet die empfohlene strict-Version von assert.

9.2 Wie Assertions in diesem Buch verwendet werden

In diesem Buch werden Assertions auf zwei Arten verwendet: um Ergebnisse in Codebeispielen zu dokumentieren und um testgetriebene Übungen zu implementieren.

9.2.1 Ergebnisse in Codebeispielen mit Assertions dokumentieren

In Codebeispielen drücken Assertions erwartete Ergebnisse aus. Nehmen wir zum Beispiel die folgende Funktion:

function id(x) {
  return x;
}

id() gibt seinen Parameter zurück. Wir können sie in Aktion zeigen, indem wir eine Assertion verwenden:

assert.equal(id('abc'), 'abc');

In den Beispielen lasse ich die Anweisung zum Importieren von assert normalerweise weg.

Die Motivation hinter der Verwendung von Assertions ist:

• Man kann genau angeben, was erwartet wird.
• Codebeispiele können automatisch getestet werden, was sicherstellt, dass sie tatsächlich funktionieren.

9.2.2 Testgetriebene Übungen mit Assertions implementieren

Die Übungen für dieses Buch sind testgetrieben, über das Testframework Mocha. Die Prüfungen innerhalb der Tests erfolgen über Methoden von assert.

Das Folgende ist ein Beispiel für einen solchen Test:

// For the exercise, you must implement the function hello().
// The test checks if you have done it properly.
test('First exercise', () => {
  assert.equal(hello('world'), 'Hello world!');
  assert.equal(hello('Jane'), 'Hello Jane!');
  assert.equal(hello('John'), 'Hello John!');
  assert.equal(hello(''), 'Hello !');
});

Weitere Informationen finden Sie in §10 „Erste Schritte mit Quizzes und Übungen“.

9.3 Normaler Vergleich vs. tiefer Vergleich

Das strenge equal() verwendet === zum Vergleichen von Werten. Daher ist ein Objekt nur mit sich selbst gleich – selbst wenn ein anderes Objekt den gleichen Inhalt hat (da === nicht den Inhalt von Objekten vergleicht, sondern nur ihre Identitäten).

assert.notEqual({foo: 1}, {foo: 1});

deepEqual() ist die bessere Wahl zum Vergleichen von Objekten.

assert.deepEqual({foo: 1}, {foo: 1});

Diese Methode funktioniert auch für Arrays.

assert.notEqual(['a', 'b', 'c'], ['a', 'b', 'c']);
assert.deepEqual(['a', 'b', 'c'], ['a', 'b', 'c']);

9.4 Kurzübersicht: Modul assert

Für die vollständige Dokumentation siehe die Node.js-Dokumentation.

9.4.1 Normale Gleichheit

• function equal(actual: any, expected: any, message?: string): void

  actual === expected muss true sein. Andernfalls wird eine AssertionError ausgelöst.

  assert.equal(3+3, 6);

• function notEqual(actual: any, expected: any, message?: string): void

  actual !== expected muss true sein. Andernfalls wird eine AssertionError ausgelöst.

  assert.notEqual(3+3, 22);

Der optionale letzte Parameter message kann verwendet werden, um zu erklären, was assertiert wird. Wenn die Assertion fehlschlägt, wird die Nachricht verwendet, um die ausgelöste AssertionError zu erstellen.

let e;
try {
  const x = 3;
  assert.equal(x, 8, 'x must be equal to 8')
} catch (err) {
  assert.equal(
    String(err),
    'AssertionError [ERR_ASSERTION]: x must be equal to 8');
}

9.4.2 Tiefe Gleichheit

• function deepEqual(actual: any, expected: any, message?: string): void

  actual muss tief gleich expected sein. Andernfalls wird eine AssertionError ausgelöst.

  assert.deepEqual([1,2,3], [1,2,3]);
  assert.deepEqual([], []);
  
  // To .equal(), an object is only equal to itself:
  assert.notEqual([], []);

• function notDeepEqual(actual: any, expected: any, message?: string): void

  actual darf nicht tief gleich expected sein. Andernfalls wird eine AssertionError ausgelöst.

  assert.notDeepEqual([1,2,3], [1,2]);

9.4.3 Erwarten von Ausnahmen

Wenn Sie eine Ausnahme erhalten möchten (oder erwarten), benötigen Sie throws(): Diese Funktion ruft ihren ersten Parameter, die Funktion block, auf und ist nur erfolgreich, wenn sie eine Ausnahme auslöst. Zusätzliche Parameter können verwendet werden, um anzugeben, wie die Ausnahme aussehen muss.

• function throws(block: Function, message?: string): void

  assert.throws(
    () => {
      null.prop;
    }
  );

• function throws(block: Function, error: Function, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    TypeError
  );

• function throws(block: Function, error: RegExp, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    /^TypeError: Cannot read properties of null \(reading 'prop'\)$/
  );

• function throws(block: Function, error: Object, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    {
      name: 'TypeError',
      message: "Cannot read properties of null (reading 'prop')",
    }
  );

9.4.4 Eine weitere Hilfsfunktion

• function fail(message: string | Error): never

  Löst immer eine AssertionError aus, wenn sie aufgerufen wird. Das ist gelegentlich nützlich für Unit-Tests.

  try {
    functionThatShouldThrow();
    assert.fail();
  } catch (_) {
    // Success
  }