Un outil de test d'API sans interface graphique (headless) exécute vos tests depuis la ligne de commande, sans fenêtre à ouvrir ni action manuelle. L’intérêt est simple : lancer les mêmes vérifications à chaque push dans un pipeline CI, faire échouer la build si une assertion casse, puis publier des rapports exploitables. Ce guide explique ce qu’un runner API headless doit faire, comment utiliser la CLI Apidog, et quand préférer des alternatives comme Newman ou Hurl.
Ce que "headless" signifie pour le test d'API
Un outil de test d'API headless est conçu pour être automatisé. Il doit pouvoir :
- s’exécuter via une commande CLI ;
- fonctionner sans écran, session utilisateur ou interaction manuelle ;
- charger les tests depuis un fichier, une collection, une suite ou un ID de projet ;
- retourner un code de sortie non nul quand une assertion échoue ;
- générer des rapports lisibles par un humain et par une machine : CLI, HTML, JSON, JUnit XML.
Le point clé est le code de sortie. Une interface graphique informe un développeur. Un runner headless informe un pipeline. C’est ce qui permet de bloquer une merge request, d’arrêter un déploiement ou de détecter une régression avant qu’elle n’atteigne les utilisateurs.
Pour structurer ce flux dans vos pipelines, consultez aussi les meilleures pratiques CI/CD pour les tests d'API.
Pourquoi sortir les tests API de l’interface graphique
Un client visuel est utile pour :
- explorer un endpoint ;
- ajuster des headers ;
- inspecter une réponse ;
- écrire rapidement une assertion.
Mais il est mauvais pour la répétition. Vous ne voulez pas demander à quelqu’un de relancer manuellement quarante requêtes après chaque commit.
Un runner headless résout ce problème :
runner api-tests
La même commande peut tourner :
- sur votre machine locale ;
- sur celle d’un collègue ;
- dans GitHub Actions, GitLab CI, Jenkins ou tout autre système CI ;
- dans un job planifié de monitoring.
Ajoutez des fichiers CSV ou JSON en entrée, et un seul scénario peut couvrir plusieurs cas : utilisateurs valides, données invalides, tokens expirés, rôles différents, etc.
Cette cohérence est particulièrement importante si votre API est traitée comme un produit. Voir aussi : API comme un produit.
Apidog CLI : exécuter vos scénarios API sans GUI
Apidog CLI est le runner headless d’Apidog. Le workflow typique est le suivant :
- Concevoir ou importer votre API dans Apidog.
- Créer vos scénarios de test et assertions dans l’application.
- Exécuter ces scénarios depuis le terminal avec
apidog run. - Générer des rapports pour la CI.
- Faire échouer le pipeline si les tests échouent.
La commande apidog run peut exécuter des scénarios, dossiers, suites de tests ou fichiers exportés localement.
Exemple minimal :
npm install -g apidog-cli
apidog run https://api.apidog.com/... \
-e <id-environnement> \
-r cli,html,junit
Dans ce flux, Apidog sert à la fois à concevoir, documenter, tester et exécuter les scénarios.
Ajouter des données de test avec CSV ou JSON
Pour exécuter le même scénario avec plusieurs jeux de données, utilisez l’option :
-d, --iteration-data <path>
Exemple avec un fichier CSV :
apidog run https://api.apidog.com/... \
-e <id-environnement> \
-d ./data/users.csv \
-r cli,html,junit
Vous pouvez aussi limiter le nombre d’itérations :
apidog run https://api.apidog.com/... \
-d ./data/users.csv \
-n 10
Ce modèle est utile pour tester :
- plusieurs profils utilisateurs ;
- des payloads invalides ;
- des variations de permissions ;
- des formats de données différents ;
- des cas limites.
Le fonctionnement complet est détaillé dans le guide sur le test d'API piloté par les données avec l'Apidog CLI.
Générer des rapports exploitables en CI
Apidog CLI prend en charge plusieurs formats via :
-r, --reporters
Exemple :
apidog run https://api.apidog.com/... \
-r cli,html,json,junit
Formats courants :
-
cli: lecture rapide dans les logs ; -
html: rapport consultable comme artefact ; -
json: post-traitement personnalisé ; -
junit: intégration dans les panneaux de tests CI.
Par défaut, les rapports HTML et JUnit sont générés dans :
apidog-reports/
Vous pouvez ensuite les publier comme artefacts de build dans votre pipeline.
Injecter les variables d’environnement au runtime
Évitez de commiter des secrets ou des valeurs propres à un environnement. Utilisez plutôt :
-e <id-environnement>
--env-var clé=valeur
--global-var clé=valeur
Exemple :
apidog run https://api.apidog.com/... \
-e <id-environnement-staging> \
--env-var base_url=https://staging.example.com \
--env-var token=$API_TOKEN \
-r cli,junit
Ce modèle permet de garder vos tests versionnés tout en injectant les secrets depuis votre système CI.
Exemple GitHub Actions
Voici une base simple pour exécuter Apidog CLI dans GitHub Actions :
name: API tests
on:
push:
branches: [main]
pull_request:
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API tests
run: |
apidog run https://api.apidog.com/... \
-e ${{ secrets.APIDOG_ENV_ID }} \
--env-var token=${{ secrets.API_TOKEN }} \
-d ./data/users.csv \
-r cli,html,junit
- name: Upload reports
uses: actions/upload-artifact@v4
if: always()
with:
name: apidog-reports
path: apidog-reports/
Pour démarrer depuis zéro, consultez le guide complet d'Apidog CLI, le tutoriel REST API en ligne de commande, ou la référence de commande apidog run.
Autre usage headless : Apidog MCP
Apidog propose aussi une capacité headless différente avec le serveur Apidog MCP.
L’idée : permettre à un agent IA ou un IDE compatible IA, comme Cursor ou VS Code via Cline, de lire vos spécifications API directement. L’assistant peut alors générer du code ou des tests à partir du contrat réel au lieu de deviner la structure des endpoints.
C’est un autre type de workflow sans GUI : la spécification API pilote l’agent.
Le flux est détaillé dans le guide sur le débogage visuel avec le client Apidog MCP.
Alternatives headless à connaître
Apidog n’est pas la seule option. Le bon choix dépend surtout de l’endroit où vos tests vivent déjà.
Newman
Newman est le runner CLI des collections Postman.
Utilisez-le si vos collections Postman sont déjà votre source de vérité.
Exemple :
npm install -g newman
newman run collection.json \
-e environment.json \
-d data.csv \
-r cli,json,junit
Newman prend en charge plusieurs rapporteurs intégrés : cli, json, junit, progress, emojitrain. Le rapport HTML est disponible via un package npm séparé.
Hurl
Hurl adopte une approche texte brut. Vous écrivez les requêtes et assertions dans un fichier .hurl, puis vous l’exécutez depuis le terminal.
Exemple simplifié :
GET https://api.example.com/users/1
HTTP 200
[Asserts]
jsonpath "$.id" == 1
Puis :
hurl test.hurl
Hurl est pertinent si vous préférez des tests versionnés, lisibles comme du HTTP, sans dépendre d’une interface projet.
Hoppscotch CLI
Hoppscotch CLI, via la commande hopp, exécute les collections Hoppscotch en CI.
Vous pouvez utiliser :
- une collection exportée en JSON ;
- un environnement exporté ;
- des IDs de collection et d’environnement avec un jeton d’accès ;
- des données d’itération CSV ;
- un rapporteur JUnit via
--reporter-junit.
C’est un choix logique si votre équipe utilise déjà Hoppscotch. Pour comparer, consultez les meilleures alternatives à Hoppscotch CLI.
Comparaison rapide des runners headless
| Outil | Source de test | Données d’itération | Rapporteurs intégrés | Meilleur choix si |
|---|---|---|---|---|
| Apidog CLI | Projet Apidog, suites ou fichier exporté | CSV / JSON avec -d
|
cli, html, json, junit
|
Vous voulez conception, mock, test et documentation dans un seul projet |
| Newman | Collections Postman | CSV / JSON avec -d
|
cli, json, junit, progress ; HTML via module complémentaire |
Postman est votre source de vérité |
| Hurl | Fichiers .hurl
|
CSV via les options du runner | JUnit, TAP, JSON | Vous préférez des tests HTTP en texte brut |
| Hoppscotch CLI | Collections Hoppscotch, fichier ou ID | CSV avec --iteration-data
|
JUnit | Votre équipe utilise déjà Hoppscotch |
Tous ces outils sont réellement headless : ils s’exécutent en ligne de commande, n’ont pas besoin de GUI et retournent un statut exploitable par la CI.
La différence d’Apidog est organisationnelle : les scénarios exécutés par la CLI peuvent vivre dans le même projet que le contrat API, les mocks et la documentation.
Comment choisir le bon outil
Commencez par une question simple : où sont vos tests aujourd’hui ?
- Collections Postman existantes ? Utilisez Newman.
- Tests HTTP en texte brut ? Utilisez Hurl.
- Collections Hoppscotch existantes ? Utilisez Hoppscotch CLI.
- Besoin de centraliser contrat, mock, tests et documentation ? Utilisez Apidog CLI.
Si vous partez de zéro, privilégiez l’outil qui réduit le nombre de sources de vérité. Plus vos contrats, mocks, tests et docs sont séparés, plus ils risquent de diverger.
FAQ
Un outil de test d'API headless est-il la même chose qu'un outil CLI ?
Dans la pratique, oui.
"Headless" décrit l’absence d’interface graphique. "CLI" décrit le mode de contrôle par ligne de commande. Un outil de test d’API headless est presque toujours un outil CLI.
Ce qui compte pour la CI :
- exécution sans intervention humaine ;
- code de sortie fiable ;
- rapports exploitables ;
- configuration reproductible.
Puis-je exécuter des tests headless sans écrire de scripts ?
Oui, selon l’outil.
Avec Apidog, vous pouvez créer vos assertions visuellement, puis exécuter les mêmes scénarios depuis la CLI. Vous n’avez pas besoin d’écrire un harnais de test complet.
Newman et Hoppscotch CLI exécutent des collections qui peuvent contenir des scripts ou assertions créés dans leurs applications. Hurl, lui, repose sur des fichiers texte que vous écrivez directement.
Pour un workflow visuel puis headless, consultez le guide complet d'Apidog CLI.
Les tests d'API headless nécessitent-ils un backend réel ?
Pas toujours.
Vous pouvez pointer vos tests vers :
- un environnement local ;
- une URL de staging ;
- un service déjà déployé ;
- un serveur mock.
Utiliser un mock en CI permet de valider les contrats, payloads et formats de réponse avant que le backend final soit prêt. C’est utile pour débloquer le frontend ou les intégrations parallèles.
Quel runner headless choisir pour la CI/CD ?
Il n’y a pas de gagnant universel.
Le meilleur outil est celui qui exécute vos tests actuels avec le moins de friction. Si vous consolidez votre stack ou démarrez un nouveau projet, Apidog CLI est intéressant parce qu’il regroupe conception, mock, test et documentation dans un même projet.
Pour approfondir les compromis, consultez :
Pour conclure
Un outil de test d’API headless est un runner automatisable : une commande que vous pouvez lancer localement, paramétrer avec des données, intégrer à la CI et faire échouer en cas de régression.
Newman, Hurl et Hoppscotch CLI fonctionnent très bien dans leurs écosystèmes respectifs. Apidog CLI ajoute l’avantage d’un projet unique pour le contrat, les mocks, les tests et la documentation.
Téléchargez Apidog pour concevoir un scénario une fois, puis l’exécuter en mode headless partout.
Top comments (0)