Wie entwickle und teste ich lokal?

Die lokale Entwicklung von Extensions, die sich stark mit dem mStudio integrieren, kann eine Herausforderung sein, da keine Möglichkeit besteht, das mStudio lokal oder in einer DEV Umgebung zu starten. Neben der Möglichkeit, die mStudio API zu mocken, was sich ohne Kenntnisse der API als schwierig erweisen kann, existieren dennoch Mittel und Wege, um die lokale Entwicklung von Extensions zu erleichtern. Diese werden im Folgenden vorgestellt.

Erstellen einer Extension Instance

Notiz

Es muss bereits ein Context zugewiesen sein, bevor du eine Extension Instance erstellen kannst.

Wenn du deine Extension entwickelst, kannst du sie nur innerhalb des mStudio vollständig testen.
Dazu musst du eine Extension Instance erstellen, wofür du die Extension ID deiner Extension kennen musst.
Die Extension ID kann unter dem "Entwicklung" Tab der Extension im mStudio eingesehen werden.

Notiz

Alle Extension Instances innerhalb deines Contributors sind kostenlos.

Während der Entwicklung wird deine Extension nicht im Marktplatz angezeigt.

...über das mStudio (empfohlen)

1. Öffne das mStudio.
2. Navigiere zum Marktplatz.
3. Wähle eine beliebige Extension aus.
4. Ersetze in der URL-Pfad die Extension ID mit der Extension ID deiner Extension.

...über die API

Du kannst eine Extension Instance programmatisch mit der

unknown operation extension-add-extension-to-context Operation erstellen.

Für jeden benötigten Scope musst du im scopes-Feld deines Request-Bodys einen Eintrag im folgenden Format hinzufügen:
"bereich:(read|write|delete)". Die benötigten Scopes findest du in dem Bereich "Berechtigungen" deiner Extension im mStudio.

Nach der Veröffentlichung deiner Extension

Nach der Veröffentlichung deiner Extension werden die Extension Instances, die du zu Testzwecken erstellt hast, entfernt.
Du kannst deine Extension jedoch jederzeit kostenlos zu deinen Contextes hinzufügen.

Authentifizierte Domain Actions

Um die Geschäftslogik im Zusammenspiel mit dem mStudio effektiv zu testen, ist es am einfachsten, die mStudio API direkt zu verwenden. Dabei ist es in der Regel erforderlich, sich gegen die API zu authentifizieren.

...mittels persönlichem API-Token

In einer frühen Phase, in der die Geschäftsidee noch geprüft und an einem Proof of Concept gearbeitet wird, bietet es sich an, einen persönlichen API-Token zu verwenden. Dieser Token kann für die lokale Entwicklung genutzt werden. Es ist jedoch wichtig, darauf zu achten, dass API-Tokens nicht in Versionskontrollsysteme wie Git gelangen und diese Lösung nur für die lokale Entwicklung gedacht ist.

Weitere Informationen zur Erzeugung eines persönlichen API-Tokens sind zu finden unter Ein API-Token beziehen

...mittels Extension Instance Secret Rotation

Eine weitere Möglichkeit, die mStudio API authentifiziert zu nutzen, ohne die Authentifizierungsmethoden vollständig zu implementieren, ist die Rotation eines Extension Instance Secrets. Hierfür wird die PUT/v2/contributors/{contributorId}/extensions/{extensionId}/extension-instances/{extensionInstanceId}/secret/-Operation verwendet. Das neue Secret wird per Webhook übermittelt, aber auch als Antwort auf den Request zurückgegeben. Das so erhaltene Secret kann nun sicher hinterlegt werden, ähnlich wie ein persönlicher API-Token, um ein Access Token beziehen zu können, wie unter Authentifizierung mittels Extension Instance Secret beschrieben. Bei Nutzung dieser Route wird der Lifecycle Webhook synchron ausgeführt. Bei Fehlschlag wird der Webhook nicht erneut versendet. Außerdem wird das Secret nicht gültig, wenn der Webhook fehlschlägt. Um ohne funktionierende Webhooks dennoch testen zu können, kann der Route im Request Body "allowWebhookFailure": true hinzugefügt werden. Der Fehler des Lifecycle Webhooks wird dann ignoriert und das Secret samt Antwort des Extension-Backends trotzdem zurückgegeben.

Diese Methode ist besonders nützlich, wenn die Authentifizierung später ebenfalls über das Extension Instance Secret erfolgen soll. Zudem können Initialisierungsprozesse, die anschließend zu den Lifecycle Webhooks ausgeführt werden würden, mit einem funktionierenden Secret getestet werden, ohne im mStudio für jeden Versuch eine neue Extension Instance erstellen zu müssen.

...mittels OAuth2

Wenn die Authentifizierung und Ausführung von Domain Actions über OAuth2 getestet werden soll, empfiehlt es sich, im OAuth2-Client eine lokale Redirect URI einzurichten. Dies kann entweder localhost oder eine Domain sein, für die ein lokaler Host-Eintrag existiert. Es sollte darauf geachtet werden, dass bei Verwendung eines Host-Eintrags keine potenziell öffentlich auflösbare Domain verwendet wird, die nicht unter der Kontrolle des Entwicklers steht, um Sicherheitsrisiken zu vermeiden.

Deine lokale Extension erreichbar machen

Lifecycle Webhooks werden immer vom mStudio Backend an die an der Extension konfigurierte Webhook-URL gesendet. Es gibt derzeit keine Möglichkeit, echte Lifecycle Webhooks zu empfangen, ohne die lokal laufende Extension öffentlich erreichbar zu machen. Ein Tunnel aus dem öffentlichen Internet auf deinen Rechner gehört daher zu jedem lokalen Setup, in dem Webhooks eine Rolle spielen.

Grundsätzlich funktioniert jede Tunneling-Technik. Wenn du bereits ngrok oder Cloudflare Tunnel verwendest, bleib dabei. Wir empfehlen zrok als kostenlose Open-Source-Option, die sowohl self-hosted als auch als SaaS-Lösung genutzt werden kann.

Wir empfehlen, eine stabile URL zu reservieren, die einen Neustart des Tunnels übersteht, damit du die Webhook-URL deiner Extension nicht bei jedem Neustart neu konfigurieren musst. Mit der zrok SaaS-Lösung sind das drei Befehle:

zrok enable <dein-token>          # einmal pro Rechner, Token von myzrok.io
zrok reserve public 3000          # einmalig, reserviert eine stabile URL für deinen lokalen Port
zrok share reserved <share-token> # startet den Tunnel

Anschließend konfigurierst du die entstandene öffentliche URL samt deines Webhook-Pfads als Webhook-URL deiner Extension. Das geht im Tab "Webhooks" deiner Extension im mStudio oder programmatisch über die PATCH/v2/contributors/{contributorId}/extensions/{extensionId}/-Operation.

Info

Eine Schritt-für-Schritt-Anleitung für dieses Setup, und wie es sich in eine vollständige Extension einfügt, findest du unter Expose Extension im Getting-Started-Guide.

Testen der Lifecycle Webhooks

Beide im Folgenden beschriebenen Methoden senden Webhooks an die konfigurierte Webhook-URL deiner Extension. Sie setzen daher voraus, dass deine lokale Extension erreichbar ist, wie unter deine lokale Extension erreichbar machen beschrieben.

Musst du das Webhook-Handling überhaupt testen?

Die technische Seite von Lifecycle Webhooks — den Call annehmen, die Signatur verifizieren, den Payload parsen und ihn an den richtigen Handler weiterreichen — ist generische Infrastruktur, die du nicht selbst bauen und deshalb auch nicht selbst testen musst. Bibliotheken wie @weissaufschwarz/mitthooks, die auch die Reference Extension verwendet, decken das vollständig ab.

Übrig bleibt deine Domänenlogik: was deine Extension tut, wenn eine Extension Instance hinzugefügt, aktualisiert oder entfernt wird. Das ist gewöhnlicher Anwendungscode, den du lokal isoliert testen kannst — ganz ohne Tunnel und ohne mStudio. Nutze die folgenden Methoden, um die Integration als Ganzes zu verifizieren.

...mittels Dry Run Webhooks (empfohlen)

Mithilfe der POST/v2/contributors/{contributorId}/extensions/{extensionId}/extension-instances/{extensionInstanceId}/actions/dry-run/{webhookKind}/-Operation können Lifecycle Webhooks auch über das mStudio Backend simuliert werden. Dabei wird der angefragte Lifecycle Webhook an die an der Extension konfigurierten URL gesendet. Dry Run Webhooks können nur für Extension Instances des Contributors ausgeführt werden. Die Werte der Lifecycle Webhooks können frei gewählt werden oder vom mStudio Backend zufällig generiert werden. Für eine Übersicht, welche Werte statisch gesetzt werden können, siehe in der verlinkten Operation.

Das Ergebnis samt Response Body, Headern und Status Code wird dabei als Antwort auf die Operation zurückgegeben.

Dry Run Webhooks sind der praktischste Weg, um während der Entwicklung zu iterieren:

• Du musst deine Extension nicht für jeden Versuch neu installieren und wieder entfernen.
• Das mStudio führt Dry Run Webhooks synchron aus. Du bekommst die Antwort deines Webhook-Handlers also unmittelbar zurück, statt in deinen lokalen Logs nachsehen zu müssen.
• Dadurch kannst du denselben Webhook beliebig oft und in einer selbst gewählten Reihenfolge senden. Echte Lifecycle Webhooks werden asynchron zugestellt, wodurch du deutlich weniger Kontrolle über Zeitpunkt und Wiederholung hast.

Achtung

Um den Webhook als Dry Run erkennbar zu machen, wird dem Webhook der Query-Parameter dry-run=true hinzugefügt. Es sollte darauf geachtet werden, dass in Produktivsystemen keine Webhooks mit diesem Parameter verarbeitet und persistiert werden, da es sich um eine Simulation handelt und so die Daten inkonsistent werden könnten.

Zu Dokumentationszwecken kann zusätzlich der executing-user-id Query-Parameter ausgewertet werden. Dieser wird ebenfalls automatisch jedem Dry Run Webhook beigefügt. Er enthält die ID des Benutzers, der den Dry Run Webhook ausgelöst hat.

...durch Installation deiner Extension

Die Installation deiner Extension ist der realistischste Test, denn sie löst Webhooks genauso aus, wie es später deine Nutzer tun: indem die Extension zu einem Context hinzugefügt, ihr Zustand verändert und sie wieder entfernt wird. Jede dieser Aktionen erzeugt einen echten, signierten Webhook-Call.

1. Mache deine lokale Extension erreichbar und konfiguriere die Webhook-URL, wie unter deine lokale Extension erreichbar machen beschrieben.
2. Erstelle eine Extension Instance, wie unter Erstellen einer Extension Instance beschrieben. Das löst den ExtensionAddedToContext-Webhook aus.
3. Aktiviere oder deaktiviere die Extension Instance, um InstanceUpdated-Webhooks auszulösen.
4. Entferne die Extension aus dem Context, um den InstanceRemovedFromContext-Webhook auszulösen.

Die Bedeutung der einzelnen Webhooks ist unter Lifecycle Webhooks beschrieben.

Da alle Extension Instances innerhalb deines Contributors kostenlos sind, kannst du diesen Zyklus beliebig oft wiederholen. Da das mStudio diese Webhooks asynchron zustellt, eignet sich diese Methode eher dazu, die Integration als Ganzes zu bestätigen, als im Detail zu iterieren.

Frontend Fragments testen

Um zu testen, ob die Integration deines Frontend-Fragments korrekt funktioniert, solltest du dein Frontend starten. Außerdem solltest du deine (Development-)Extension so konfigurieren, dass sie die URL deines lokalen Entwicklungsservers, z.B. http://localhost:3000/my-fragment als Frontend Fragment verwendet. Dazu kannst du eine versteckte Kopie deiner Extension für die lokale Entwicklung erstellen (siehe Staging).

Dies ermöglicht es dir, dein Frontend-Fragment lokal zu entwickeln und zu testen, bevor du es live bereitstellst.

Eine optimierte Entwicklungsumgebung für Frontend-Fragmente, die diesen Prozess weiter vereinfachen soll, wird in Zukunft eingeführt.