Guide d'installation Jenkins CI pour ReadyAPI et une alternative plus simple

En bref

L'exécution de tests ReadyAPI dans Jenkins est possible via l'outil en ligne de commande `testrunner` et le plugin SmartBear Jenkins, mais cela nécessite l'installation de ReadyAPI sur les agents de build et implique de fréquents problèmes de configuration. L'intégration CI/CD d'Apidog fonctionne via une interface CLI simple installée avec npm, sans aucune exigence de logiciel d'agent et sans licence par exécution.

💡

Apidog est une plateforme de développement d'API tout-en-un gratuite avec un exécuteur CLI léger qui s'intègre à Jenkins, GitHub Actions et d'autres pipelines sans licence supplémentaire. Essayez Apidog gratuitement, aucune carte de crédit requise.

bouton

Introduction

L'intégration de tests API dans un pipeline CI/CD est l'une des choses les plus précieuses qu'une équipe de test puisse faire. Détecter les régressions sur chaque pull request, avant que le code n'atteigne le staging ou la production, vaut l'effort de configuration.

ReadyAPI prend en charge l'intégration Jenkins via deux mécanismes : l'outil en ligne de commande `testrunner` et le plugin officiel SmartBear Jenkins. Les deux fonctionnent, mais chacun vient avec sa complexité. Ce guide explique comment configurer ReadyAPI avec Jenkins, les problèmes courants que vous rencontrerez, et comment Apidog offre la même intégration de pipeline avec moins de surcharge d'infrastructure.

Configuration de ReadyAPI dans Jenkins : l'approche `testrunner`

Le `testrunner` est le moteur d'exécution en ligne de commande de ReadyAPI. Lorsque Jenkins doit exécuter des tests ReadyAPI sans interface graphique, il appelle `testrunner` avec des arguments pointant vers un fichier de projet.

Prérequis :

ReadyAPI doit être installé sur chaque agent Jenkins qui exécute des tests API. C'est la plus grande exigence opérationnelle. Si vous avez cinq agents de build et que des tests ReadyAPI s'exécutent sur l'un d'entre eux, les cinq doivent avoir ReadyAPI installé. Cela crée :

Une charge de maintenance d'installation lorsque ReadyAPI est mis à jour.
Une question de licence : chaque installation d'agent nécessite-t-elle sa propre licence ? La politique de licence CI/CD de SmartBear varie selon le contrat. Confirmez avec votre équipe de compte.
Une taille d'image d'agent et un temps de démarrage accrus pour les agents basés sur le cloud.

Commande `testrunner` de base :

Sous Linux/macOS :

/path/to/ReadyAPI/testrunner.sh \
  -r \
  -f /path/to/results \
  -s "TestSuiteName" \
  -c "TestCaseName" \
  /path/to/project.xml

Sous Windows :

C:\ReadyAPI\testrunner.bat ^
  -r ^
  -f C:\results ^
  -s "TestSuiteName" ^
  -c "TestCaseName" ^
  C:\projects\project.xml

Indicateurs clés du `testrunner` :

-r : génère un rapport XML compatible JUnit
-f <directory> : répertoire de sortie pour les résultats
-s <name> : exécute une suite de tests spécifique (omettre pour exécuter toutes)
-c <name> : exécute un cas de test spécifique (omettre pour exécuter tous)
-e <environment> : spécifie l'environnement à utiliser
-P <name>=<value> : écrase les propriétés du projet

Étape de pipeline Jenkins :

Dans un Jenkinsfile :

stage('API Tests') {
  steps {
    sh '''
      /opt/readyapi/testrunner.sh \
        -r \
        -f ${WORKSPACE}/test-results \
        -e ${ENVIRONMENT} \
        ${WORKSPACE}/project.xml
    '''
    junit 'test-results/*.xml'
  }
}

L'étape `junit` publie les résultats dans Jenkins afin que les échecs apparaissent dans le rapport de build.

Utilisation du plugin SmartBear Jenkins

SmartBear maintient un plugin Jenkins pour ReadyAPI disponible dans le répertoire des plugins Jenkins. Le plugin fournit une étape de build dans l'interface utilisateur de Jenkins plutôt que de vous obliger à écrire des commandes shell manuellement.

Pour l'installer :

Allez dans Jenkins > Gérer Jenkins > Gestionnaire de plugins.
Recherchez « SmartBear ReadyAPI Functional Testing ».
Installez et redémarrez Jenkins.

Après l'installation, vous configurez le chemin d'installation de ReadyAPI dans les paramètres globaux de Jenkins, puis ajoutez une étape de test ReadyAPI à votre tâche de build en la sélectionnant dans le menu déroulant des étapes de build.

Le plugin gère la construction des arguments pour vous et intègre les résultats dans les rapports de test de Jenkins. Pour les équipes qui préfèrent la configuration via une interface graphique plutôt que des scripts de pipeline Groovy, le plugin réduit le temps de configuration.

Limitations du plugin : Le plugin est lié à des versions spécifiques de Jenkins et de ReadyAPI. Les mises à jour du plugin sont en retard par rapport aux versions de ReadyAPI et aux versions de Jenkins. Les équipes utilisant la dernière version de ReadyAPI peuvent rencontrer des problèmes de compatibilité qui nécessitent d'attendre une mise à jour du plugin.

Problèmes courants Jenkins + ReadyAPI

Le `testrunner` se bloque au démarrage. ReadyAPI est une application Java/Swing. Lorsqu'elle est lancée sans interface graphique en CI, elle tente parfois d'initialiser des composants graphiques. Définissez la variable d'environnement `DISPLAY` ou utilisez les arguments JVM `-Djava.awt.headless=true` si vous rencontrez ce problème.

Échecs de validation de licence. ReadyAPI valide sa licence au démarrage. Si l'agent CI ne peut pas atteindre le serveur de licences de SmartBear (fréquent dans les réseaux d'entreprise verrouillés), les tests échouent avec une erreur de licence plutôt qu'une défaillance de test. Vous devez configurer les paramètres du serveur de licences flottantes ou la licence hors ligne.

Erreurs de mémoire insuffisante. Les paramètres par défaut du tas JVM dans `testrunner` sont conservateurs. Les grandes suites de tests ou les projets avec de nombreux fichiers de données peuvent nécessiter un ajustement des paramètres `-Xmx`. Modifiez le fichier `testrunner.sh` ou `testrunner.bat` pour augmenter le tas :

-Xms128m -Xmx1024m

Problèmes de chemins avec les fichiers de projet. Les projets ReadyAPI référencent des fichiers externes (sources de données, schémas, scripts) en utilisant des chemins. Lors de l'exécution en CI, les chemins relatifs ne fonctionnent que si le répertoire de travail est correctement défini. Les chemins absolus dans les fichiers de projet causent des problèmes lorsque le projet est déplacé entre machines. Utilisez les propriétés du projet pour les chemins et définissez-les via les indicateurs `-P` lors de l'exécution.

Les tests passent localement mais échouent en CI. Souvent causé par des différences d'environnement : différentes données dans les fichiers externes, différentes valeurs de variables d'environnement ou chemins codés en dur. Utilisez la fonction d'environnement de ReadyAPI avec une sélection d'environnement explicite dans l'argument `-e` du `testrunner`.

Intégration Apidog Jenkins : une approche plus simple

L'exécuteur CLI d'Apidog s'installe via npm et ne nécessite pas d'application de bureau sur l'agent de build.

Installation sur l'agent Jenkins :

npm install -g apidog-cli

Ou dans une étape de pipeline :

npm ci
# apidog-cli is in devDependencies

Exécution de tests dans un Jenkinsfile :

stage('API Tests') {
  steps {
    sh '''
      apidog run \
        --collection ${WORKSPACE}/apidog-collection.json \
        --environment staging \
        --reporter junit \
        --reporter-junit-export ${WORKSPACE}/results/report.xml
    '''
    junit 'results/report.xml'
  }
}

Différences clés par rapport à ReadyAPI :

Aucune application de bureau sur les agents. L'interface CLI d'Apidog est un package Node.js léger. Installez-le en quelques secondes, pas en quelques minutes. Pas de problèmes d'initialisation de l'interface graphique, pas d'exigences de connectivité au serveur de licences.

Aucune préoccupation de licence par exécution. Apidog ne facture pas par exécution CI. Exécutez autant de cycles de test par jour que votre pipeline l'exige.

Configuration de l'environnement via des variables d'environnement ou des indicateurs. Transmettez les informations d'identification et les URL de base sous forme de variables d'environnement directement à partir du magasin de justificatifs Jenkins :

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
  sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}

Comparaison avec GitHub Actions :

Pour les équipes utilisant également GitHub Actions, l'approche Apidog est tout aussi propre :

- name: Exécuter les tests API
  run: |
    npm install -g apidog-cli
    apidog run collection.json --environment staging
  env:
    API_BASE_URL: ${{ vars.STAGING_URL }}
    API_KEY: ${{ secrets.API_KEY }}

L'équivalent ReadyAPI nécessite soit un runner auto-hébergé avec ReadyAPI installé, soit une construction d'image Docker complexe. Aucun des deux n'est aussi simple.

Migration de la CI/CD de ReadyAPI vers Apidog

Si vous migrez votre suite de tests et devez mettre à jour votre configuration CI/CD simultanément :

Exportez vos définitions d'API depuis ReadyAPI et importez-les dans Apidog.
Installez l'interface CLI d'Apidog sur vos agents Jenkins.
Ajoutez une étape de test Apidog à votre pipeline parallèlement à l'étape ReadyAPI existante.
Exécutez les deux en parallèle. Comparez les taux d'échec et la couverture des tests.
Supprimez l'étape ReadyAPI une fois que vous avez confiance en la couverture d'Apidog.
Supprimez ReadyAPI des agents de build lors du prochain rafraîchissement de l'image de l'agent.

FAQ

Le `testrunner` de ReadyAPI nécessite-t-il une licence CI distincte ?La politique de licence de SmartBear pour l'utilisation CI/CD varie selon le contrat. Certains accords incluent les droits d'exécution CI/CD dans la licence standard ; d'autres nécessitent un accord distinct. Vérifiez votre contrat ou contactez votre responsable de compte SmartBear avant de supposer que les exécutions CI sont couvertes.

Les tests ReadyAPI peuvent-ils s'exécuter dans des conteneurs Docker ?Oui, avec des efforts. Vous pouvez créer une image Docker avec ReadyAPI installé et l'utiliser comme conteneur d'agent Jenkins. L'image est grande (ReadyAPI est une application de bureau) et nécessite une configuration sans interface graphique. Cela fonctionne mais ajoute de la complexité par rapport aux outils conçus pour les environnements CI conteneurisés.

Apidog prend-il en charge l'exécution parallèle des tests dans Jenkins ?Oui. Vous pouvez exécuter plusieurs instances de l'interface CLI Apidog en parallèle dans des étapes Jenkins, chacune exécutant une collection ou un environnement différent. L'exécution parallèle est contrôlée via votre Jenkinsfile, et non par l'interface CLI Apidog.

Quel format de rapport de test Apidog produit-il pour Jenkins ?L'interface CLI d'Apidog peut produire des rapports JUnit XML, que Jenkins analyse et affiche nativement dans la section des résultats de test. Le format est le même que celui produit par le `testrunner` de ReadyAPI.

Les scripts de test Apidog s'exécutent-ils dans le même processus que l'exécuteur CLI ?Oui. Les scripts de test JavaScript s'exécutent au sein du processus Node.js de l'interface CLI Apidog. Il n'y a pas d'environnement d'exécution de script séparé à configurer.

Existe-t-il un plugin officiel Apidog Jenkins ?L'interface CLI Apidog s'exécute comme une étape shell dans Jenkins, ce qui ne nécessite pas de plugin dédié. Cette approche est plus simple à maintenir que les intégrations basées sur des plugins qui nécessitent des mises à jour lorsque Jenkins ou Apidog publient de nouvelles versions.

L'intégration de ReadyAPI dans Jenkins fonctionne, mais elle nécessite une gestion d'infrastructure importante. Pour les équipes qui souhaitent simplifier leur configuration CI/CD tout en maintenant une couverture complète des tests API, l'approche CLI d'Apidog élimine les points douloureux les plus courants : les exigences logicielles des agents, les dépendances des serveurs de licences et la configuration complexe de l'environnement.