Sortie de Hurl 4.0.0

• Hurl 4.0.0 est une nouvelle version de l’outil CLI de test HTTP basé sur curl, qui améliore le flux d’exécution des requêtes HTTP et des validations de réponses écrites dans des fichiers en texte brut
• Les rapports HTML sont générés en HTML pur, uniquement avec du CSS inline et sans JavaScript, et affichent pour chaque requête/réponse une timeline waterfall, les logs d’exécution et les erreurs inline
• --error-format long affiche les en-têtes et le corps de la réponse des tests en échec, afin de fournir dans le débogage CI/CD le contexte nécessaire pour comprendre la cause sans relancer l’exécution
• Les nouveaux filtres decode et xpath permettent de décoder directement des octets de réponse dont le jeu de caractères n’est pas clairement indiqué, et d’effectuer des validations XPath sur une partie du HTML
• Une partie du mode d’évaluation de JSONPath a changé, et les méthodes HTTP personnalisées respectant la contrainte des majuscules sont prises en charge, ce qui permet aussi d’expérimenter de nouvelles méthodes comme QUERY

---

Présentation de Hurl 4.0.0

• Hurl est un outil en ligne de commande basé sur curl, qui exécute des requêtes HTTP définies dans un format simple en texte brut
• Dans un fichier Hurl, il est possible d’écrire à la fois les requêtes, le statut HTTP attendu et des assertions comme les en-têtes, les certificats ou JSONPath
• Hurl 4.0.0 apporte principalement des changements autour des rapports HTML, de la sortie d’erreur, des filtres, du comportement de JSONPath et de la prise en charge des méthodes HTTP personnalisées

Rapports HTML et timeline waterfall

• Le rapport HTML de Hurl génère trois types d’informations à chaque exécution
  • Timeline waterfall : affiche chaque requête/réponse sous forme de graphique et permet de consulter les timings de réponse comme le DNS, la poignée de main TCP ou le time to first byte
  • Logs d’exécution : incluent notamment les en-têtes de requête/réponse et les informations de certificat
  • Fichier source avec coloration syntaxique : affiche les erreurs inline
• Le rapport est composé de HTML pur et de CSS inline, sans JavaScript, ce qui facilite son intégration dans des environnements CI/CD comme GitLab CI/CD ou GitHub Actions
• Les timings utilisés dans la timeline waterfall sont fournis par libcurl et sont aussi exposés via l’option --json
  • --json fournit des informations d’exécution structurées incluant les erreurs, assertions, certificats, captures, cookies et timings
  • Cette sortie JSON permet de créer ses propres rapports

Les visualisations révèlent un goulot d’étranglement dans les performances des assertions

• Des visualisations riches peuvent révéler des problèmes de performance cachés
• Lors de certaines exécutions, de grands intervalles sont apparus entre les requêtes ; la cause était le très grand nombre d’assertions sur les réponses HTTP
• Dans Hurl 4.0.0, le calcul des assertions fonctionne de manière simple
  • Chaque assertion sur une même réponse est traitée indépendamment
  • À chaque assertion, l’analyse repart de zéro et le calcul est refait
• L’équipe Hurl était confiante dans les performances de la combinaison libcurl et Rust, mais ce cas lui a fait conclure qu’une amélioration des performances des assertions serait nécessaire dans la prochaine version

Sortie d’erreur détaillée pour la CI/CD

• La sortie existante en cas d’échec de test était centrée sur la valeur attendue et pouvait manquer d’informations nécessaires à l’analyse
• La nouvelle option --error-format permet de choisir une description d’erreur plus longue
• En mode --error-format long, les en-têtes de réponse et le corps de réponse sont automatiquement consignés dans les logs
• Dans l’exemple, le test cherchait l’en-tête Control-Security-Policy, mais la réponse réelle contenait Content-Security-Policy
  • Les en-têtes et le corps de la réponse étant inclus dans les logs, il est facile d’identifier un problème de type faute de frappe
• Cette option est utile dans les environnements CI/CD où l’on veut obtenir le contexte nécessaire au débogage d’une session sans relancer les tests
• Comme le corps de réponse est également enregistré, les logs peuvent devenir très longs

Nouveaux filtres : decode et xpath

• Les assertions textuelles de Hurl décodent automatiquement les octets du corps de réponse, en utilisant pour cela l’indication charset de l’en-tête de réponse Content-Type
• Il arrive que Content-Type ne contienne pas d’encodage, ou que le jeu de caractères soit indiqué dans une balise <meta> à l’intérieur du document HTML
• Le nouveau filtre decode permet de décoder explicitement des octets en texte afin de les valider
  • L’exemple décode un corps encodé en GB2312 avec bytes decode "gb2312"
• Le nouveau filtre xpath permet d’évaluer une expression XPath sur une partie de la réponse
  • L’exemple valide le texte du body HTML avec xpath "string(//body)"

Changement du mode d’évaluation de JSONPath

• Hurl 4.0.0 modifie en partie l’évaluation des requêtes JSONPath
• JSONPath ne dispose pas vraiment d’une spécification officielle, et Hurl cherche à suivre autant que possible le document de goessner.net, utilisé de fait comme un standard
• Certains cas limites varient selon les implémentations
  • JSONPath standard renvoie toujours une collection, mais cela a le plus souvent peu de sens et peut être difficile à tester
  • Certaines implémentations distinguent la valeur d’un nœud pour les definite paths et les collections pour les indefinite paths
• Dans Hurl 4.0.0, seuls deux types de sélecteurs renvoient une valeur
  • Sélecteur d’index de tableau : $.store.book[2]
  • Sélecteur de clé d’objet : $.store.bicycle.color, $.store.bicycle['color']
• Les sélecteurs utilisant un filtre ou les sélecteurs comme $[*].id renvoient une collection
  • Pour extraire une valeur d’une collection, il est possible d’utiliser le filtre nth

Méthodes HTTP personnalisées

• Hurl 4.0.0 prend en charge des méthodes HTTP personnalisées arbitraires
• Les méthodes doivent être écrites en majuscules
• Il est par exemple possible d’expérimenter immédiatement la nouvelle méthode QUERY à venir
  • Document associé : nouvelle méthode QUERY à venir

Notes de version et appel à contribution

• Les autres améliorations et corrections de bugs sont disponibles dans les notes de version
• Le projet invite à laisser une star GitHub, partager sur Twitter, proposer des améliorations et partager des cas d’usage

[GN⁺]

Avis Hacker News

• J’ai apprécié que la présentation de Hurl commence par « un outil en ligne de commande basé sur curl qui exécute des requêtes HTTP définies dans un simple format texte brut »
  Je découvrais Hurl pour la première fois, et la courte introduction et l’exemple de code tout en haut m’ont immédiatement donné envie de l’installer et de l’essayer ; ça ressemble à une excellente release

  • En tant que mainteneur de Hurl, je lis Hacker News depuis longtemps et j’ai noté tous les conseils de présentation du style « montrez des exemples de langage le plus vite possible » ou « expliquez le concept brièvement à chaque fois », et j’ai essayé de les appliquer concrètement sur hurl.dev
  • Beaucoup trop d’annonces et de README commencent par les prérequis d’installation ou par « nous avons corrigé X, Y, Z » sans expliquer au fond ce que fait l’outil, donc cette approche est la bonne
  • C’est vrai, mais l’essentiel aurait dû figurer dans le titre
    Par exemple, un titre comme Hurl: Run HTTP requests in a simple plain-text format aurait été meilleur

• J’aimerais qu’on en fasse le standard de l’industrie pour les tests d’API
  J’en ai assez de regarder des captures d’écran Postman envoyées par la QA, et d’attendre que la QA clique sur Send après une correction ; la QA en a sûrement assez d’attendre les développeurs aussi
  Hurl peut être lu et écrit à la fois par les développeurs et la QA, permet l’automatisation et l’intégration CI, facilite la transmission du comportement attendu, et peut être ajouté à une PR comme point de départ pour la QA, donc je ne vois pas de raison de ne pas l’utiliser quand c’est possible

  • On utilise Hurl dans un service à la fois pour les tests d’API manuels et dans la CI, et c’est vraiment bien
    On peut mettre tout le flux d’échanges HTTP par workflow dans un seul fichier hurl, ce qui en fait une suite de tests qui va directement dans Git
  • Pour les équipes qui utilisent VSCode, vscode-restclient vaut aussi le détour : https://github.com/Huachao/vscode-restclient
    Cela dit, Hurl est aussi très intéressant, et je suis d’accord que son indépendance vis-à-vis de l’éditeur en fait une meilleure solution pour ce problème
  • Je me demande si vous avez aussi essayé https://k6.io/
    On peut y écrire des tests de charge/performance en JS, les commit dans un dépôt, les automatiser facilement dans la CI, envoyer des métriques vers plusieurs backends, utiliser des protocoles autres que HTTP, et profiter d’une interface en ligne de commande moderne avec beaucoup de fonctionnalités
    Il existe aussi un convertisseur Postman vers k6 : https://github.com/apideck-libraries/postman-to-k6
    La philosophie de k6 est que les développeurs écrivent ce type de tests, comme des tests unitaires/d’intégration, pour casser le cycle QA-développement classique ; Hurl a l’air bien aussi, mais ses fonctionnalités semblent plus limitées que celles des outils de test de performance existants, et personnellement je préfère écrire les tests dans un langage de programmation plutôt que dans un format texte dédié
  • Personnellement, j’aime bien l’approche qui consiste à définir l’API avec OpenAPI puis à valider la spécification avec Dredd
    Même si on utilise un outil qui génère la spécification à partir du code source, une erreur utilisateur dans la définition des métadonnées d’un endpoint reste possible, et Dredd permet de la détecter

• C’est probablement l’un des meilleurs exemples de programme Unix moderne que j’aie vus jusqu’ici
  Il lit l’entrée standard, écrit sur la sortie standard, n’inonde pas le terminal d’emojis Unicode partout, et il a des pages man assez soignées
  J’aime aussi que l’extension de fichier hurl fasse quatre lettres au lieu de trois ; on dirait qu’on a enfin cessé de se préoccuper de la compatibilité MS-DOS
  Ça a l’air d’être un outil qui mérite d’être essayé sérieusement

  • Je ne m’étais pas rendu compte à quel point les emojis dans le terminal me dérangeaient ; le fait qu’il n’y en ait pas ici me plaît soudain beaucoup
  • On a donc aussi cessé de se préoccuper non seulement de MS-DOS, mais aussi de la compatibilité VMS

• Pour les outils HTTP en ligne de commande, mes préférés sont Httpie ou XH, sa réécriture plus rapide en Rust
  Ils permettent d’envoyer des requêtes depuis la ligne de commande avec une syntaxe bien plus proche de HTTP que curl, sans avoir à apprendre une foule d’options
  Si vous êtes déjà à l’aise avec curl, ça ne vous servira peut-être pas énormément, mais pour un usage léger c’est bien plus intuitif
  https://httpie.io/
  https://github.com/ducaale/xh

• Chez Adaptive, on utilise largement hurl.dev pour l’automatisation des tests : https://adaptive.live
  On teste avec Hurl l’ensemble de nos flux produit internes, et c’est l’un des meilleurs choix que nous ayons faits dans l’organisation du point de vue de la stabilisation du produit
  Avant chaque déploiement, on exécute plusieurs tests automatisés basés sur Hurl pour vérifier l’onboarding, l’inscription, les flux critiques, etc., et comme tout est conteneurisé, on peut aussi les lancer en parallèle
  On construit également des outils internes autour de hurl.dev, et c’est appréciable qu’il soit facile à apprendre, au point que des analystes ou des profils métier puissent aussi créer des tests

  • Je me demande pourquoi utiliser un outil autonome
    Dans un contexte de test, une approche basée sur le navigateur comme Selenium semble bien plus puissante et globalement plus utile
  • Je me demande s’il prend en charge nativement les flux OAuth, ou s’il faut des tokens codés en dur
    J’ai regardé la documentation mais je n’ai rien trouvé à ce sujet

• J’observe hurl depuis quelque temps, et ce qui le distingue des autres outils, c’est qu’il a sa propre DSL pour les tests
  Il ne se contente pas d’envoyer des requêtes HTTP ; il peut aussi valider les réponses et capturer des données
  Cela dit, si le mainteneur lit ceci, j’aimerais qu’il permette de déléguer les validations à des scripts externes
  Par exemple, pour vérifier que toutes les propriétés d’une collection d’éléments ont la même valeur, c’est encore difficile sans utiliser le sélecteur nth, et il faudrait quelque chose comme nth = *
  Fournir tous les cas d’usage via la DSL serait un travail énorme, donc ce serait bien de pouvoir passer le résultat jsonpath à jq et considérer le test comme réussi si true est renvoyé

  • Une DSL finit inévitablement par dériver vers un langage général Turing-complet, donc l’appel à des scripts externes semble raisonnable
    En revanche, cela rendrait les fichiers moins autonomes et pourrait introduire des problèmes assez complexes

• Hurl semble croître rapidement, ce qui est encourageant
  Pour les tests d’endpoint, il faut toujours de l’authentification ; je me demande s’il existe un moyen de mettre l’authentification dans un fichier puis de la récupérer au début d’autres fichiers qui ont besoin du token

  • Il ne semble pas que Hurl ait des fonctionnalités du type include ou macro
    Et de toute façon, on n’est pas certain que ce soit la meilleure façon de stocker et d’utiliser des secrets
    D’après la documentation, on peut transmettre des variables aux fichiers hurl via des arguments en ligne de commande et des variables d’environnement : https://hurl.dev/docs/templates.html

• Pour cet usage, j’aime aussi beaucoup httpyac : https://httpyac.github.io
  Il offre des fonctions de scripting JS, donc c’est assez proche, et en plus de l’interface en ligne de commande, son intégration VS Code est excellente

  • httpyac est aussi très compatible avec la prise en charge des fichiers .http dans les IDE JetBrains
    JetBrains fournit aussi un outil gratuit en ligne de commande qui génère des rapports de test jUnit à partir des fichiers .http

• J’ai découvert que Visual Studio 2022 prend aussi en charge des fonctions similaires avec des fichiers .http : https://learn.microsoft.com/en-us/aspnet/core/test/http-file...
  Hurl semble offrir bien plus de fonctionnalités

  • Les IDE JetBrains le prennent aussi en charge, donc pour l’instant cela ressemble à un format relativement proche d’un standard par rapport aux autres approches
  • Hurl est bien plus rapide
  • J’utilise depuis quelque temps l’extension VS Code sur laquelle cette fonctionnalité est basée