Vous voulez des tests d'API qui se lisent comme de l'anglais simple, vivent dans Git à côté de votre code et s'exécutent dans n'importe quel pipeline CI. Karate est conçu exactement pour cela. Il utilise un langage spécifique à un domaine (DSL) pour que vous écriviez des tests sous forme d'étapes Given / When / Then au lieu de méthodes Java. Ce guide explique ce qu'est Karate, comment fonctionnent ses fichiers de fonctionnalités et présente un exemple exécutable.
Qu'est-ce que Karate
Karate est un framework d'automatisation de tests open-source, basé sur Java, pour les API. Vous décrivez chaque test comme un scénario dans un fichier .feature en utilisant Gherkin, la même structure Given/When/Then qui provient du développement axé sur le comportement (Behavior-Driven Development). La différence avec des outils comme Cucumber est que vous n'écrivez pas de code de liaison (glue code) pour les définitions d'étapes. Karate intègre les étapes HTTP, les assertions et la gestion JSON, de sorte qu'un test d'API fonctionnel ne nécessite aucune connaissance de Java.
Le projet propose plus que des tests d'API. Le dépôt inclut des modules pour les mocks, les tests de performance (via Gatling) et l'automatisation de l'interface utilisateur (UI). Pour ce guide, l'accent est mis sur le cœur des tests d'API, ce qui est généralement la première chose que la plupart des équipes recherchent.
Étant donné que les tests sont des fichiers texte brut, ils se versionnent bien. Un diff de pull request montre exactement quelle assertion a été modifiée. Cela s'intègre bien à la revue de code et à un workflow Git-natif, basé sur le code.
Si vous êtes nouveau dans le style Given/When/Then, notre introduction au Behavior-Driven Development explique d'où il vient et pourquoi les équipes l'utilisent.
Comment ça marche : Fichiers de fonctionnalités et karate-config.js
Un test Karate commence par un fichier de fonctionnalités. Chaque fichier contient un bloc Feature: et un ou plusieurs blocs Scenario:. À l'intérieur d'un scénario, vous configurez la requête avec Given, l'exécutez avec When, et faites des assertions avec Then.
Voici la structure présentée par le guide de démarrage rapide de Karate :
Feature: User API
Scenario: List all users
Given url 'https://jsonplaceholder.typicode.com'
And path 'users'
When method get
Then status 200
And match response == '#[10]'
Lisez-le de haut en bas. url définit l'adresse de base. path ajoute la ressource. method get envoie la requête. status 200 vérifie le code HTTP. La dernière ligne affirme que la réponse est un tableau JSON avec exactement 10 éléments. Le #[10] est un marqueur Karate, pas du JavaScript. Plus de détails sur ces marqueurs dans la section des assertions.
Le Gherkin ici est standard Given/When/Then. Si vous souhaitez une analyse plus approfondie de cette syntaxe, consultez notre guide Gherkin pour le BDD et les tests d'API.
La plupart des projets nécessitent des valeurs spécifiques à l'environnement : une URL de base de développement, un jeton de staging, un endpoint de production. Karate gère cela avec un seul fichier nommé karate-config.js. Il s'exécute une fois avant vos tests et renvoie un objet de configuration que chaque scénario peut lire.
function fn() {
var env = karate.env || 'dev';
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
if (env === 'qa') {
config.baseUrl = 'https://qa.example.com';
}
return config;
}
karate.env provient d'une propriété système que vous transmettez lors de l'exécution. Changez d'environnement sans toucher à un seul fichier de fonctionnalités. Dans un scénario, vous écririez alors Given url baseUrl au lieu de coder en dur l'adresse.
Un Exemple de Scénario
Écrivons quelque chose avec un corps de requête. Ce scénario crée un utilisateur, vérifie le statut et valide la structure de la réponse.
Feature: Create user
Background:
* url baseUrl
Scenario: Create a new user returns 201
Given path 'users'
And request { name: 'Ada', job: 'engineer' }
When method post
Then status 201
And match response.name == 'Ada'
And match response.id == '#string'
Quelques points à noter. Le bloc Background: s'exécute avant chaque scénario du fichier, vous définissez donc l'URL de base une seule fois. Le * est une étape générique ; Karate traite * de la même manière que Given, When ou Then, ce qui vous permet d'écrire des étapes de configuration sans vous soucier de la grammaire. Le mot-clé request prend directement une charge utile JSON. Pas de sérialiseur, pas de POJO. Et #string est un comparateur flou qui affirme que le champ id existe et est une chaîne de caractères, sans le lier à une valeur spécifique.
Assertions et Correspondance JSON
Les assertions sont ce qui fait la force de Karate. Le mot-clé principal est match. Il compare une valeur réelle à une valeur attendue et fait échouer le test en cas de non-correspondance.
La correspondance exacte vérifie l'égalité :
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Les jetons #number, #string, #boolean et #uuid sont des comparateurs flous. Ils affirment le type et la présence sans exiger une valeur littérale, ce qui maintient la stabilité des tests lorsque le serveur renvoie des identifiants ou des horodatages générés.
Lorsque vous ne vous souciez que d'un sous-ensemble de champs, utilisez contains :
And match response contains { name: 'Ada' }
Cela réussit tant que name est égal à Ada, même si la réponse contient dix autres champs. Karate prend également en charge !contains, contains only, contains any et contains deep pour un contrôle plus fin de la correspondance partielle.
Vous pouvez également valider des tableaux. match response == '#[10]' affirme un tableau de longueur 10. Vous pouvez appliquer un schéma à chaque élément avec each :
And match each response == { id: '#number', name: '#string' }
Cette seule ligne vérifie que chaque objet du tableau possède un id numérique et un name de type chaîne. Ce type de validation de forme nécessiterait une boucle et plusieurs assertions dans un framework de test à usage général. Si vous souhaitez avoir une vue d'ensemble sur la validation des réponses, notre guide pratique des assertions d'API couvre les modèles communs aux différents outils.
Tests basés sur les données et CI
Les véritables suites de tests exécutent la même logique avec de nombreuses entrées. Karate gère cela avec Scenario Outline et une table Examples. Les espaces réservés entre crochets angulaires sont remplis à partir de chaque ligne.
Scenario Outline: Create users from a table
Given url baseUrl
And path 'users'
And request { name: '<name>', job: '<job>' }
When method post
Then status 201
And match response.name == '<name>'
Examples:
| name | job |
| Ada | engineer |
| Grace | scientist |
| Alan | analyst |
Cela exécute le scénario trois fois, une fois par ligne. Vous pouvez également lire les lignes à partir d'un fichier externe au lieu d'une table intégrée, ce qui permet de ne pas surcharger vos fichiers de fonctionnalités avec de grands ensembles de données :
Examples:
| read('classpath:test-data/users.json') |
Karate lit les fichiers JSON et CSV de cette manière, de sorte que vos données de test peuvent résider là où votre équipe préfère les gérer.
Pour l'intégration continue, vous avez deux options. Dans un projet Maven ou Gradle, Karate s'exécute via JUnit 5. Vous ajoutez la dépendance karate-junit5 et pointez un exécuteur vers vos fichiers de fonctionnalités, de sorte que mvn test les exécute comme n'importe quel autre test unitaire. Cela signifie que votre étape CI existante ne nécessite aucun outil spécial.
La deuxième option est le fichier jar autonome, qui ne nécessite aucun outil de build. Téléchargez karate.jar depuis les versions du projet et exécutez directement les fichiers de fonctionnalités. Notez que le jar nécessite une version récente de Java, vérifiez donc les notes de version pour la configuration minimale requise.
java -jar karate.jar src/test/java/features
Vous pouvez filtrer par balise, exécuter en parallèle et choisir un répertoire de sortie :
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Transmettez un environnement avec une propriété système, qui est ensuite utilisée par karate.env dans karate-config.js :
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karate génère un rapport HTML dans le répertoire de sortie après chaque exécution, de sorte que les échecs sont faciles à inspecter dans un artefact de pipeline. Pour une vue d'ensemble de la CI, consultez comment automatiser les tests d'API en CI/CD.
Forces et Compromis
Karate présente des forces évidentes. Les tests se lisent presque comme de l'anglais simple, ce qui abaisse la barrière pour les personnes qui ne maîtrisent pas couramment Java. La correspondance JSON intégrée, y compris les comparateurs flous et each, élimine beaucoup de code répétitif d'assertions. Tout réside dans des fichiers texte sous Git, de sorte que les tests peuvent être révisés et comparés comme du code source. Et cela couvre plus que le HTTP, de sorte qu'une équipe peut ajouter des mocks ou des tests de performance plus tard sans changer d'outils.
Les compromis sont également réels. Karate s'exécute sur la JVM, vous avez donc besoin de Java installé et d'un certain confort avec l'écosystème JVM pour aller au-delà des bases. Le DSL est une chose à apprendre en soi ; la syntaxe se lit facilement mais écrire des comparateurs corrects et des modèles de réutilisation demande de la pratique. La logique réutilisable, les helpers personnalisés et les configurations complexes vous ramènent souvent vers des fonctions JavaScript ou l'interopérabilité Java. Et parce que les tests sont du code, les non-développeurs de l'équipe ne peuvent généralement pas les créer ou les modifier sans aide.
Rien de tout cela n'est une critique. C'est le profil d'un framework axé sur le code. La question est de savoir si ce profil correspond à la façon dont votre équipe souhaite travailler.
Karate vs une approche sans code (Apidog)
Karate est basé sur le code et natif de Git. Vous écrivez des fichiers de fonctionnalités, les commitez et les exécutez à partir d'un outil de build ou du jar. Cela convient aux ingénieurs qui souhaitent que les tests soient sous contrôle de version à côté de l'application et qui sont à l'aise avec la JVM.
Apidog adopte une approche visuelle et sans code pour atteindre le même objectif. Vous construisez des scénarios de test dans une interface utilisateur, enchaînez les requêtes et ajoutez des assertions en cliquant plutôt qu'en écrivant du DSL. Parce que l'ensemble du cycle de vie de l'API (conception, débogage, mocking, documentation) se trouve au même endroit, les tests peuvent réutiliser les endpoints et les schémas que vous avez déjà définis. Cela abaisse la barrière pour les ingénieurs QA et les responsables produits qui ne veulent pas gérer un projet Java.
Les suites visuelles ne sont pas bloquées dans l'interface utilisateur. Apidog les exécute sans interface graphique en CI via l'Apidog CLI, de sorte qu'une suite sans code s'intègre toujours dans un pipeline automatisé. Vous l'installez avec Node :
npm install -g apidog-cli
Puis déclenchez un scénario ou une suite enregistré par ID, en pointant vers un environnement et en choisissant les formats de rapport :
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
L'option -t cible un scénario, un dossier ou une suite ; -e sélectionne l'environnement ; -r choisit un ou plusieurs rapporteurs (cli, html, json, junit). Pour les exécutions basées sur les données, -d (ou --iteration-data) prend un chemin de fichier de données ou un ID de données de test. L'interface CLI est sans interface graphique et s'exécute sur n'importe quelle étape CI qui peut exécuter Node. Elle exécute vos scénarios Apidog enregistrés ; ce n'est pas un expéditeur de requêtes interactif ou un générateur de charge. Consultez une présentation complète dans Apidog CLI pour CI/CD, et une comparaison avec un autre exécuteur dans Apidog CLI vs Newman.
Les deux approches produisent des tests d'API automatisés qui s'exécutent sans interface graphique en CI. La différence réside dans le style de rédaction : Karate souhaite que vous écriviez du DSL dans Git ; Apidog souhaite que vous cliquiez dans une interface utilisateur qui exporte également vers le pipeline.
Comment Choisir
Choisissez Karate lorsque votre équipe est fortement composée de développeurs, à l'aise avec la JVM, et souhaite des tests versionnés comme du code juste à côté de l'application. Les fichiers de fonctionnalités en texte brut et la correspondance JSON intégrée sont avantageux lorsque les ingénieurs sont responsables de la suite de tests de bout en bout.
Choisissez un outil sans code comme Apidog lorsque les rédacteurs incluent des personnes de l'assurance qualité (QA) et du produit, lorsque vous souhaitez que les tests soient liés à un workflow de conception et de documentation existant, ou lorsque vous préférez ne pas maintenir un build Java pour exécuter des vérifications d'API. Vous bénéficiez toujours d'une couverture CI via l'interface CLI.
Certaines équipes utilisent les deux : Karate pour des suites de régression profondes, gérées par le code, et un outil visuel pour une couverture large et rapide que les non-développeurs peuvent étendre. Si vous hésitez encore, notre aperçu sur la façon de choisir un framework de test d'automatisation d'API présente les critères de décision.
FAQ
Ai-je besoin de connaître Java pour utiliser Karate ? Non, pas pour écrire des tests d'API de base. Les fichiers de fonctionnalités utilisent le DSL Gherkin, et Karate intègre les étapes HTTP et d'assertion. Vous aurez besoin de Java installé pour exécuter les tests, et une certaine connaissance de Java ou JavaScript aide lorsque vous avez besoin d'assistants personnalisés ou d'une réutilisation complexe.
En quoi Karate est-il différent de Cucumber ? Les deux utilisent la syntaxe Given/When/Then de Gherkin. Avec Cucumber, vous écrivez du code de définition d'étape pour chaque étape. Karate fournit les étapes de test d'API pour vous, il n'y a donc pas de code de liaison à maintenir pour les tests HTTP standard.
Karate peut-il fonctionner sans Maven ou Gradle ? Oui. Téléchargez le karate.jar autonome depuis les versions du projet et exécutez les fichiers de fonctionnalités avec java -jar karate.jar <path>. Il prend en charge les balises, les threads parallèles et un répertoire de sortie personnalisé sans aucun outil de build.
Que signifient les syntaxes #string ou #[10] ? Ce sont les comparateurs flous de Karate. #string affirme qu'un champ est une chaîne de caractères de n'importe quelle valeur, #number un nombre, et #[10] affirme qu'un tableau JSON a une longueur de 10. Ils vous permettent de valider la forme de la réponse sans coder en dur les valeurs générées.
Les tests d'API sans code peuvent-ils toujours s'exécuter en CI ? Oui. Un outil visuel comme Apidog exporte les scénarios enregistrés vers l'Apidog CLI, qui est sans interface graphique et s'exécute sur n'importe quelle étape CI avec Node. Vous créez donc des tests dans une interface utilisateur et bénéficiez toujours d'exécutions de pipeline automatisées.