docurun

DocuRun

DocuRun ist ein Tool zum Ausführen Ihrer Dokumentation als Integrationstests.

Warum ?

Ich wette, sowohl Ihre Integrationstests als auch Ihre Dokumentation sind enttäuschend.

• Ihre Integrationstests sind wahrscheinlich schwer zu schreiben, schwer zu lesen und schwer zu debuggen. Wenn etwas schief geht, müssen Sie den Code durchforsten und versuchen zu erraten, an welcher Stelle sie sich von dem unterscheiden, was Sie manuell in Ihrem Browser tun.
• Ihre Endbenutzerdokumentation ist wahrscheinlich veraltet, da die Entwickler sie nicht jedes Mal aktualisieren möchten, wenn sie den Code ändern. Wenn Sie den Wortlaut einer Schaltfläche ändern, müssen Sie daran denken, die Screenshots in der Dokumentation zu aktualisieren, was wahrscheinlich nicht der Fall sein wird.

Wenn Sie eine Änderung vornehmen, die das dokumentierte Verhalten der Benutzeroberfläche beeinträchtigt, erfahren Sie dies wahrscheinlich erst, wenn sich Ihre Benutzer beschweren.

Was ist DocuRun?

DocuRun ist ein Tool, das Markdown-Dateien einschließlich Dramatiker-Codeblöcken als Integrationstests ausführt. Es erstellt eine schöne Dokumentationswebsite mit Screenshots, die während der Tests erstellt wurden.

So verwenden Sie DocuRun

1. Schreiben Sie Ihre Dokumentation in Markdown-Dateien, einschließlich Codeblöcken, die beschreiben, wie Sie Ihre Anwendung verwenden. Erstellen Sie eine docurun/index.md Datei, die wie folgt aussieht:
2. Führen Sie DocuRun für Ihre Markdown-Dateien aus

   npx docurun

3. Docurun zeigt in seiner Standardausgabe einen schönen Bericht an, der zeigt, welche Markdown-Dateien erfolgreich ausgeführt wurden und welche fehlgeschlagen sind. Der Exit-Code ist 0, wenn alle Tests bestanden wurden, und 1, wenn einige Tests fehlgeschlagen sind, was die Integration in Ihre CI/CD-Pipeline erleichtert. Außerdem wird ein docurun/website/ -Verzeichnis erstellt, das eine statische Website mit Ihrer Dokumentation und Screenshots enthält. Wenn einige Tests fehlgeschlagen sind, enthält die Dokumentation die Screenshots der Seite zum Zeitpunkt des Fehlers sowie die Fehlermeldung.

Docker

Sie können DocuRun auch in einem Docker-Container ausführen, ohne node.js auf Ihrem Computer installieren zu müssen:

docker run -v $( pwd ) /docurun:/docurun -it lovasoa/docurun

Siehe lovaoa/docurun auf Docker Hub.

Screenshots

SQLSeite

Dies zeigt die ausführbare Dokumentation des SQLPage-Website-Erstellungstools.

Github-Sterne

Fehler

Ein Fehlerlauf sieht im Terminal so aus

 $ npx docurun

> [email protected] start
> node cli.js

Processing all files in ./docurun/:
 - download_sqlpage.md
 - star_a_repository.md.
Saving results to ./docurun/website/.

✅ download_sqlpage
Error while executing code:
await page.getByText('inexistent element').click()

locator.click: Timeout 30000ms exceeded.
Call log:
  - waiting for getByText('inexistent element')

 star_a_repository

Und gerendert: