La testocumentation

J'étais en train de créer une API avec Adonis, un framework Node.JS, quand je me suis dit : "Il serait peut-être temps de faire des tests".

Étant en phase expérimentale et n'étant pas certain de conserver Adonis voir même Node pour mon projet, j'ai commencé à regarder les frameworks de tests agnostiques. Je suis tombé sur Dredd, il permet de tester son API a partir d'un fichier de configuration Api Blueprint. Et c'est là que tout commence.

Serveur

Pour simplifier la présentation, notre serveur aura deux routes retournant du JSON :

• la racine retournant un "Hello world"
• une route avec paramètre retournant les informations d'un utilisateur

const express = require("express")

const app = express()

const users = [
  {
    id: 1,
    name: "Jean Smaug",
  },
  {
    id: 2,
    name: "Timmy",
  },
]

app.get("/", function(req, res) {
  res.json({ message: "Hello World!" })
})

app.get("/bogass/:id", function(req, res) {
  res.json(users.find(user => user.id === Number(req.params.id)))
})

app.listen(3000, () => {
  console.log("Listening on port 3000")
})

Initialisation de Dredd

Après avoir installé Dredd avec un yarn add -DE dredd, nous pouvons l'initialiser en lançant yarn dredd init

? Location of the API description document apiary.apib
? Command to start the API server under test yarn dev
? Host of the API under test http://127.0.0.1:3000
? Do you want to use hooks to customize Dredd's behavior? No
? Do you want to report your tests to the Apiary inspector? No
? Dredd is best served with Continuous Integration. Do you want to create CI configuration? No

Nous venons de configurer Dredd pour qu'il lise un fichier apiary.apib. Ce fichier permettra de lancer des tests sur un serveur accessible via http://127.0.0.1:3000. Et ce serveur sera lancé via la commande yarn dev.
Maintenant que Dredd est initialisé nous pouvons nous concentrer sur API Blueprint.

API Blueprint

API Blueprint se définit comme étant un "puissant langage de description" pour les API web.
Concrètement, nous allons définir vos routes, les paramètres nécessaires et les valeurs de retour attendues, dans un fichier .apib, apiary.apib dans ce cas précis.
Dans ce fichier, nous allons écrire du MSON (Markdown Syntax for Object Notation), donc attention à bien respecter l'indentation.

FORMAT: 1A

# Bogass

API de l'application Bogass, l'application des bogass

# GET /

- Response 200 (application/json; charset=utf-8)

  - Body

          {
              "message": "Hello World!"
          }

# GET /bogass/{id}

- Parameters

  - id: 1 (number) - Identifiant du bogass

- Response 200 (application/json; charset=utf-8)

  - Body

          {
              "id": 1,
              "name": "Jean Smaug"
          }

Lorsque Dredd lira ce fichier, il lancera deux requêtes, une sur chaque route. On s'attendra pour chacune d'entre elle à recevoir un code HTTP 200 et un content-type ayant (application/json; charset=utf-8) pour valeur.

La grosse différence entre la première et la seconde requête réside dans le passage de paramètre qui s'effectue de la manière suivante.

- nom_du_champs: valeur_de_test (type) - Description

Pour lancer nos test un simple yarn dredd suffit.

Avoir un fichier de description de notre API est tout bonnement super, car il permet à n'importe quel outil de venir le consommer. Ce qui me permet de faire une transition vers snowboard

Snowboard

Snowboard va lui aussi lire notre fichier de configuration .apib, et il va générer une documentation.

Pour obtenir ce résultat il faut lancer la commande yarn snowboard html -o index.html apiary.apib

Conclusion

Créer un lien entre les tests et la documentation est une idée que je trouve tout bonnement excellente. Je pense qu'écrire une documentation est quelque chose de chiant et primordial. Et la maintenir est quelque chose d'encore plus abominable. Avec ce genre d'outil, si la documentation n'est pas à jour cela veut dire que les tests non plus, ce qui est... problématique.
En bref n'hésitez pas a lire les documentations de Dredd, Api Blueprint et Snowboard qui sont bien plus complète que cette succinte présentation.
Merci de m'avoir lu.

Bonus

Une chose dont je n'ai pas parlé : Dredd supporte aussi le format Open API (V2 pour le moment). Si vous êtes un adepte de l'Open API vous pouvez consulter cet article.