Mock Service Worker – Einfach Backends mocken

Der Mock Service Worker, kurz MSW, ist ein hilfreiches Werkzeug zum API Mocking bei der Entwicklung von Single Page Applications.

Beim Entwickeln einer clientseitigen Webanwendung ist die Kommunikation zwischen Frontend und Backend essenziell. Dementsprechend ist es wichtig, diese hinreichend zu testen. Das ist allerdings nicht trivial, da es etliche Fehlerszenarien gibt, die es zu beachten gilt. Darüber hinaus ist die Kommunikation asynchron, was für sich allein gestellt schon eine gewisse Komplexität mit sich bringt.

Test-Frameworks wie Jest bieten zwar eine Möglichkeit, HTTP Requests zum Server zu mocken, allerdings sind diese imperativ und damit nicht sonderlich flexibel. Eine weitere Möglichkeit ist es, einen Testserver aufzusetzen, um ein Backend zu simulieren. Das ist jedoch recht aufwändig und nicht so einfach in einer CI Pipeline zu integrieren.

Die API Mocking Library Mock Service Worker (siehe „Internetauftritt „) greift genau diese Probleme auf und bietet eine großartige Lösung. Sie verwendet das Service Worker API , um sich zwischen Frontend und Backend zu schalten. Hierdurch können Requests zum Backend abgefangen und simuliert werden. Das Beste daran ist, dass dies auf allen Ebenen der Testpyramide funktioniert und dadurch eine hohe Wiederverwendbarkeit geschaffen wird.

Den Einsatz des Mock Service Workers möchte ich anhand einer Beispielanwendung, dem „Magnificent Rick & Morty Character Wheel“ , erläutern.

Mock Service Worker: Das Backend

Als Backend verwende ich das großartige Rick-and-Morty-API . Es bietet Zugriff auf eine Datenbank für Charaktere aus dem Rick-&-Morty-Universum.

Ein Aufruf des Endpunkts https://rickandmortyapi.com/api/character liefert eine Seite mit max. 20 Ergebnissen. Zusätzlich erhalten wir Meta-Informationen, die Auskunft darüber geben, wie viele Elemente sich insgesamt auf wie vielen Seiten in der Datenbank befinden, sowie die Links zur nächsten und vorherigen Seite.

Backend-Beispiel:

1{
2  "info": {
3    "count": 671,
4    "pages": 34,
5    "next": "https://rickandmortyapi.com/api/character/?page=2",
6    "prev": null
7  },
8  "results": [
9    // ...
10  ]
11}

Das Frontend

Eine React-Anwendung soll es uns ermöglichen, die Charaktere der Datenbank anzuzeigen und über zwei Buttons zum jeweils nächsten bzw. vorherigen Charakter zu wechseln.

Eine besondere Anforderung soll sein, dass wir durch die Liste rotieren können. Das bedeutet, dass der Button „Next“ beim letzten Charakter zum ersten springt und umgekehrt. Eine klassiche Karussellfunktion also.

Die Komponente CharacterWheel erhält den jeweils aktuell gewählten Charakter und bietet Callbacks für die beiden Buttons. Bei den einzelnen Elementen der Komponente handelt es sich um Styled Components , daher die eventuell etwas verwirrenden Elementnamen.

1//components/characterwheel/characterWheel.js
2export const CharacterWheel = ({
3                                   currentCharacter,
4                                   onClickNext,
5                                   onClickPrev,
6                               }) => {
7  return (
8    <CharacterWheelDiv>
9        <Character bio={currentCharacter}/>
10        <ButtonGroup alignRight={!onClickPrev}>
11            {onClickPrev && <Button onClick={() => onClickPrev()}>Previous</Button>}
12            {onClickNext && <Button onClick={() => onClickNext()}>Next</Button>}
13        </ButtonGroup>
14    </CharacterWheelDiv>
15  );
16};

Da unsere Anwendung nur aus einer Seite besteht, wird die Komponente direkt in der Hauptseite eingebunden:

1//pages/main/index.js
2const Main = () => {
3    const [wheel] = useState(
4        new CharacterwheelService(new RickandmortyApiAdapter())
5    );
6    const [currentChar, setCurrentChar] = useState(undefined);
7
8    const init = useCallback(async () => {
9        await wheel.init();
10        setCurrentChar(await wheel.currentChar());
11    }, [setCurrentChar, wheel]);
12
13    useEffect(() => {
14        init();
15    }, [init]);
16
17    const next = async () => {
18        setCurrentChar(await wheel.nextChar());
19    };
20
21    const prev = async () => {
22        setCurrentChar(await wheel.prevChar());
23    };
24
25    return (
26        <>
27            {currentChar && (
28                <CharacterWheel
29                    currentCharacter={currentChar}
30                    onClickNext={() => next()}
31                    onClickPrev={() => prev()}
32                />
33            )}
34        </>
35    );
36};

Die Seite hat zwei Statusvariablen. Den aktuellen Charakter currentChar sowie das wheel als Instanz des  CharacterWheelService. Dieser bietet Methoden zum Abrufen des aktuellen Charakters sowie zum Vor- und Zurückwechseln.

1//service/characterwheel/index.js
2class CharacterwheelService {
3
4    // ...
5
6    currentChar = () => {
7        return this.#currentPageResults[this.#currentCharIndex];
8    };
9
10    nextChar = async () => {
11        await this.#raiseCharIndex();
12
13        return this.currentChar();
14    };
15
16    prevChar = async () => {
17        await this.#lowerCharIndex();
18
19        return this.currentChar();
20    };
21}

Der Service bindet dabei einen Adapter ein, der das Rick-and-Morty-API bedient und bei Bedarf eine neue Seite mit Charakteren abruft.

1//service/characterwheel/index.js
2class RickandmortyApiAdapter {
3    static #characterUrl = "https://rickandmortyapi.com/api/character";
4
5    // ...
6
7    //ruft eine Seite auf und liefert die Charactere als Array
8    fetchResultsOfPage = async (page) => {
9        const params = new URLSearchParams({page});
10        const response = await fetch(
11            `${RickandmortyApiAdapter.#characterUrl}?${params}`
12        );
13        const data = await response.json();
14        return data.results;
15    };
16}
17
18export default RickandmortyApiAdapter;

Einsatz in Tests

Sowohl für den Service als auch für den API-Adapter werden Integrationstests implementiert, die direkt mit dem Rick-&-Morty-API interagieren.

Adapter-Test

1//adapters/rickandmortyapiadapter/index.spec.js
2import RickandmortyApiAdapter from "./index";
3
4describe("Rick and Morty Api Adapter", () => {
5
6    //...
7
8    it("should fetch the results for a page", async () => {
9        const rickandmortyapiadapter = new RickandmortyApiAdapter();
10
11        const page34 = await rickandmortyapiadapter.fetchResultsOfPage(34);
12
13        expect(page34).toEqual(pageContentOfPage34.results);
14    });
15});
16const pageContentOfPage34 = {
17    // ...Haufenweise code nur fürs Testen    
18}

Service-Test

1//service/characterwheel/index.spec.js
2describe("CharacterWheel", () => {
3    const characterWheel = new CharacterwheelService(
4        new RickandmortyApiAdapter()
5    );
6
7    describe("after initializing", () => {
8        beforeEach(async () => {
9            await characterWheel.init();
10        });
11
12        it("returns the character with id 1 when callling current() ", () => {
13            const currentChar = characterWheel.currentChar();
14
15            expect(currentChar).toEqual(characterWithId1);
16        });
17
18        it("returns the next character when calling next()", async () => {
19            const nextChar = await characterWheel.nextChar();
20
21            expect(nextChar).toEqual(characterWithId2);
22        });
23
24        it("returns the third character when calling next() twice", async () => {
25            await characterWheel.nextChar();
26            const thirdChar = await characterWheel.nextChar();
27
28            expect(thirdChar).toEqual(characterWithId3);
29        });
30
31        it("returns the last character when calling prev()", async () => {
32            let lastChar = await characterWheel.prevChar();
33
34            expect(lastChar).toEqual(characterWithId671);
35        });
36
37        it("returns the first character when caling prev() and next()", async () => {
38            await characterWheel.prevChar();
39            const firstChar = await characterWheel.nextChar();
40
41            expect(firstChar).toEqual(characterWithId1);
42        });
43    });
44});
45
46const characterWithId1 = { /* Haufenweise Zeilen */};
47const characterWithId2 = { /* Die nur nötig sind, */};
48const characterWithId3 = { /* weil wir gegen */};
49const characterWithId671 = { /* die echte api testen */};

Beide Tests sind an sich sehr überschaubar. Allerdings arbeiten sie aktuell gegen das echte API und genau das birgt unterschiedliche Gefahrenquellen, die die Tests fehlschlagen lassen können:

• Das API könnte nicht verfügbar sein.
• Die Datenbank wird erweitert und liefert andere Metriken.
• Das API wird geändert und liefert Objekte in einem anderen Format.

Darüber hinaus arbeiten die Assertions in den Tests mit echten Objekten aus dem API. Diese sind enorm groß und blähen die Tests unnötig auf.

Ein Test, der bis zum letzen Charakter blättert, um festzustellen, ob man bei einem Aufruf von nextChar() wieder auf dem ersten Charakter landet, fehlt komplett. Diese Funktionalität wird zwar durch den letzten Test „returns the first character when caling prev() and next()“ implizit abgedeckt, allerdings wäre ein expliziter Test auch wünschenswert. Aus Perfomancegründen wurde jedoch darauf verzichtet. Schließlich müsste man über 600 Charaktere durchgehen, um wieder beim ersten zu landen.

Einführung des Mock Service Worker

Mit dem Mock Service Worker können wir den genannten Problemen entgegentreten, indem wir das Backend mocken. Das geht mit dem MSW sehr einfach. Nach der Installation mit npm install -D msw legen wir in dem Verzeichnis src/mocks
eine Datei handlers.js an, in der wir die zu mockenden Backend-Funktionen ablegen.

In unserem Fall ist das der GET-Endpunkt https://rickandmortyapi.com/api/character den ich im Abschnitt Das Backend bereits beschrieben habe. Allerdings möchten wir in unseren Tests nur zwei Charaktere zurückgeben, die wir auch selber definieren. Über das rest-Objekt, das wir aus dem Modul msw importieren, können wir sehr einfach Endpunkte erzeugen. Es genügt, die nach der entsprechenden HTTP-Methode benannte Funktion aufzurufen. In unserem Fall rest.get. Jede dieser Funktionen erhält als Parameter die URL sowie eine Callback Funktion mit den drei Parametern

• req – ein Objekt, das Informationen über den Request enthält.
• res – eine Funktion, die es ermöglicht, eine Response zu erzeugen.
• ctx – ein Hilfsobjekt, das Funktionen bietet, um die Response nach unseren Wünschen zu transformieren.

1//mocks/handlers.js
2import {rest} from "msw";
3
4export const handlers = [
5    //der zu mockende Endpunkt
6    rest.get("https://rickandmortyapi.com/api/character", (req, res, ctx) => {
7        const page = Number.parseInt(req.url.searchParams.get("page")) - 1 || 0;
8
9        return res(ctx.status(200), ctx.json(pages[page]));
10    }),
11];
12
13const pages = [
14    {
15        info: {
16            pages: 2,
17            count: 6,
18            next: "https://rickandmortyapi.com/api/character?page=2",
19            prev: null,
20        },
21        results: [
22            {
23                id: 1,
24                name: "Rick Sanchez",
25                status: "Alive",
26                species: "Human",
27                gender: "Male",
28                origin: {
29                    name: "Earth (C-137)",
30                    url: "https://rickandmortyapi.com/api/location/1",
31                },
32                image: "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
33            },
34            //...
35        ],
36    },
37
38    {
39        info: {
40            //...
41        },
42        results: [
43            //...
44        ],
45    },
46];

Damit unser Testcode statt des echten API den Handler aufruft, müssen wir Jest noch dazu bringen, den MSW-Server zu starten. Dazu legen wir zuerst im Mockverzeichnis eine Datei server.js an und registrieren die Handler am zu startenden Server.

1//mocks/server.js
2import {setupServer} from "msw/node";
3import {handlers} from "./handlers";
4
5export const server = setupServer(...handlers);

Da das Projekt mit der create-react-app erstellt wurde, gibt es bereits eine Datei setupTests.js im src Verzeichnis. (Ist dies nicht der Fall, kann man Jest auch sehr einfach so konfigurieren, dass eine Datei vor dem Start der Tests ausgeführt wird ). Diese machen wir uns zunutze, um den Server vor den Tests zu starten und danach zu beenden. Nach jedem ausgeführten Test wird die Funktion resetHandlers() aufgerufen. Diese kann in Tests benutzt werden , um definierte Handler zu überschreiben . Das ist nützlich, wenn z. B. getestet werden soll, dass ein Endpunkt einen Fehler zurückgibt. Der Aufruf ohne Parameter sorgt dafür, dass die Handler in den Ursprungsstatus zurückversetzt werden (so wie in der handlers.js definiert).

1//setupTests.js
2import {server} from "./mocks/server";
3
4beforeAll(() => server.listen());
5
6afterEach(() => server.resetHandlers());
7
8afterAll(() => server.close());

Das war es schon. Startet man nun die Tests, wird der Handler des Mock Service Workers aufgerufen und ein vom echten API entkoppeltes Testen wird ermöglicht. Es sind keine Änderungen am produktiven Code notwendig. Lediglich die Testdaten müssen etwas angepasst werden. Das Beste an der Sache ist, dass Backend Calls, für die noch keine Handler bestehen, weiterhin vom vorhandenen Backend bedient werden. Möchte ich den MSW in ein existierendes Projekt integrieren, kann ich Schritt für Schritt echte Calls durch Mocks ersetzen.

Ausblick: Möglichkeiten des Mock Service Workers

Dieses Beispiel ist nur ein kleiner Einblick in die Möglichkeiten, die der Mock Service Worker bietet. Durch die den Einsatz des Service Worker API können alle im Test gemockten auch in einen Browser geladen werden. Alles, was dafür notwendig ist, ist das Einbinden einer JavaScript-Datei im Auslieferungsverzeichnis der Webanwendung. Der Service Worker kann anschließend beim Bootstrappen der Anwendung gestartet werden und fängt alle zuvor definierten Rest Calls ab. Die Einbindung ist kinderleicht und wird durch ein npm-Skript unterstützt.

Dieser Vorteil wird erst dann ersichtlich, wenn er im Zusammenspiel mit weiteren Tools eingesetzt wird. Nutzt man z. B. Cypress zum Testen der Anwendung, kann der Mock Service Worker als zuverlässiges Backend agieren, ohne dass ein Server
notwendig ist. Aber auch bei Einsatz von Komponentenbibliotheken wie StorybookJS kann der MSW seine Stärken ausspielen. Er ermöglicht das entkoppelte Entwickeln von Komponenten, die eine Backendanbindung benötigen, ohne dass dafür extra ein Server gestartet werden muss.

Fazit

Der MSW ist ein hilfreiches Werkzeug beim Entwickeln von Single Page Applications. Gerade im Hinblick auf verteilte Systeme (Stichwort: Microservices) kann er seine Stärken ausspielen. Die Einbindung ist einfach, das API ist schnell gelernt und die Einsatzmöglichkeiten sind vielseitig. In meinem Werkzeugkasten hat er jedenfalls einen Platz gefunden.

---

Der Code zur Beispielanwendung befindet sich auf Github .