Ludwig facilite la validation collaborative d'une application.

Ce service web permet aux usagers de transmettre des cas de test executables aux développeurs en créant un pont entre l'interface de l'application et GitHub.

Qu'est-ce que Ludwig n'est pas ?

Un Business Readable, Domain Specific Language comme Gherkin car chaque application est différente et que l'utilisation d'un tel langage se fait à un coût élevé pour les développeurs et pour les experts métiers.

Un test runner comme Mocha car vous en utilisez probablement déjà un. Avec Ludwig, votre stratégie de test actuelle sera exploitée et votre corpus de tests sera alimenté directement par vos usagers et experts métier.

Dans quel contexte peut-on utiliser Ludwig ?

Notre exemple : Validation collaborative d'une API

Un usager ou un expert métier remplit un formulaire complexe dans une application web. Les données sont ensuite envoyées à une API qui génère les résultats correspondants. En cas d'écart entre les résultats attendus et ceux générés, il est possible d'indiquer les valeurs attendues et de justifier leur validité (en faisant référence à des textes de loi ou des situations réelles par exemple).

Pré-requis techniques

Votre application doit avoir une stratégie de validation qui repose sur des fichiers contenus dans un dépôt GitHub. Chaque fichier doit définir un cas de test ie. une situation donnée, les résultats attendus associés et la description de la situation et votre application doit être capable de générer de tels fichiers.

Des exemples de fichiers de test sont visibles à https://github.com/openfisca/openfisca-france/blob/master/tests/mes-aides.gouv.fr.

Intégration

1. Proposition de suggestions
   • Un endpoint est mis à disponible pour déposer des suggestions
   • Le widget JavaScript permet de passer d'un fichier de cas de tests à une pull request dans GitHub
2. Réception des rapports de tests
   • Les rapports de tests doivent être envoyés à Ludwig qui permettra une bonne visualisation de l'état de validation de l'application

De quoi est composé Ludwig ?

Ludwig comprend deux composants :

• le widget navigateur ;
• l'application.

Le widget peut s'utiliser seul pour certaines fonctionnalités, mais prend surtout son intérêt couplé à l'application.

Que fait le widget navigateur ?

Le widget est là pour simplifier la collecte d'informations fonctionnelles pour créer des tests pour l'application qui intègre le widget.

Que fait l'application ?

L'application, quant à elle, permet de faire le lien entre le widget et GitHub (pour certaines fonctionnalités nécessitant une utilisation authentifiée de l'API GitHub, par exemple). Elle permet aussi d'aggréger les résultats de tests fonctionnels de l'application (au format xUnit) et de les présenter aux utilisateurs.

Exemple de fiche résumée :

Exemple de détail pour un test (historique) :

Ludwig en 5 minutes

Pour utiliser Ludwig avec son application, il faut :

• Intégrer le widget sur son application et le configurer
• Installer la partie serveur de ludwig

Les deux composants vont devoir communiquer, il faut donc que le serveur Ludwig soit joignable par le widget.

Tout ce dont va avoir besoin l'application est détaillé dans les exemples et dans le script setupNPMVariables.sh.

Intégrer le widget

Dans le dépôt, le widget "prêt à servir" est disponible à l'emplacement suivant : dist/ludwig.js, il suffit de l'intégrer dans son application avec un tag script pour qu'il soit disponible dans window.ludwig.

window.ludwig donne accès au constructeur car il faut configurer le widget.

Exemple d'import et de configuration :

<script type="text/javascript" src="http://url.serveur.ludwig/ludwig.js" charset="utf-8">
</script>
<script>
    var configuration = {
        repo: 'monutilisateur/nom-depot',
        template: 'un+template+basique\r\n===========',
        ludwigCreateSuggestionURL: 'http://url.serveur.ludwig/createSuggestion'
    }

    var ludwig = new Ludwig(configuration); //à cette étape, le widget "ludwig" est initialisé et configuré
</script>

Notes:

• La branche utilisée par défaut est "master"
• Le template va servir de préfixe au contenu du test à créer, il peut, entre autres contenir des informations que l'on souhaite saisies automatiquement.

Installer le serveur Ludwig

Vous pouvez récupérer la dernière version de Ludwig avec

$ npm install sgmap.ludwig

Avant de démarrer le serveur, il faut le configurer. Cela se fait via le fichier ./ludwig-conf.js et la configuration npm.

Exemple de fichier de configuration :

module.exports = {
    repo: 'monutilisateur/nom-depot',
    acceptedTestsLocation: 'tests',
    github: {
        branch: 'master',
        authenticationCallback: 'http://url.serveur.ludwig/github_callback'
    },
    mongo: {
        uri: 'mongodb://url.serveur.mongo/ludwig',
        options: {}
    }
};

La configuration NPM peut se faire via le script situé ici : scripts/setupNPMVariables.sh. Le script est interactif, il suffit de se laisser guider.

Créer une suggestion depuis le widget

Une fois le widget et le serveur configurés. On peut créer une suggestion depuis le widget (etatCourant représente l'état observé de l'application que l'on souhaite tester et etatAttendu celui souhaité, typiquement sous la forme d'objets JSON mais ce n'est pas une obligation):

ludwig.postSuggestion('nom suggestion', 'description de la suggestion', etatCourant, etatAttendu)

Plus de détails

Pré-requis

Pour installer Ludwig et le lancer, vous aurez besoin de :

• NodeJS/NPM
• MongoDB

Utiliser le widget dans une application

Configurer le widget

Le widget s'instancie avec en unique paramètre un objet contenant les informations nécessaires pour joindre le dépôt GitHub de votre projet.

Détail des entrées de la configuration du widget

• repo : identifiant du dépôt GitHub de l'application (ex : https://github.com/sgmap/ludwig).
• branch : branche dans laquelle créer des nouvelles demandes et consulter la liste de tests.
• template : contenu par défaut du fichier créé avec la suggestion.
• prefix : préfixe du fichier qui sera créé lors de la suggestion.
• ludwigCreateSuggestionURL : l'URL Ludwig à joindre pour créer une suggestion en passant par les APIs authentifiées GitHub.

Ajouter le widget

L'application peut embarquer le widget directement ou se le faire servir par le backend Ludwig. Dans le premier cas, il faut que l'application embarque le fichier ludwig.js généré dans l'étape précédente. Dans le second cas on va retrouver ce fichier à $URL_DE_L_APPLI/ludwig.js.

<script type="text/javascript" src="http://url.ludwig/ludwig.js" charset="utf-8">

Une fois cet ajout fait, le widget est disponible sous le nom Ludwig (qui est une classe, pour accéder aux fonctionnalités, il faut donc l'instancier en passant par un new Ludwig(configuration), avec configuration un objet contenant la configuration du widget telle que définie plus haut).

Note : Le widget "prêt à servir" à jour est présent dans le répertoire dist du module publié.

L'API du widget

Le widget doit être initialisé avec sa configuration pour les diverses URLs à appeler pour une tâche ou l'autre. La configuration suit la même organisation que celle côté serveur.

Son API complète est documentée dans un document à part On notera cependant 2 fonctions principales:

• generateSuggestionURL(currentState, expectedResult [, customSuggestionFormatter] ) : Génère une URL permettant d'ajouter un fichier correspondant à une suggestion. ATTENTION : Cette utilisation est limitée par GitHub et par les navigateurs eux-mêmes pour les URLs trop longues. L'API retournera une erreur si la longueur totale de l'URI générée par le widget dépasse une taille compatible avec les navigateurs supportés par Ludwig.
• generateLudwigSuggestionEndpointURL(suggestionTitle, suggestionDescription, currentState, expectedResult) : Crée le lien qui permet de contacter l'API Ludwig pour créer une nouvelle suggestion. Cela permet de fournir un titre et une description en plus de l'état et du résultat attendu.

Configurer et lancer le serveur Ludwig

Configurer

Le fichier de configuration utilisé par l'application se trouve à la racine. Il permet de configurer l'accès à une base de données mongo (pour stocker les rapports de tests) ainsi que quelques informations sur le dépôt GitHub où sont publiés les fichiers de tests et où l'on va créer des pull requests pour les demandes de nouveaux tests.

Détail de la configuration générale de l'application

Un fichier exemple ludwig-conf-sample.js est présent à la racine du projet, renommé en ludwig-conf.js et édité pour y mettre les informations correspondant à votre dépôt / votre base de données il devrait permettre à votre instance de se lancer et de communiquer avec les APIs GitHub.

• repo: Le dépôt GitHub où sont versionnés les tests (sous la forme <utilisateur>/<nom du dépôt>
• acceptedTestsLocation: Le chemin dans le dépôt où seront stockés les fichiers contenant les tests
• github:
  • branch: La branche de travail (par défaut : master)
  • authenticationCallback: L'URL de callback que GitHub doit appeler lors d'une authentification
• mongo (cette section correspond à ce que l'on trouve dans la documentation de mongoose):
  • uri: L'URI de connexion
  • options: Les options que l'on souhaite passer à mongoose

Configuration des secrets

Afin que votre application puisse utiliser les APIs GitHub (et en particulier connecter le contributeur lorsqu'il tente de soumettre un cas de test) votre instance de Ludwig doit être enregistrée. Cela se fait par le biais de cette page. Une fois le formulaire présenté rempli et validé, GitHub vous fournira le clientID et le clientSecret dont vous avez besoin.

Note : Pour correctement renseigner le champ Authorization callback URL, il faut fournir une URL de type <URI de la machine Ludwig>/github_callback.

• github.clientID : Client ID à utiliser pour requêter l'API GitHub
• github.clientSecret : Client Secret à utiliser pour requêter l'API GitHub
• github.accessToken : Un access token de compte ayant le droit de créer des commits sur le dépôt du projet (celui du mainteneur principal par exemple). Un guide est disponible ici. Note : Dans le cas qui nous intéresse pour le jeton d'accès, il faut en créer un avec le scope "repo" et ne pas sélectionner les autres.

Les clientID et clientSecret doivent être créés au préalable par le responsable du dépôt qui sera modifié de sorte à permettre à Ludwig d'accéder au dépôt et d'y faire des modifications.

D'autres paramètres peuvent être configurés :

• session.secret : Le secret qui sera utilisé pour signer le cookie de session (et éviter qu'il soit manipulé)
• cors : Le pattern d'URLs autorisées pour une utilisation cross-domain (si le widget et l'application Ludwig sont sur des machines avec des domaines différents)

Lancer le serveur Ludwig

Attention, il faut avoir créé le fichier de configuration de l'application. Le fichier ludwig-conf-sample.js est là pour qu'il ne reste plus qu'à remplir les blancs et le renommer en ludwig-conf,js pour avoir une configuration qui permette de démarrer le serveur.

$ npm install
$ npm start

Consulter le rapport des derniers tests

Description générale

Il est possible d'alimenter une base de données avec des rapports de tests afin de présenter aux contributeurs l'état des tests de l'application et son historique.

Pour pouvoir visualiser ces rapports, il faut tout d'abord alimenter la base de données de l'application. Cela se fait en utilisant l'utilitaire d'alimentation :

$ npm run insertTestReportData <fichier.xunit.xml>

Pour l'instant Ludwig accepte les rapports au format xUnit avec une suite de tests à la racine. Pour éviter d'insérer deux fois le même rapport, on considère que la propriété "timestamp" de la suite de tests est une clef unique (et l'importeur déclenchera une erreur si l'on tente d'insérer deux rapports avec le même timestamp, ce qui semble être une approche raisonnable pour un unique projet).

Où trouver ce rapport ?

Le rapport peut être trouvé à l'adresse suivante : /listTests.

Comment enregistrer un rapport pour Ludwig ?

Pour l'instant, les rapports que Ludwig est capable de traiter doivent suivre le format xUnit (avec un bloc testsuite juste sous la racine). Quelques consignes pour profiter des fonctionnalités comme le lien direct vers le fichier source d'un test :

Pour déterminer l'URL du fichier source d'un test, Ludwig se base sur :

• L'URL de base du dépôt où se trouvent les tests (dans la configuration c'est la propriété baseUrl).
• Le chemin permettant d'atteindre, sur le dépôt, le répertoire contenant les fichiers de test.
• Le nom du fichier de test lié au test à consulter doit être renseigné dans l'attribut classname de chacun des cas de test.

Les informations générales (tests ok, en échec, date des tests, temps pris par la campagne de tests…) se trouvent dans les propriétés de la suite de tests.

• name : Le nom de la campagne de test
• time : Le temps pris par tous les tests
• timestamp : L'heure à laquelle la campagne de tests s'est terminée
• tests : Le nombre total de tests
• errors : Les tests en erreur (cassés, le problème est technique)
• failures : Les échecs (les tests ont échoué car le comportement observé n'est plus celui attendu par les tests)

Tester l'application

Il existe aujourd'hui une page qui permet de directement tester l'application dans un navigateur, elle est exposée dans /test. Il n'est pas recommandé d'exposer cet endpoint. Pour éviter cela, il suffit de lancer l'application avec un dans son environnement la variable NODE_ENV définie à autre chose que development (qui est la valeur par défaut).