@xstate/test mit TestCafe: 3 Probleme, auf die wir gestossen sind — und ihre Lösungen

«Vorab: In diesem Artikel erkläre ich weder, wie du XState verwendest, noch was State Charts sind. Falls du Lernmaterial zu XState suchst: David Khourshid hat eine aktuelle Liste mit Ressourcen zusammengestellt.»
Bei smartive wollen wir unseren Tech Stack stetig verbessern. Als mir mein Kollege Robert Vogt Anfang 2019 von XState und seinen Vorteilen erzählt hat, war ich deshalb fast sofort Feuer und Flamme. XState macht App-Logik verständlicher: Es beschreibt deklarativ, was passieren soll, wenn Events eintreten, und in welchem expliziten State die App danach ist.
Wir haben schnell gemerkt, dass wir mit XState hochwertigere Apps bauen können, die sich leichter erweitern und besser warten lassen und am Ende besser skalieren.
Seit 2019 entwickeln wir Apps für unsere Kund*innen mit XState und wollten nie mehr zurück. Zwei Beispiele sind die Payment- und Lagerverwaltungs-App von subsidia und die Supply Chain App, die wir für die Migros entwickelt haben.
Als David Khourshid sein Package @xstate/test veröffentlicht hat, das einen modellbasierten Testansatz ermöglicht, haben wir damit in Side Projects experimentiert, um unser Testing zu vereinfachen. @xstate/test nimmt eine bereits definierte State Machine und testet entlang ihrer Pfade. Damit deckst du (fast) alle deine Use Cases ab, verbesserst deine Tests und brauchst weniger Zeit, um sie zu implementieren.
Natürlich wollten wir @xstate/test auch in freier Wildbahn einsetzen. Im Sommer 2020 wollte subsidia, eine unserer Kundinnen und Early Adopterin von XState, dass wir Teile ihrer neu gebauten Back-Office-App mit @xstate/test testen. Ihre Apps sind mit der Zeit ziemlich gewachsen, und mit einem klassischen Frontend-Testansatz kann es gut sein, dass ein Fall durch die Maschen fällt. Und wer alle möglichen Fälle testen will, braucht sehr viel Zeit, um alle Tests von Hand zu schreiben. Darum sollten wir @xstate/test integrieren und ihnen so das Leben leichter machen.
Der Testfall
Nehmen wir an, wir müssten eine App bauen, mit der du nach Personen suchen kannst. Sie soll folgende Funktionen abdecken:
- Zu Beginn 10 Personen auflisten
- Wenn möglich, 10 weitere Personen laden (Pagination)
- Nach einer bestimmten Person suchen (mit Debounce, um unnötige API Requests zu vermeiden)
- Bei einem Netzwerkproblem einen Fehler anzeigen
- Einen Hinweis anzeigen, wenn es keine Resultate gibt
- Einen Button zum Zurückspringen nach oben anzeigen, wenn keine weiteren Personen geladen werden können
Aus diesen Anforderungen haben wir die folgende State Machine abgeleitet:

Der Anfang
Laut dem @xstate/test Quick Start gibt es die createModel-Funktion, die eine beliebige State Machine entgegennimmt und dafür Testpfad-Pläne generiert. Das erzeugte Model stellt zwei Funktionen bereit, mit denen sich diese Pläne generieren und die State Machine deiner App testen lassen. Einerseits gibt es getSimplePathPlans, das alle einfachen Pfade zurückgibt. Einfache Pfade führen vom Initial State zu jedem anderen State, über jeden möglichen anderen State. Andererseits gibt es getShortestPathPlans, das die kürzesten Pfade vom Initial State zu jedem anderen State liefert.
Für unseren Fall haben wir uns für getSimplePathPlans entschieden, weil wir jede mögliche Kombination von State-Übergängen testen wollen. Und genau da stossen wir auf unser erstes Problem: die guards.
Das guards-Problem
Mit createModel wird die State Machine im Kontext des Test-Frameworks ausgeführt, ohne dass echte Services aufgerufen werden. Das ist ein Problem, denn die Services holen in der Regel Daten, die den context verändern und damit das Resultat eines Guards bestimmen. Der Aufruf von getSimplePathPlans scheitert also entweder an einem bestimmten Guard, weil keine echten Daten vorhanden sind, oder der Guard gibt seinen Default-Wert zurück. Dann werden nicht alle Pfade generiert und folglich auch nicht alle verfügbaren Pfade getestet.
Deshalb haben wir eine Funktion gebaut, die Guard-Kombinationen berechnet: Sie nimmt ein Guards-Objekt entgegen und gibt ein Array mit allen möglichen Kombinationen der Guards zurück. Im Grunde baut sie eine einfache Binärtabelle (oder eine Wahrheitstabelle für logisches or), in der jede 0 oder 1 ein mögliches Resultat einer Guard-Funktion ist. Damit es greifbarer wird, nehmen wir die guards aus der Personensuche-App:
const guards = {
hasQuery: ({ query }) => query !== null,
hasMore: (_, event) => isPeopleDoneEvent(event) && !!event.data.next,
hasPeople: (_, event) => isPeopleDoneEvent(event) && event.data.count > 0,
}Jede der obigen guard-Funktionen kann entweder false oder true (0 oder 1) zurückgeben und damit zu einem anderen Pfad im State Chart führen. Wenn aber keine Daten da sind, weil beim Auswerten der State Machine kein echter Service aufgerufen wird, können zum Beispiel query oder event.data nie definiert sein. Darum haben wir eine Funktion gebaut, die das Guards-Objekt nimmt und ein Array mit allen möglichen Kombinationen erstellt:
const guardCombinations = [
{
hasQuery: () => false,
hasMore: () => false,
hasPeople: () => false,
},
{
hasQuery: () => true,
hasMore: () => false,
hasPeople: () => false,
},
{
hasQuery: () => false,
hasMore: () => true,
hasPeople: () => false,
},
{
hasQuery: () => false,
hasMore: () => false,
hasPeople: () => true,
},
{
hasQuery: () => true,
hasMore: () => true,
hasPeople: () => false,
},
// and so forth...
];Jetzt können wir über das Array iterieren und für jede Kombination Pfad-Pläne zum Testen generieren, indem wir die generierten Guards als Config in die Machine geben.
const testPlans = guardCombinations.reduce((plans, guards) => [
...plans,
...createModel(Machine(statechartToTest, { guards }))
.withEvents(testEvents)
.getSimplePathPlans(),
], []);Endlich haben wir alle unsere Pfad-Pläne. Aber wie testet @xstate/test sie eigentlich?
Das meta-Problem
Aus dem @xstate/test Quick Start wissen wir, dass wir jedem State, den wir testen wollen, eine meta-Property hinzufügen müssen. Das State Chart der Personensuche würde also so aussehen:
const statechart = {
// ...
id: "PeopleMachine",
initial: "Fetching",
states: {
Fetching: {
// ...
meta: {
test: ({ t }) =>
t.expect(Page.Items.count).eql(0).expect(Page.Loading.exists).ok(),
},
},
Idle: {
// ...
initial: "More",
states: {
More: {
// ...
meta: {
test: ({ t }) =>
t
.expect(Page.Items.count)
.eql(10)
.expect(Page.MoreButton.exists)
.ok(),
},
},
End: {
// ...
meta: {
test: ({ t }) =>
t
.expect(Page.Items.count)
.gt(0)
.expect(Page.MoreButton.exists)
.notOk()
.expect(Page.GoToTopButton.exists)
.ok(),
},
},
NoResults: {
// ...
meta: {
test: ({ t }) =>
t
.expect(Page.Items.count)
.eql(0)
.expect(Page.NoResults.exists)
.ok(),
},
},
},
},
// ...
},
};Wir wollen aber keinen Testcode in unseren State Charts haben, denn der landet sonst im Browser der User. Deshalb möchten wir den meta-Code auslagern und programmatisch an das State Chart anhängen, damit wir den Testcode separat schreiben können:
const tests: StatesTestFunctions<Context, TestContext> = {
Fetching: ({ t }) =>
t.expect(Page.Items.count).eql(0).expect(Page.Loading.exists).ok(),
Idle: {
More: ({ t }) =>
t.expect(Page.Items.count).eql(10).expect(Page.MoreButton.exists).ok(),
End: ({ t }) =>
t
.expect(Page.Items.count)
.gt(0)
.expect(Page.MoreButton.exists)
.notOk()
.expect(Page.GoToTopButton.exists)
.ok(),
NoResults: ({ t }) =>
t.expect(Page.Items.count).eql(0).expect(Page.NoResults.exists).ok(),
},
// ... additional state tests
};Tim Deschryver hat einen sehr schönen Artikel darüber geschrieben, wie er das in Kombination mit Cypress gelöst hat. Wir haben seinen Ansatz als Basis genommen, die obige Logik für Guard-Kombinationen und einen Logging-Mechanismus ergänzt und das Ganze als Package namens @smartive/xstate-test-toolbox veröffentlicht.
Dieses Package enthält den Helper createTestPlans, den du mit xstate und xstate/test verwenden kannst.
Mit der Funktion createTestPlans aus dem Package konnten wir alle möglichen Testpfade für unsere State Machines generieren:
const tests = {
Fetching: ({ t }) =>
t.expect(Page.Items.count).eql(0).expect(Page.Loading.exists).ok(),
// ...
};
const testEvents = {
/* Will be discussed in the next section. */
};
const testPlans = createTestPlans({ machine, tests, testEvents });
// Iterate over plans and test paths
testPlans.forEach(({ description: plan, paths }) => {
fixture(plan).page("<http://localhost:8080>");
paths.forEach(({ test: run, description: path }) => {
test(`via ${path} ⬏`, (t) => run({ plan, path, t }));
});
});Jetzt haben wir also alle Tests aus unseren State Charts generiert, und wie von Zauberhand wird alles getestet. Na ja, nicht ganz. Weil @xstate/test von uns erwartet, dass wir definieren, welches User-Event oder andere Event einen State-Wechsel auslöst, sind wir auf das nächste Problem gestossen.
Das async-Problem
Die Idee hinter @xstate/test ist, dass wir definieren, was im State X getestet werden soll und welche Aktion (z. B. ein Klick auf einen Button) die App in den nächsten State Y bringt. Wie testen wir also aufgerufene Services?
Nehmen wir als Beispiel das folgende State Chart:

Mit diesem Testcode:
const tests = {
idle: ({ t }) =>
t.expect(Selector('[data-test="idle"]').exists).ok(),
loading: ({ t }) =>
t.expect(Selector('[data-test="loading"]').exists).ok(),
success: ({ t }) =>
t.expect(Selector('[data-test="success"]').exists).ok(),
failure: ({ t }) =>
t.expect(Selector('[data-test="failure"]').exists).ok(),
};
const testEvents = {
FETCH: ({ t }) => t.click('[data-test="fetch"]'),
"done.invoke.fetch": /* What action can we trigger here? */,
"error.platform.fetch": /* Or here? */,
};In unserem Initial State idle testen wir, ob das User Interface irgendein Idle-Element anzeigt. Für den Übergang von idle zu loading sagen wir @xstate/test, dass es auf das Element mit dem Selektor [data-test="fetch"] klicken soll, um in der App das Event FETCH auszulösen. Wie erwartet ruft der State loading den Service fetch auf und würde direkt zu success übergehen. Das führt aber zu zwei Problemen:
- Wie können wir den State
loadingdeterministisch testen? - Welche Aktion (z. B. Klick, Tippen usw.) müssen wir in unserem Test-Event
done.invoke.fetchdefinieren, damit das User Interface und die zugrunde liegende State Machine vonloadingzusuccesswechseln?
Das obige Beispiel ist ein typischer Use Case in Apps, die mit XState gebaut sind. Um dieses Problem mit TestCafe zu lösen, haben wir ein weiteres Package namens @smartive/testcafe-utils veröffentlicht, das Util-Klassen und -Funktionen enthält.
Neben anderen Funktionen und Klassen enthält das Package eine Interceptor-Klasse für XHR-Calls, die du so initialisieren kannst:
const xhrInterceptor = new XHRInterceptor({
fetch: {
method: "GET",
pattern: /.*\\/fetch\\/?.*/,
},
});Diese lässt sich dann mithilfe der clientScripts von TestCafe einschleusen, bevor unsere App lädt, etwa so: test.clientScripts([xhrInterceptor.clientScript()]). Jetzt wird jeder Call auf .../fetch abgefangen und bleibt unaufgelöst, bis xhrInterceptor.resolve aufgerufen wird. Damit können wir Aktionen für Invoke-Events wie das obige definieren. Jetzt können wir schreiben:
const testEvents = {
FETCH: ({ t }) => t.click('[data-test="fetch"]'),
"done.invoke.fetch": xhrInterceptor.resolve("fetch"),
"error.platform.fetch": xhrInterceptor.resolve("fetch"),
};Das Resultat
Den ganzen Code der obigen App findest du auf GitHub. Dort gibt es auch einen Workflow, der die generierten Tests erfolgreich ausführt. Zusätzlich kannst du mit der App auf CodeSandbox herumspielen oder sie dir einfach auf Vercel anschauen.
Für alle, die ein Beispiel aus der «echten Welt» sehen möchten: Ich habe das Repo cypress-realworld-app geforkt und @xstate/test und TestCafe obendrauf gesetzt. Du findest das Ganze als Pull Request auf meinen Fork der App. Der Pull Request ist in zwei Commits aufgeteilt: Der erste enthält Änderungen, die nötig waren, um die Testbarkeit der App zu verbessern. (Ich habe Kommentare hinzugefügt, die erklären, warum es die Änderungen braucht.) Der zweite Commit enthält den eigentlichen Testcode. Kommentare oder Fragen zum Pull Request sind herzlich willkommen.
Fazit
Beim Schreiben der Tests für unsere Kundin haben wir das guards-, das meta- und das async-Problem gelöst. Dabei haben wir auch gemerkt, dass mehrere States keine passende Darstellung im UI hatten und so, wie sie implementiert waren, nicht getestet werden konnten. Deshalb mussten wir zusätzliche UI-Elemente einbauen und die State Machine teilweise anpassen. Am Ende hat das insgesamt zu einer besseren, zuverlässigeren und stabileren User Experience geführt.
Wenn du XState bereits nutzt, empfehlen wir dir wärmstens, @xstate/test in Kombination mit unserer @smartive/xstate-test-toolbox auszuprobieren. Und falls du auch TestCafe einsetzt, hilft dir @smartive/testcafe-utils beim Abfangen von API Calls oder beim Mocken von allem, was mit Datum und Zeit zu tun hat.
Womit managst du den State deines User Interface und/oder deiner Daten? Wie testest du diese Apps? Was hältst du von unserer Lösung? Wir sind gespannt auf deine Herausforderungen und wie du sie gelöst hast! Hinterlass uns unten einen Kommentar oder lass uns reden!

Geschrieben von
Dominique Wirz
Ähnliche Challenge auf dem Tisch? Lass uns drüber reden.





