docurun

DocuRun

DocuRun est un outil pour exécuter votre documentation sous forme de tests d'intégration.

Pourquoi ?

Je parie que vos tests d'intégration et votre documentation sont décevants.

• Vos tests d'intégration sont probablement difficiles à écrire, difficiles à lire et difficiles à déboguer. Lorsque quelque chose ne va pas, vous devez parcourir le code et essayer de deviner à quel point il diffère de ce que vous faites manuellement dans votre navigateur.
• Votre documentation utilisateur final est probablement obsolète, car les développeurs ne souhaitent pas la mettre à jour à chaque fois qu'ils modifient le code. Lorsque vous modifiez le libellé d'un bouton, il faut penser à aller mettre à jour les captures d'écran dans la documentation, et vous ne le ferez probablement pas.

Si vous apportez une modification qui rompt le comportement documenté de l’interface utilisateur, vous ne le découvrirez probablement que lorsque vos utilisateurs se plaindront.

Qu’est-ce que DocuRun ?

DocuRun est un outil qui prend des fichiers de démarque, y compris des blocs de code de dramaturge, et les exécute en tant que tests d'intégration. Il produit un beau site de documentation avec des captures d'écran prises lors des tests.

Comment utiliser DocuRun

1. Rédigez votre documentation dans des fichiers markdown, y compris des blocs de code qui décrivent comment utiliser votre application. Créez un fichier docurun/index.md qui ressemble à ceci :
2. Exécutez DocuRun sur vos fichiers démarques

   npx docurun

3. Docurun affichera un joli rapport sur sa sortie standard indiquant quels fichiers de démarque ont été exécutés avec succès et lesquels ont échoué. Le code de sortie sera 0 si tous les tests ont réussi, et 1 si certains tests ont échoué, ce qui facilite l'intégration dans votre pipeline CI/CD. Il créera également un répertoire docurun/website/ contenant un site Web statique avec votre documentation et vos captures d'écran. Si certains tests échouent, la documentation contiendra les captures d'écran de la page au moment de l'échec, ainsi que le message d'erreur.

Docker

Vous pouvez également exécuter DocuRun dans un conteneur Docker, sans avoir à installer node.js sur votre machine :

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

Voir lovaoa/docurun sur Docker Hub.

Captures d'écran

Page SQL

Ceci montre la documentation exécutable de l'outil de création de site Web SQLPage.

Les étoiles de GitHub

Erreurs

Une erreur d'exécution ressemble à ceci dans le terminal

 $ 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

Et rendu :