Exécutez vos tests depuis CI/CD
L'écran CI/CD du Studio génère le fichier de pipeline pour GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI ou Bitbucket. Ce guide présente ce que ce fichier exécute, le contrôle de verdict unique, le déploiement facultatif après une exécution réussie, les trois emplacements où la tâche peut s'exécuter, les secrets, le fichier XML JUnit et les preuves conservées, ainsi que les erreurs rencontrées par une machine de CI.
Dernière mise à jour :
Par l’équipe Nexus StudioQA, Verdict System LLC.
Le fichier de pipeline
Sur l'écran CI/CD, choisissez le fournisseur, les navigateurs, les contrôles et l'emplacement d'exécution de la tâche, puis lancez la génération. Le Studio valide d'abord le fichier localement et peut créer un commit et le pousser depuis ce même écran. Depuis un terminal, nexus init --ci github ou nexus init --ci gitlab génère le même fichier.
| Partie | GitHub Actions | GitLab CI |
|---|---|---|
| Fichier | .github/workflows/nexus-ci.yml | .gitlab-ci.yml |
| Déclencheurs | Les pull requests, les pushs vers main ou master, et une exécution manuelle (workflow_dispatch) avec une entrée tc_ids. Avec la régression nocturne activée, un cron schedule en UTC, par défaut 0 6 * * *. | Les règles de pipeline de votre projet. Le fichier ne contient pas de planification : pour une exécution nocturne, ajoutez un Pipeline Schedule dans GitLab. |
| Runner | runs-on: ubuntu-latest pour un agent d'exécution hébergé dans le cloud, dans l'image mcr.microsoft.com/playwright:v1.62.1-noble; runs-on: [self-hosted] pour votre propre agent | L'image mcr.microsoft.com/playwright:v1.62.1-noble ; tags: [self-hosted] pour votre propre runner |
| Étapes | actions/checkout@v4; actions/setup-node@v4 avec Node.js 22, uniquement sur votre propre machine sans Docker (l'image contient déjà Node.js et les bibliothèques système); npm ci; npx playwright install, avec --with-deps sur cette même machine; node bin/nexus.js ci --all, ou les identifiants des tests choisis | npm ci ; node bin/nexus.js ci avec la variable TC_IDS, ou --all. L'image contient déjà les navigateurs. |
| Artefacts | actions/upload-artifact@v4, if: always(), nom nexus-evidence, chemin evidence/ | artifacts: when: always, reports: junit: evidence/ci/junit.xml, paths: evidence/ |
Avec plusieurs navigateurs, GitHub exécute un job par navigateur, avec fail-fast: false, et chacun ajoute --project=<browser>. Les vérifications que vous sélectionnez ajoutent --visual, --a11y, --chaos=, --loop= ou --no-retry.
Jenkins, Azure DevOps, CircleCI et Bitbucket
Les quatre autres fournisseurs utilisent la même commande, node bin/nexus.js ci --all, avec une exécution par navigateur, la publication JUnit propre à chaque fournisseur et le dossier evidence/ conservé comme artefact même en cas d'échec. Jenkins, CircleCI et Bitbucket s'exécutent dans l'image mcr.microsoft.com/playwright:v1.62.1-noble; Azure DevOps s'exécute sur un agent ubuntu-latest et installe d'abord les navigateurs.
| Fournisseur | Fichier | Les tests en échec s'affichent dans |
|---|---|---|
| Jenkins | Jenkinsfile | La page Test Result de la compilation |
| Azure DevOps | azure-pipelines.yml | L'onglet Tests de l'exécution, et Test Plans, Runs |
| CircleCI | .circleci/config.yml | L'onglet Tests de la tâche |
| Bitbucket | bitbucket-pipelines.yml | L'onglet Tests du pipeline |
Ces quatre fournisseurs lisent les secrets dans leur propre magasin. Le Studio répertorie les clés à y ajouter, sans leurs valeurs, et n'y écrit rien. Le contrôle de verdict et la tâche de déploiement ci-dessous concernent GitHub Actions et GitLab CI.
Codes de sortie et JUnit XML
nexus ci exécute les tests que vous nommez (TC1,TC2) ou --all, et se termine avec le code 0 en cas de succès, 1 en cas d'échec et 2 lorsqu'aucun test n'a été exécuté ou si la commande est incorrecte. Il écrit le XML JUnit dans evidence/ci/junit.xml ; --junit=<path> permet de l'écrire ailleurs.
Un contrôle de verdict unique pour toute la matrice
Avec plusieurs navigateurs, GitHub affiche un contrôle par navigateur. Le workflow généré ajoute une tâche nommée Nexus verdict, qui s'exécute après toutes les autres, même si l'une d'elles a échoué, et ne passe au vert que si tous les navigateurs ont réussi. Rendez ce seul contrôle obligatoire dans votre règle de protection de branche, plutôt qu'un contrôle par navigateur.
Déployer après validation
Cochez déployer après validation sur l'écran CI/CD pour ajouter une tâche de déploiement. Elle ne s'exécute que lors d'une poussée vers la branche principale et uniquement si la suite de tests a réussi : en cas d'échec, elle est ignorée. Sur GitHub, elle attend le contrôle de verdict et s'exécute dans l'environnement production, les règles de protection de l'environnement s'appliquent donc.
| Cible | Fonctionnalités | Secrets lus |
|---|---|---|
| Hook de déploiement (GitHub, GitLab) | Envoie une requête POST à une URL de déploiement fournie par votre hébergeur | NEXUS_DEPLOY_HOOK |
| Cloudflare (GitHub) | wrangler deploy | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
| Vercel (GitHub) | vercel pull, build et deploy --prebuilt --prod | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
| SSH et Docker Compose (GitHub) | docker compose pull et up -d dans un dossier de votre serveur | DEPLOY_SSH_HOST, DEPLOY_SSH_USER, DEPLOY_SSH_KEY, DEPLOY_SSH_KNOWN_HOSTS, DEPLOY_SSH_DIR |
- Secrets référencés uniquement par leur nom. Chaque secret est transmis à l'étape sous forme de variable d'environnement, jamais dans le texte du script, et la tâche vérifie d'abord chacun d'eux : tout secret manquant provoque un échec qui indique son nom.
- SSH vérifie la clé du serveur. La clé d'hôte provient de
DEPLOY_SSH_KNOWN_HOSTS; la vérification de la clé d'hôte n'est jamais désactivée. - Autorisations minimales. Les tâches de hook de déploiement et SSH n'ont aucune autorisation sur le dépôt; Cloudflare et Vercel disposent d'un accès en lecture pour récupérer le code.
Emplacement d'exécution du job : trois options
Chaque option nécessite une machine disposant d'une activation : le moteur n'exécute pas de suites sur une machine qui n'en possède pas, et chaque machine activée est comptabilisée dans votre abonnement (abonnements et machines). Un runner hébergé dans le cloud, runs-on: ubuntu-latest, démarre une nouvelle machine virtuelle pour chaque job et n'en conserve donc jamais aucune ; utilisez un runner persistant qui vous appartient.
Option A : un runner auto-hébergé sur la machine du Studio
- Sur le PC Windows 11 ou le mini PC où Nexus StudioQA est installé et activé, enregistrez un runner : sur GitHub, dans les Paramètres du dépôt, sous Actions, Runners, Nouveau runner auto-hébergé ; sur GitLab, dans Paramètres, CI/CD, Runners.
- Sur l'écran CI/CD, choisissez Ma machine. Le fichier contient alors
runs-on: [self-hosted]sur GitHub outags: [self-hosted]sur GitLab. - Exécutez le runner en tant qu'utilisateur Windows ayant activé le Studio. Le moteur lit l'activation depuis le profil de cet utilisateur, dans
.nexus-studioqa\license.json; un service de runner fonctionnant sous un autre compte n'en trouvera aucune.
Le job utilise l'activation de cette machine : une activation par machine, déjà comptabilisée dans votre abonnement, et aucune clé dans le pipeline. N'utilisez un runner auto-hébergé qu'avec un dépôt privé, comme le Studio vous en avertit : sur un dépôt public, toute personne ouvrant une pull request peut exécuter du code sur votre machine.
Option B : un runner sur un VPS, dans un conteneur
Un VPS sous Ubuntu 24.04 LTS x86_64, avec Docker Engine et Compose v2, accessible par authentification par clé SSH. Il est comptabilisé comme une machine de votre abonnement.
- Sur l'écran CI/CD, choisissez My machine + Docker. En plus du fichier de pipeline, le Studio écrit
docker-compose.nexus-studioqa-runner.yml,Dockerfile.runneret les deux scripts d'entrée du runner dans l'espace de travail.Dockerfile.runnerpart demcr.microsoft.com/playwright:v1.62.1-noble. - L'écran affiche les commandes à coller dans une session SSH sur le VPS, et non dans le terminal du Studio. Pour GitHub, il récupère un jeton d'enregistrement, valable 1 heure, et définit
REPO_URL,RUNNER_TOKENetRUNNER_NAME; pour GitLab,GITLAB_URLetGITLAB_RUNNER_TOKEN. Ensuite :
docker compose -f docker-compose.nexus-studioqa-runner.yml up -d --build nexus-studioqa-runner
docker compose -f docker-compose.nexus-studioqa-runner.yml up -d nexus-studioqa-runner-gitlab
La première ligne est pour GitHub, la seconde pour GitLab. Dans un conteneur Linux, la licence identifie la machine par /etc/machine-id : montez celui de l'hôte en lecture seule, /etc/machine-id:/etc/machine-id:ro, et conservez le dossier .nexus-studioqa du répertoire personnel du runner sur un volume, afin que l'activation survive à une reconstruction. Activez une seule fois, manuellement, avec nexus license activate et votre clé, jamais depuis le fichier de pipeline.
Aujourd'hui, l'image du runner est construite sur le VPS à partir de Dockerfile.runner. Le dépôt ne dispose pas encore de registre de conteneurs : une image publiée sur GitHub Container Registry, celle qu'utilise le runtime VPS du Studio, sera livrée avec la prochaine version.
Option C : le job CI démarre une exécution sur un hôte via SSH
Le job reste léger, sur n'importe quel runner, et les suites s'exécutent sur un hôte qui vous appartient, avec l'espace de travail et le moteur à un chemin défini, tel que le runtime SSH du Studio l'attend. L'écran CI/CD ne génère pas ce job ; voici les options qu'utilise le runtime SSH du Studio :
ssh -o BatchMode=yes -o StrictHostKeyChecking=yes -o ConnectTimeout=8 <user>@<host> "cd <path> && node bin/nexus.js ci --all"
scp -r -o BatchMode=yes -o StrictHostKeyChecking=yes <user>@<host>:<path>/evidence ./evidence
- Authentification par clé uniquement.
BatchMode=yesne demande jamais de mot de passe. Écrivez la clé privée depuis un secret CI dans un fichier accessible uniquement par le job, et supprimez-la à la fin du job. StrictHostKeyChecking=yes. La clé de l'hôte doit déjà être présente dans le fichierknown_hostsdu runner : conservez la ligne de clé publique de l'hôte dans une variable CI et écrivez-la avant le premier appel àssh. Ne la définissez jamais àno.- Le code de sortie est retourné.
sshse termine avec le code de la commande distante, de sorte que l'étape échoue lorsque la suite échoue, etscprapatrie les éléments de preuve, y compris le XML JUnit, pour l'étape d'artefact. - L'hôte vérifie sa propre licence et compte comme une seule machine de votre abonnement.
Secrets
- Stockez les jetons, les URL de webhook et les clés privées SSH en tant que secrets CI : sur GitHub dans Settings, Secrets and variables, Actions, ou avec
gh secret set <KEY>; sur GitLab en tant que variables masquées dans Settings, CI/CD, Variables. Jamais dans le dépôt, le fichier de pipeline ou un journal. - Le workflow GitHub généré lit uniquement les clés d’intégration et le jeton CI, depuis
secrets.<KEY>, et seulement lors des étapes Nexus : les clés de Telegram, Slack, Teams, Jira, Azure Boards et GitHub Issues, les paramètres d’activation des notifications etNEXUS_CI_LICENSE. L’écran CI/CD les définit pour vous : via l’API GitHub si vous avez enregistré unGITHUB_CI_TOKENdans les paramètres, ou avecgh secret setdans le cas contraire. Rien n’est affiché. - La clé de licence n’a pas sa place dans la CI. Un exécuteur hébergé utilise le jeton CI distinct,
NEXUS_CI_LICENSE, disponible sur le portail de votre compte : stockez-le uniquement en tant que secret masqué. Un exécuteur persistant peut, à la place, être activé une seule fois, manuellement : la clé est envoyée une fois et n’est pas conservée. - N'affichez jamais un secret dans une étape. Le moteur expurge les secrets du texte qu'il consigne comme preuve, tel que les messages d'échec JUnit et les journaux ; il n'expurge pas la sortie console propre au job, et le service CI masque uniquement les valeurs stockées en tant que secrets.
JUnit XML et preuves en tant qu'artefacts
- GitHub téléverse
evidence/en tant quenexus-evidence, unnexus-evidence-<browser>par navigateur avec une matrice, que l'exécution ait réussi ou échoué. Le JUnit XML se trouve à l'intérieur, àevidence/ci/junit.xml. - GitLab conserve
evidence/et signaleevidence/ci/junit.xmlen tant que rapport JUnit, de sorte que les tests échoués apparaissent dans la merge request. - Depuis Studio, l'écran CI/CD peut démarrer une exécution de workflow GitHub et télécharger ses preuves dans
evidence/ci-remote/run-<id>dans l'espace de travail. - Où réside la copie. Un artefact est une copie des preuves, captures d'écran et journaux inclus, sur le stockage de votre service CI ; sur un service hébergé, il s'agit du matériel d'un tiers. Définissez la rétention des artefacts selon ce que votre politique autorise, ou conservez les preuves sur votre runner et téléversez uniquement
evidence/ci/junit.xml.
Dépannage
SEAT_LIMIT sur un runner hébergé dans le cloud ou éphémère
Chaque nouvelle machine virtuelle est une nouvelle machine pour la licence, de sorte qu'un runner éphémère nécessiterait une activation à chaque tâche. Une fois que toutes les machines de votre abonnement sont actives, l'activation est refusée avec SEAT_LIMIT : « Toutes les machines de votre abonnement sont utilisées. Désactivez-en une dans votre compte. » Utilisez un runner auto-hébergé persistant (option A ou B), et désactivez les machines que vous n'utilisez plus sous License & machines dans votre compte (plus d'informations sur SEAT_LIMIT).
Le runner était hors ligne depuis plusieurs jours
La licence d'une machine doit être validée au moins tous les 7 jours. Passé ce délai, elle bénéficie de 4 jours supplémentaires avec un avertissement, puis passe en lecture seule : les suites ne s'exécutent plus jusqu'à ce qu'une vérification réussisse, et les preuves restent lisibles. Sur un runner de nouveau en ligne, nexus license renew effectue une nouvelle vérification (utilisation hors ligne).
« no /etc/machine-id » dans un conteneur
Le conteneur ne dispose d'aucun identifiant de machine que la licence puisse lire. Montez celui de l'hôte : -v /etc/machine-id:/etc/machine-id:ro, ou la même ligne sous volumes: dans le fichier compose.
La tâche se termine avec le code 2
Rien ne s'est exécuté : aucun test ne correspond aux identifiants, ou la commande était incorrecte. Vérifiez les identifiants transmis à nexus ci, dans tc_ids sur GitHub ou TC_IDS sur GitLab.
Échec de la vérification de la clé hôte
StrictHostKeyChecking=yes a refusé un hôte absent de known_hosts ou dont la clé a changé. Ajoutez la clé de l'hôte depuis une source de confiance, après avoir vérifié son empreinte directement sur l'hôte. Ne désactivez pas cette vérification.