<!--
  canonical-url: https://www.avonture.be/fr/blog/hurl
  published:     2026-11-19
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Hurl — Enchaînez vos appels HTTP dans une recette lisible par tous

> Hurl remplace la danse curl + jq + export par un seul fichier texte .hurl qui se connecte, garde le token, appelle l'API protégée et vérifie chaque réponse avec des assertions. Lisible par un non-développeur, exécutable comme suite de tests par le développeur de l'API, et livrable à un client qui veut simplement ses données dans une base chaque nuit.

---
![Hurl — Enchaînez vos appels HTTP dans une recette lisible par tous](/img/v2/hurl.webp)

**TL;DR**

Hurl est un outil en ligne de commande gratuit et open source qui lit un fichier texte `.hurl`, envoie les requêtes HTTP qu'il décrit de haut en bas, et confronte chaque réponse aux assertions écrites en dessous. Un token capturé dans la première réponse alimente la deuxième requête : « se connecter, puis appeler l'API protégée » tient dans un seul fichier au lieu de deux appels `curl` recollés avec `jq`. Le même fichier est une recette lisible pour un non-développeur, une suite de tests pour le développeur de l'API, et un export de données nocturne pour le client.

Appeler une API protégée avec `curl` se passe toujours de la même façon : un premier `curl` pour obtenir un token, `jq` pour l'extraire du JSON, une variable shell pour le garder, un second `curl` avec `-H "Authorization: Bearer $TOKEN"`, et ensuite… je regarde la réponse de mes propres yeux et je décide qu'elle est correcte. Et quand un collègue, ou un client, demande *« comment j'appelle cette API ? »*, je lui envoie un script shell qu'il ne sait pas lire.

Hurl transforme tout ça en un petit fichier texte lisible par n'importe qui, qui enchaîne les appels tout seul et **vérifie** chaque réponse avant de continuer.

## Ce que Hurl fait pour vous {#what-hurl-does-for-you}

Voici la version `curl` d'une connexion sur [DummyJSON](https://dummyjson.com) — une fausse API REST gratuite — suivie de la question *« qui suis-je ? »* avec le token reçu :

**login-curl.sh**

```bash
#!/usr/bin/env bash
set -euo pipefail

# Step 1. Log in, then dig the token out of the JSON answer with jq
TOKEN=$(curl --silent --fail \
    --header 'Content-Type: application/json' \
    --data "{\"username\": \"${API_USERNAME}\", \"password\": \"${API_PASSWORD}\"}" \
    https://dummyjson.com/auth/login | jq --raw-output '.accessToken')

# Step 2. Call the protected endpoint with that token
curl --silent --fail \
    --header "Authorization: Bearer ${TOKEN}" \
    https://dummyjson.com/auth/me | jq '{username, email}'

# ...and checking the answer is still up to you
```

```bash
$ API_USERNAME=emilys API_PASSWORD=emilyspass ./login-curl.sh
{
  "username": "emilys",
  "email": "emily.johnson@x.dummyjson.com"
}
```

Et voici la même conversation en deux étapes, écrite pour Hurl :

**login.hurl**

```hurl
# Step 1. Log in and get an access token
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Use the token to ask "who am I?"
GET https://dummyjson.com/auth/me
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.username" == "{{username}}"
jsonpath "$.email" endsWith "@x.dummyjson.com"
```

Pas de `jq`, pas de variable shell, pas de casse-tête de quotes autour du corps JSON : le token capturé à l'étape 1 s'écrit simplement `{{token}}` à l'étape 2. Et les deux lignes sous `[Asserts]` vérifient la réponse — le script `curl`, lui, vous laisse ce travail. Lancez-le :

```bash
$ hurl --test --variable username=emilys --secret password=emilyspass login.hurl
Success login.hurl (2 request(s) in 3142 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (0.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3145 ms (0h:0m:3s:145ms)
```

Maintenant avec un mauvais mot de passe :

```bash
$ hurl --test --variable username=emilys --secret password=oops login.hurl
error: Assert status code
  --> login.hurl:8:6
   |
   | POST https://dummyjson.com/auth/login
   | ...
 8 | HTTP 200
   |      ^^^ actual value is <400>
   |

Failure login.hurl (1 request(s) in 118 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (8.2/s)
Succeeded files:   0 (0.0%)
Failed files:      1 (100.0%)
Duration:          122 ms (0h:0m:0s:122ms)
```

Hurl pointe la ligne exacte qui a échoué, dit ce qu'il a obtenu à la place, n'envoie jamais la deuxième requête, et se termine avec un code non nul — tout ce qu'un script, une tâche cron ou un pipeline CI a besoin de savoir.

## Pourquoi ça marche {#why-it-works}

* **Un seul fichier contient toute la recette.** Chaque étape de la conversation se trouve dans le même fichier, dans l'ordre où elle se produit. Ce que `[Captures]` retient d'une réponse — un token, un id, un cookie — devient une variable pour toutes les requêtes en dessous.
* **Un non-développeur sait le lire.** Une adresse, quelques lignes `Name: value`, la réponse attendue. Pas de pipes, pas de quotes échappées, pas de `$(...)`. Quelqu'un qui n'a jamais ouvert un terminal comprend quand même ce que fait le fichier, et repère l'URL qui a changé.
* **Les vérifications voyagent avec les requêtes.** Le statut attendu et la checklist `[Asserts]` vivent juste sous la requête qu'ils vérifient : le fichier documente l'API *et* son contrat.
* **Aucun secret dans le fichier.** Uniquement des champs comme `{{password}}`, remplis à l'exécution ; les valeurs passées avec `--secret` sont masquées dans tous les logs affichés par Hurl.
* **C'est curl en dessous.** Hurl est construit sur libcurl : proxies, certificats et HTTP/2 se comportent exactement comme le `curl` auquel vous faites déjà confiance.
* **Un binaire, trois systèmes.** Windows, Linux et macOS, gratuit et open source (Apache 2.0), maintenu par Orange.

## Installer Hurl {#installing-hurl}

Hurl est packagé pour tous les systèmes ; prenez la première ligne qui correspond au vôtre.

```bash
$ brew install hurl            # macOS, Linux and WSL (Homebrew)
$ winget install Orange-OpenSource.Hurl   # Windows
```

**Debian / Ubuntu : le .deb officiel (Hurl n'est pas dans l'archive Ubuntu)**

Ubuntu ne package pas Hurl, mais chaque release GitHub fournit un `.deb`, sa somme de contrôle et une attestation de provenance de build signée :

```bash
$ VERSION=8.1.0
$ curl -LO "https://github.com/Orange-OpenSource/hurl/releases/download/${VERSION}/hurl_${VERSION}_amd64.deb"
$ curl -LO "https://github.com/Orange-OpenSource/hurl/releases/download/${VERSION}/hurl_${VERSION}_amd64.deb.sha256"
$ sha256sum -c "hurl_${VERSION}_amd64.deb.sha256"
$ gh attestation verify "hurl_${VERSION}_amd64.deb" --repo Orange-OpenSource/hurl
$ sudo apt install "./hurl_${VERSION}_amd64.deb"
```

La somme de contrôle prouve seulement que le téléchargement n'a pas été tronqué ; c'est la ligne `gh attestation verify` qui prouve que le fichier a bien été produit par le workflow GitHub de Hurl.

**Rien à installer : l'image Docker**

```bash
$ docker run --rm ghcr.io/orange-opensource/hurl:8.1.0 --version
```

Ensuite, dans chaque commande de cet article, remplacez `hurl` par `docker run --rm -v "$PWD":/work -w /work ghcr.io/orange-opensource/hurl:8.1.0`. Pour passer les variables `HURL_VARIABLE_...` et `HURL_SECRET_...` du chapitre sur la suite de tests, ajoutez `-e HURL_VARIABLE_username -e HURL_SECRET_password` juste après `--rm` : un container n'hérite pas de l'environnement de votre shell.

Vérifiez que c'est bien dans votre `PATH` :

```bash
$ hurl --version
hurl 8.1.0 (x86_64-alpine-linux-musl) libcurl/8.23.0 OpenSSL/3.5.9 zlib/1.3.2 brotli/brotli/1.2.1 zstd/zstd/1.5.7 c-ares/1.34.9 libidn2/2.3.8 nghttp2/1.70.0
```

## Anatomie d'un fichier `.hurl` {#anatomy-of-a-hurl-file}

Un fichier `.hurl` est une liste d'**entrées**, exécutées de haut en bas. Chaque entrée est une requête suivie, en option, de la réponse qu'elle attend :

| Partie         | Exemple                                         | Signification                                                         |
| -------------- | ----------------------------------------------- | --------------------------------------------------------------------- |
| Méthode et URL | `POST https://dummyjson.com/auth/login`         | la seule ligne obligatoire                                            |
| En-têtes       | `Authorization: Bearer {{token}}`               | un `Name: value` par ligne, juste en dessous                          |
| Sections       | `[Query]`, `[Form]`, `[BasicAuth]`, `[Options]` | query string, champs de formulaire, identifiants, options par requête |
| Corps          | un objet JSON, un document XML ou du texte brut | envoyé tel quel, après les en-têtes                                   |
| Statut         | `HTTP 200`                                      | la réponse **doit** avoir ce code, sinon Hurl s'arrête                |
| `[Captures]`   | `token: jsonpath "$.accessToken"`               | garder une valeur de la réponse pour plus tard                        |
| `[Asserts]`    | `jsonpath "$.username" == "emilys"`             | la checklist sur la réponse                                           |

Les lignes commençant par `#` sont des commentaires, pour les humains uniquement.

### Les champs `{{ }}` à remplir {#the---blanks}

Un nom entre doubles accolades est rempli juste avant le départ de la requête :

| Champ          | Rempli avec                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| `{{username}}` | une variable donnée en ligne de commande, dans un fichier ou dans l'environnement           |
| `{{token}}`    | une valeur capturée par une entrée précédente                                               |
| `{{newUuid}}`  | un nouvel UUID aléatoire, généré à chaque exécution — pratique pour un identifiant de trace |
| `{{newDate}}`  | la date et l'heure courantes, ISO 8601                                                      |

Comme le fichier ne contient que des champs vides, il peut être commité et partagé : personne ne peut s'en servir sans les valeurs.

## Remplir les champs sans divulguer de secrets {#filling-the-blanks-without-leaking-secrets}

Quatre façons de donner ses valeurs à Hurl, de la plus explicite à la plus automatique :

| Option             | Exemple                                                     | Remarque                                                            |
| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------- |
| `--variable`       | `--variable username=emilys`                                | affiché tel quel dans les logs verbeux                              |
| `--secret`         | `--secret password=emilyspass`                              | remplacé par `***` partout où Hurl affiche quelque chose            |
| `--variables-file` | `--variables-file vars.env`                                 | un `name=value` par ligne                                           |
| Environnement      | `HURL_VARIABLE_username=emilys`, `HURL_SECRET_password=...` | parfait pour la CI, où les secrets vivent déjà dans l'environnement |

Le schéma habituel garde les identifiants dans un fichier `.env` — [chargé par le shell](/blog/bash-load-env) — qui n'est jamais commité, et la recette dans le fichier `.hurl` qui, lui, l'est. L'occasion d'essayer sur votre machine : les deux fichiers ci-dessous sont la recette `login.hurl` du début de cet article et son `.env`.

**Project: hurl-demo**

> **Note:**
>
> Maintenant, lancez la commande ci-dessous depuis le dossier hurl-demo.

**login.hurl**

```hurl
# Step 1. Log in and get an access token
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Use the token to ask "who am I?"
GET https://dummyjson.com/auth/me
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.username" == "{{username}}"
jsonpath "$.email" endsWith "@x.dummyjson.com"
```

**.env**

```
API_USERNAME="emilys"
API_PASSWORD="emilyspass"
```

```bash
$ source .env && hurl --test --variable "username=${API_USERNAME}" --secret "password=${API_PASSWORD}" login.hurl
Success login.hurl (2 request(s) in 3132 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (0.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3135 ms (0h:0m:3s:135ms)
```

Le masquage de `--secret` ne se limite pas à la ligne de commande. Avec `--very-verbose`, Hurl affiche la requête qu'il envoie — sous forme de commande `curl` équivalente — **et** la réponse qu'il reçoit, et le mot de passe est caché dans les deux, y compris dans le profil utilisateur renvoyé par DummyJSON :

```plaintext
* curl --header 'Content-Type: application/json' --data $'{\n  "username": "emilys",\n  "password": "***"\n}' 'https://dummyjson.com/auth/login'
...
* {"id":1,"firstName":"Emily","lastName":"Johnson",...,"username":"emilys","password":"***",...}
```

Un log verbeux peut donc être collé dans un ticket sans arrière-pensée.

## Assertions : la checklist de chaque réponse {#assertions-the-checklist-on-every-answer}

`HTTP 200` dit que le serveur a répondu *« OK »*. Il ne dit rien sur **ce qu'il** a répondu : une liste vide, un champ manquant et un CSV écrit à moitié reviennent tous avec un 200. C'est le travail de `[Asserts]`.

Ce fichier demande à DummyJSON tous ses utilisateurs et vérifie que la liste est complète et bien formée :

**users.hurl**

```hurl
# Every user must have a first name, a last name and an email
GET https://dummyjson.com/users
[Query]
limit: 0
select: firstName,lastName,email
HTTP 200
[Asserts]
header "Content-Type" contains "application/json"
jsonpath "$.users" isCollection
jsonpath "$.users" count == 208
jsonpath "$.total" == 208
jsonpath "$.users[?!@.firstName]" not exists
jsonpath "$.users[?!@.lastName]" not exists
jsonpath "$.users[?!@.email]" not exists
jsonpath "$.users[0].email" matches /^[a-z.]+@x\.dummyjson\.com$/
duration < 5000
```

Ligne par ligne :

* `header "Content-Type" contains ...` — le serveur annonce qu'il envoie du JSON.
* `jsonpath "$.users" isCollection` puis `count == 208` — `$.users` est une liste, avec exactement 208 entrées.
* `jsonpath "$.users[?!@.firstName]" not exists` — *ne garder que les utilisateurs sans prénom*, et il ne doit y en avoir aucun. Lisez les trois lignes ensemble comme *« chaque utilisateur a un prénom, un nom et un email »*.
* `matches /.../` — une expression régulière sur une valeur.
* `duration < 5000` — la réponse est arrivée en moins de cinq secondes.

Lancez-le — toutes les vérifications passent :

```bash
$ hurl --test users.hurl
Success users.hurl (1 request(s) in 3104 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (0.3/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3108 ms (0h:0m:3s:108ms)
```

Cassez maintenant une vérification volontairement : à la ligne 11, remplacez `jsonpath "$.total" == 208` par `jsonpath "$.total" == 200`, puis relancez la même commande. Hurl affiche la valeur attendue à côté de la valeur réelle :

```bash
$ hurl --test users.hurl
error: Assert failure
  --> users.hurl:11:0
   |
   | GET https://dummyjson.com/users
   | ...
11 | jsonpath "$.total" == 200
   |   actual:   integer <208>
   |   expected: integer <200>
   |

Failure users.hurl (1 request(s) in 102 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (9.5/s)
Succeeded files:   0 (0.0%)
Failed files:      1 (100.0%)
Duration:          105 ms (0h:0m:0s:105ms)
```

Remettez `208` à la ligne 11 avant de continuer : les chapitres suivants réutilisent ce fichier.

> **Un filtre vide n'est pas une liste vide:**
>
> Un filtre JSONPath qui ne correspond à rien ne renvoie **aucune valeur** dans Hurl, pas un tableau vide. Donc « personne n'a de prénom manquant » s'écrit `not exists` ; `isEmpty` échouerait avec `actual: none`.

### Les prédicats les plus utilisés {#the-predicates-you-will-use-most}

| Prédicat                                             | Exemple                                       |
| ---------------------------------------------------- | --------------------------------------------- |
| `==`, `!=`, `>`, `>=`, `<`, `<=`                     | `jsonpath "$.total" >= 100`                   |
| `contains`, `startsWith`, `endsWith`                 | `body startsWith "Name,Code"`                 |
| `matches`                                            | `jsonpath "$.email" matches /@example\.com$/` |
| `exists`, `isEmpty`, `count`                         | `jsonpath "$.users" count > 0`                |
| `isCollection`, `isString`, `isInteger`, `isBoolean` | `jsonpath "$.users" isCollection`             |
| `isIsoDate`, `isUuid`                                | `jsonpath "$.createdAt" isIsoDate`            |

N'importe quel prédicat peut être nié avec `not`, et les queries vont bien au-delà du JSON : `status`, `header`, `cookie`, `body`, `bytes`, `xpath`, `regex`, `sha256`, `duration`, `url`, `redirects`…

## Au-delà du JSON {#beyond-json}

[httpbin.org](https://httpbin.org) est un service gratuit qui renvoie en écho ce qu'il reçoit — parfait pour essayer les autres types de requêtes. Ce seul fichier envoie un formulaire (la forme d'un appel OAuth2 `client_credentials`), utilise l'authentification basique, génère un identifiant de trace, attend un 404 **volontairement**, vérifie une page HTML avec XPath et suit les redirections :

**features.hurl**

```hurl
# A form, exactly like an OAuth2 client_credentials call
POST https://httpbin.org/post
[Form]
grant_type: client_credentials
client_id: my-app
HTTP 200
[Asserts]
jsonpath "$.form.grant_type" == "client_credentials"
jsonpath "$.headers['Content-Type']" == "application/x-www-form-urlencoded"

# Basic authentication
GET https://httpbin.org/basic-auth/bob/s3cr3t
[BasicAuth]
bob: s3cr3t
HTTP 200
[Asserts]
jsonpath "$.authenticated" == true

# A trace id, generated at every run
GET https://httpbin.org/headers
X-Trace-Id: blog-{{newUuid}}
HTTP 200
[Asserts]
jsonpath "$.headers['X-Trace-Id']" matches /^blog-[0-9a-f-]{36}$/

# Expect an error on purpose
GET https://httpbin.org/status/404
HTTP 404

# HTML, checked with XPath
GET https://httpbin.org/html
HTTP 200
[Asserts]
header "Content-Type" contains "text/html"
xpath "string(//h1)" == "Herman Melville - Moby-Dick"
body contains "Moby-Dick"

# Redirects: follow them, and check where we landed
GET https://httpbin.org/redirect/2
[Options]
location: true
HTTP 200
[Asserts]
url == "https://httpbin.org/get"
redirects count == 2
```

```bash
$ hurl --test features.hurl
Success features.hurl (8 request(s) in 3998 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 8 (2.0/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          4002 ms (0h:0m:4s:2ms)
```

Huit requêtes pour six entrées : suivre les deux redirections de la dernière entrée en coûte deux de plus.

Trois détails méritent l'attention :

* `HTTP 404` est une attente parfaitement valable. Tester qu'une ressource supprimée a bien disparu, ou qu'un mauvais token est bien refusé, est aussi important que tester le cas nominal.
* Une clé JSON contenant un tiret s'écrit avec des crochets : `$.headers['X-Trace-Id']`, pas `$.headers.X-Trace-Id`.
* `[Options]` ne change le comportement que d'une seule requête — ici `location: true` suit les redirections, et `redirects count == 2` vérifie le nombre de sauts effectués.

### Télécharger un fichier, et le vérifier d'abord {#downloading-a-file-and-checking-it-first}

`output:` écrit le corps de la réponse dans un fichier au lieu du terminal — ici une liste CSV de pays issue d'un dataset GitHub public :

**countries.hurl**

```hurl
# Download a CSV file, check it, keep it
GET https://raw.githubusercontent.com/datasets/country-list/main/data.csv
[Options]
output: countries.csv
HTTP 200
[Asserts]
header "Content-Type" contains "text/plain"
bytes count > 1000
body startsWith "Name,Code"
body contains "Belgium,BE"
body split "\n" count > 200
```

```bash
$ hurl --test countries.hurl
Success countries.hurl (1 request(s) in 3240 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (0.3/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3243 ms (0h:0m:3s:243ms)

$ head -4 countries.csv
Name,Code
Afghanistan,AF
Albania,AL
Algeria,DZ
```

`body startsWith` garantit que les titres de colonnes sont là, dans le bon ordre ; `body split "\n" count > 200` s'assure que le fichier n'a pas été coupé au milieu. Et quand une de ces vérifications échoue, Hurl **n'écrit pas le fichier du tout** : une mauvaise réponse n'atterrit jamais sur le disque.

## Côté développeur d'API : les fichiers `.hurl` comme tests {#for-the-api-developer-hurl-files-as-tests}

Vu du côté de celui qui construit l'API, un dossier de fichiers `.hurl` est une suite de tests : chaque fichier est un scénario, chaque ligne `[Asserts]` un test. Donnez plusieurs fichiers à Hurl et `--test` les exécute **en parallèle**, puis affiche un résumé ; deux options supplémentaires produisent un rapport HTML pour les humains et un fichier XML JUnit pour la CI :

```bash
$ HURL_VARIABLE_username=emilys HURL_SECRET_password=emilyspass hurl --test --report-html report/ --report-junit junit.xml *.hurl
Success countries.hurl (1 request(s) in 105 ms)
Success users.hurl (1 request(s) in 137 ms)
Success login.hurl (2 request(s) in 223 ms)
Success features.hurl (8 request(s) in 971 ms)
--------------------------------------------------------------------------------
Executed files:    4
Executed requests: 12 (12.2/s)
Succeeded files:   4 (100.0%)
Failed files:      0 (0.0%)
Duration:          986 ms (0h:0m:0s:986ms)
```

Les deux variables `HURL_...` sont écrites devant la commande : elles n'existent que pour cette exécution. Un `export` garderait `HURL_SECRET_password` dans votre shell, et chaque `--secret password=...` ultérieur s'arrêterait alors avec `secret 'password' can't be reassigned`.

Douze requêtes dans les quatre fichiers créés jusqu'ici, exécutées dans le temps de la plus lente. Le code de sortie indique au pipeline ce qui s'est passé : `0` tout est passé, `2` un fichier `.hurl` n'a pas pu être parsé, `3` une requête n'a pas pu être envoyée du tout (DNS, TLS, timeout…), `4` une assertion a échoué.

Pour exécuter les mêmes scénarios contre votre portable, le serveur de staging et la production, remplacez l'host par un champ à remplir — à la ligne 2 de `users.hurl` :

```plaintext title="users.hurl"
GET {{base_url}}/users
```

L'host se choisit désormais en ligne de commande. Ici c'est toujours DummyJSON ; sur votre propre API, ce serait `http://localhost:8000` sur votre portable et l'adresse de staging dans la CI, avec exactement les mêmes fichiers :

```bash
$ HURL_VARIABLE_username=emilys HURL_SECRET_password=emilyspass hurl --test --variable base_url=https://dummyjson.com *.hurl
Success countries.hurl (1 request(s) in 96 ms)
Success login.hurl (2 request(s) in 161 ms)
Success users.hurl (1 request(s) in 170 ms)
Success features.hurl (8 request(s) in 977 ms)
--------------------------------------------------------------------------------
Executed files:    4
Executed requests: 12 (12.1/s)
Succeeded files:   4 (100.0%)
Failed files:      0 (0.0%)
Duration:          991 ms (0h:0m:0s:991ms)
```

Contrairement aux tests unitaires, ceux-ci parlent à l'API réelle, en train de tourner — routage, authentification, sérialisation et base de données compris — exactement comme le fera un client.

## Côté consommateur d'API : une recette que vous pouvez transmettre {#for-the-api-consumer-a-recipe-you-can-hand-over}

Passons de l'autre côté. Votre client veut le catalogue produits dans sa propre base de reporting, rafraîchi chaque nuit. Au lieu d'une page de documentation et d'un « bonne chance », envoyez-lui ce fichier :

**products.hurl**

```hurl
# Daily export of the product catalog, for the reporting database

# Step 1. Log in
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Download the catalog, check it, then save it
GET https://dummyjson.com/auth/products
Authorization: Bearer {{token}}
[Query]
limit: 0
select: title,category,price,stock
[Options]
output: products.json
HTTP 200
[Asserts]
jsonpath "$.products" count > 100
jsonpath "$.products[?!@.title]" not exists
jsonpath "$.products[?@.price <= 0]" not exists
```

Il sait le lire — se connecter, télécharger le catalogue, vérifier qu'il y a plus de cent produits, tous avec un titre et un prix positif, l'enregistrer — et l'exécuter :

```bash
$ hurl --test --variable username=emilys --secret password=emilyspass products.hurl
Success products.hurl (2 request(s) in 134 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (14.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          137 ms (0h:0m:0s:137ms)
```

`products.json` est maintenant sur le disque, et [DuckDB](/blog/duckdb-json-csv) le transforme en table avec une seule instruction SQL — pas d'outil d'import, pas de schéma à déclarer. La commande ci-dessous utilise la fonction `duckdb` basée sur Docker de cet article, où `--write` autorise l'écriture de `catalog.duckdb` dans le dossier courant ; avec un DuckDB natif, supprimez `--write` :

**load.sql**

```sql
CREATE OR REPLACE TABLE products AS
    SELECT unnest(products, recursive := true)
    FROM read_json_auto('products.json');

SELECT category, count(*) AS items, sum(stock) AS in_stock
FROM products
GROUP BY category
ORDER BY in_stock DESC
LIMIT 5;
```

```bash
$ duckdb --write catalog.duckdb < load.sql
┌─────────────────────┬───────┬──────────┐
│      category       │ items │ in_stock │
│       varchar       │ int64 │  int128  │
├─────────────────────┼───────┼──────────┤
│ kitchen-accessories │    30 │     1656 │
│ groceries           │    27 │     1417 │
│ sports-accessories  │    17 │      871 │
│ smartphones         │    16 │      695 │
│ mobile-accessories  │    14 │      531 │
└─────────────────────┴───────┴──────────┘
```

Mettez les deux étapes dans un script, et laissez cron l'exécuter chaque nuit. cron ne charge pas les fonctions de votre shell, donc le script appelle directement l'image `duckdb-cli` construite dans l'article sur DuckDB :

**refresh-catalog.sh**

```bash
#!/usr/bin/env bash
# Refresh catalog.duckdb with today's product catalog.
# Meant to run from cron; credentials come from the .env file next to it.
set -euo pipefail

cd "$(dirname "$0")"

# API_USERNAME and API_PASSWORD
# shellcheck source=/dev/null
source ./.env

# 1. Download and check. When an assertion fails, Hurl does not write
#    products.json and exits non-zero: set -e stops the script right here
#    and the database keeps yesterday's data.
hurl --test \
    --variable "username=${API_USERNAME}" \
    --secret "password=${API_PASSWORD}" \
    products.hurl

# 2. Load the checked file into DuckDB (duckdb-cli image, see the DuckDB article)
docker run --rm -i \
    -v "${PWD}:/workspace" \
    -w /workspace \
    -u "$(id -u):$(id -g)" \
    duckdb-cli catalog.duckdb < load.sql
```

```plaintext title="crontab -e"
0 2 * * * /home/me/catalog/refresh-catalog.sh >> /home/me/catalog/refresh.log 2>&1
```

C'est là que les assertions se rentabilisent. La nuit où l'API répond 200 avec une liste vide, ou un prix à zéro, Hurl refuse la réponse, n'écrit rien, et `set -e` arrête le script avant DuckDB : la base garde les données de la veille au lieu d'être silencieusement vidée, et `refresh.log` nomme la ligne exacte qui a échoué.

## Vous avez déjà une commande `curl` ? {#already-have-a-curl-command}

Hurl est livré avec `hurlfmt`, qui convertit une ligne de commande `curl` en entrée Hurl — le moyen le plus rapide de faire passer un historique shell dans un fichier :

````bash
$ echo "curl -X POST https://dummyjson.com/auth/login -H 'Content-Type: application/json' -d '{\"username\":\"emilys\",\"password\":\"emilyspass\"}'" | hurlfmt --in curl
POST https://dummyjson.com/auth/login
Content-Type: application/json
```
{"username":"emilys","password":"emilyspass"}
```
````

Ajoutez un `HTTP 200` et deux ou trois assertions en dessous, et la commande ponctuelle devient une vérification réutilisable.

## Hurl, curl et les clients graphiques {#hurl-curl-and-the-gui-clients}

|                                   | `curl`                                   | Hurl                               |
| --------------------------------- | ---------------------------------------- | ---------------------------------- |
| Lisible par un non-développeur    | 😕                                       | 🙂                                 |
| Enchaîner plusieurs appels        | variables shell + [`jq`](/blog/linux-jq) | `[Captures]`, dans un seul fichier |
| Vérifier chaque réponse           | à l'œil                                  | `HTTP 200` + `[Asserts]`           |
| Masquer les secrets dans les logs | ❌                                        | `--secret`                         |
| Natif sous Windows                | 😕                                       | ✅                                  |

Si vous préférez cliquer plutôt que taper, [Postman](/blog/postman) et [Bruno](/blog/bruno) couvrent le même terrain avec une interface graphique. Hurl est le choix inverse : aucune interface, un fichier texte qui se diffe proprement dans une pull request et s'exécute à l'identique sur un portable, en CI et dans un crontab.

## Conclusion {#conclusion}

La danse du token du début de cet article — `curl`, `jq`, une variable, `curl` à nouveau, puis plisser les yeux sur la sortie — tient désormais dans un fichier lisible qui se connecte, garde le token, appelle l'API et vérifie la réponse, champ par champ. Le développeur exécute un dossier entier comme suite de tests ; le client en exécute un chaque nuit pour alimenter une base, protégé par ces mêmes assertions. Commencez par la requête que vous tapez le plus souvent : passez-la dans `hurlfmt`, ajoutez une ligne `[Asserts]`, et commitez-la à côté du code qui dépend de cette API.
