1. Was ist nock und warum wird es benötigt?

nock ist eine leistungsstarke Bibliothek für Node.js, die zum Abfangen und Mocken von HTTP-Anfragen entwickelt wurde. Sie ermöglicht Entwicklern, Antworten von externen Diensten (REST-APIs, Drittanbieter-Mikrodienste, Webhooks) zu simulieren, ohne dass tatsächliche Netzwerkanfragen ausgeführt werden müssen. Dies ist besonders wichtig beim Schreiben von Unit-Tests und Integrationstests, bei denen Stabilität und Ausführungsgeschwindigkeit von entscheidender Bedeutung sind.

Warum ist das notwendig? Stellen Sie sich vor, Ihre Anwendung sendet Anfragen an ein Zahlungsgateway, eine Wetter-API oder eine Datenbank über HTTP. In einer Testumgebung möchten Sie nicht von der Verfügbarkeit dieser Dienste, ihrer Antwortgeschwindigkeit oder Anfragelimitierungen abhängig sein. nock ermöglicht es, diese Anfragen zu "ersetzen", indem vorab definierte Daten zurückgegeben werden. Das macht Tests schnell, vorhersagbar und von externen Faktoren isoliert. Darüber hinaus können Sie Fehlerszenarien (Timeouts, 500er-Codes, leere Antworten) testen, die in der realen Umgebung nur schwer reproduzierbar sind.

Im Kontext von TypeScript integriert sich nock hervorragend mit gängigen Test-Frameworks (Jest, Mocha, Vitest) und unterstützt Typisierung, was die Arbeit damit komfortabel und sicher macht. Die Bibliothek fängt Anfragen auf Node.js-Ebene ab (über das http- und https-Modul), sodass sie mit allen HTTP-Clients funktioniert: axios, node-fetch, got und sogar dem nativen fetch (mit einigen Einschränkungen).

2. Installation

Führen Sie einen der folgenden Befehle im Terminal aus, um nock in einem TypeScript-Projekt zu installieren:

# Mit npm
npm install --save-dev nock @types/nock

# Mit yarn
yarn add --dev nock @types/nock

# Mit pnpm
pnpm add --save-dev nock @types/nock

Wichtig: @types/nock enthält die Typdeklarationen für TypeScript. Wenn Sie TypeScript 4.0+ verwenden, sind die Typen möglicherweise bereits in der Bibliothek enthalten, aber aus Kompatibilitätsgründen ist es besser, sie explizit zu installieren.

3. Schnellstart

Schreiben wir einen minimalen Test, der die grundlegende Funktionsweise von nock demonstriert. Angenommen, wir haben eine Funktion, die Benutzerdaten von einer externen API abruft.

// userService.ts
import axios from 'axios';

export async function getUser(userId: number): Promise<{ id: number; name: string; email: string }> {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${userId}`);
    return response.data;
}

Jetzt schreiben wir einen Test, der diese Anfrage mockt:

// userService.test.ts
import nock from 'nock';
import { getUser } from './userService';

describe('getUser', () => {
    afterEach(() => {
        nock.cleanAll(); // Alle Mocks nach jedem Test bereinigen
    });

    it('sollte Benutzerdaten zurückgeben', async () => {
        // 1. Abfangen konfigurieren
        const mockUser = { id: 1, name: 'John Doe', email: 'john@example.com' };
        nock('https://jsonplaceholder.typicode.com')
            .get('/users/1')
            .reply(200, mockUser);

        // 2. Getestete Funktion aufrufen
        const user = await getUser(1);

        // 3. Ergebnis überprüfen
        expect(user).toEqual(mockUser);
    });

    it('sollte bei 500 einen Fehler werfen', async () => {
        nock('https://jsonplaceholder.typicode.com')
            .get('/users/1')
            .reply(500, { error: 'Server Error' });

        await expect(getUser(1)).rejects.toThrow();
    });
});

Dieses Beispiel zeigt, wie einfach es ist, Serverantworten zu ersetzen und sowohl erfolgreiche als auch fehlerhafte Szenarien zu testen.

4. Grundlegende Methoden

nock bietet eine Vielzahl von Methoden, um HTTP-Anfragen präzise zu konfigurieren. Hier sind die wichtigsten:

• nock(baseUrl): Erstellt einen neuen Interceptor für eine bestimmte Basis-URL.
• .get(path), .post(path), .put(path), .delete(path): Definiert die HTTP-Methode und den Pfad der zu mockenden Anfrage.
• .reply(statusCode, body, headers): Gibt eine Antwort mit Statuscode, Body und optionalen Headern zurück.
• .query(queryObject): Filtert Anfragen basierend auf Query-Parametern.
• .times(n): Gibt an, wie oft ein bestimmter Mock verwendet werden soll.
• .persist(): Macht einen Mock dauerhaft gültig, bis er manuell entfernt wird.

Beispiel für die Verwendung von Query-Parametern:

nock('https://api.example.com')
    .get('/search')
    .query({ q: 'TypeScript', page: 1 })
    .reply(200, { results: [] });