Voer je tests uit vanuit CI/CD

Het CI/CD-scherm van Studio maakt het pipelinebestand voor GitHub Actions of GitLab CI. Deze handleiding beschrijft wat dat bestand uitvoert, de drie plaatsen waar de taak kan worden uitgevoerd, geheimen, de JUnit XML en het bewijsmateriaal dat de taak achterlaat, en de fouten die op een CI-machine kunnen optreden.

Het pipelinebestand

Kies op het CI/CD-scherm GitHub Actions of GitLab CI, de browsers, de controles en waar de taak wordt uitgevoerd, en genereer vervolgens het bestand. Studio valideert het bestand eerst lokaal en kan het vanuit hetzelfde scherm committen en pushen. Vanuit een terminal maakt nexus init --ci github of nexus init --ci gitlab hetzelfde bestand.

Bij meerdere browsers voert GitHub één taak per browser uit, met fail-fast: false, en voegt elke taak --project=<browser> toe. De controles die je kiest voegen --visual, --a11y, --chaos=, --loop= of --no-retry toe.

Exitcodes en JUnit XML

nexus ci voert de tests uit die je opgeeft (TC1,TC2) of --all, en sluit af met 0 als ze slagen, 1 bij een mislukking en 2 als er niets is uitgevoerd of de opdracht onjuist was. Het schrijft JUnit XML naar evidence/ci/junit.xml; --junit=<path> schrijft dit naar een andere locatie.

Waar de taak wordt uitgevoerd: drie opties

Elke optie vereist een machine met een activering: de engine voert geen testsuites uit op een machine zonder activering, en elke geactiveerde machine telt mee voor je abonnement (abonnementen en machines). Een runner in de cloud, runs-on: ubuntu-latest, start voor elke taak een nieuwe virtuele machine en behoudt dus nooit een activering; gebruik een eigen permanente runner.

Optie A: een zelfgehoste runner op de machine van Studio

1. Registreer een runner op de Windows 11-pc of mini-pc waarop Nexus Studio is geïnstalleerd en geactiveerd: op GitHub via Settings, Actions, Runners, New self-hosted runner in de repository; op GitLab via Settings, CI/CD, Runners.
2. Kies op het CI/CD-scherm Mijn machine. Het bestand bevat dan runs-on: [self-hosted] op GitHub of tags: [self-hosted] op GitLab.
3. Voer de runner uit als de Windows-gebruiker die de Studio heeft geactiveerd. De engine leest de activering uit het profiel van die gebruiker, in .sentinel-studio\license.json, dus een runnerservice onder een ander account vindt geen activering.

De taak gebruikt de activering van deze machine: één activering per machine, die al meetelt voor je abonnement, en geen sleutel in de pijplijn. Gebruik een zelfgehoste runner alleen met een privérepository, zoals de Studio waarschuwt: bij een openbare repository kan iedereen die een pull request opent code op je machine uitvoeren.

Optie B: een runner op een VPS, in een container

Een VPS met Ubuntu 24.04 LTS x86_64, Docker Engine en Compose v2, bereikbaar via SSH-sleutelauthenticatie. Deze telt als één machine binnen je abonnement.

1. Kies op het CI/CD-scherm Mijn machine + Docker. Naast het pijplijnbestand schrijft de Studio docker-compose.sentinel-runner.yml, Dockerfile.runner en de twee entrypoint-scripts van de runner naar de werkruimte. Dockerfile.runner gebruikt mcr.microsoft.com/playwright:v1.62.1-noble als basis.
2. Het scherm toont de opdrachten die je in een SSH-sessie op de VPS moet plakken, niet in de eigen terminal van de Studio. Voor GitHub wordt een registratietoken opgehaald dat 1 uur geldig is en worden REPO_URL, RUNNER_TOKEN en RUNNER_NAME ingesteld; voor GitLab zijn dat GITLAB_URL en GITLAB_RUNNER_TOKEN. Vervolgens:

docker compose -f docker-compose.sentinel-runner.yml up -d --build sentinel-runner
docker compose -f docker-compose.sentinel-runner.yml up -d sentinel-runner-gitlab

De eerste regel is voor GitHub, de tweede voor GitLab. Binnen een Linux-container identificeert de licentie de machine via /etc/machine-id: koppel dit bestand van de host als alleen-lezen, /etc/machine-id:/etc/machine-id:ro, en bewaar de map .sentinel-studio uit de thuismap van de runner op een volume, zodat de activering bij opnieuw bouwen behouden blijft. Activeer eenmalig, handmatig, met nexus license activate en je sleutel, nooit vanuit het pijplijnbestand.

Momenteel wordt de runner-image op de VPS gebouwd op basis van Dockerfile.runner. De repository heeft nog geen containerregister: een gepubliceerde image op GitHub Container Registry, die door de VPS-runtime van de Studio wordt uitgevoerd, komt met de volgende release beschikbaar.

Optie C: de CI-taak start een uitvoering op een host via SSH

De taak blijft klein, op elke runner, en de testsuites draaien op een host die je zelf beheert, met de werkruimte en de engine op een pad op die host, zoals de SSH-runtime van de Studio verwacht. Het CI/CD-scherm genereert deze taak niet; dit zijn de opties die de eigen SSH-runtime van de Studio gebruikt:

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

• Alleen sleutelverificatie. BatchMode=yes vraagt nooit om een wachtwoord. Schrijf de privésleutel uit een CI-geheim naar een bestand dat alleen door de taak kan worden gelezen, en verwijder het wanneer de taak eindigt.
• StrictHostKeyChecking=yes. De sleutel van de host moet al in known_hosts van de runner staan: bewaar de regel met de openbare sleutel van de host in een CI-variabele en schrijf die daarheen vóór de eerste ssh. Stel dit nooit in op no.
• De afsluitcode wordt teruggegeven. ssh sluit af met de code van de externe opdracht, zodat de stap mislukt als de testsuite mislukt, en scp haalt het bewijsmateriaal, inclusief JUnit XML, terug voor de artefactstap.
• De host controleert zijn eigen licentie en telt als één machine binnen je abonnement.

Geheimen

• Sla tokens, webhook-URL's en SSH-privésleutels op als CI-geheimen: op GitHub onder Instellingen, Geheimen en variabelen, Actions, of met gh secret set <KEY>; op GitLab als gemaskeerde variabelen onder Instellingen, CI/CD, Variabelen. Nooit in de repository, het pipelinebestand of een logboek.
• De gegenereerde GitHub-workflow leest alleen de integratiesleutels, uit secrets.<KEY>, en alleen bij de Nexus-stappen: TELEGRAM_*, SLACK_ENABLED, SLACK_WEBHOOK_URL, JIRA_* en de meldingsschakelaars. Het CI/CD-scherm toont voor elke sleutel een gh secret set-opdracht; gh vraagt om de waarde en er wordt niets weergegeven.
• De licentiesleutel hoort niet thuis in CI. Activeer een permanente runner één keer handmatig: de sleutel wordt één keer verzonden en niet bewaard. Als je proces toch vereist dat de sleutel in het CI-systeem staat, sla deze dan uitsluitend op als gemaskeerd geheim; niets in de gegenereerde pipeline leest deze uit.
• Geef nooit een geheim weer in een stap. De engine verwijdert geheimen uit de tekst die hij als bewijsmateriaal opslaat, zoals JUnit-foutmeldingen en logboeken; hij verwijdert ze niet uit de console-uitvoer van de taak zelf, en de CI-dienst maskeert alleen waarden die als geheim zijn opgeslagen.

JUnit XML en bewijsmateriaal als artefacten

• GitHub uploadt evidence/ als nexus-evidence, bij een matrix één nexus-evidence-<browser> per browser, ongeacht of de uitvoering is geslaagd of mislukt. De JUnit XML staat daarin, op evidence/ci/junit.xml.
• GitLab bewaart evidence/ en rapporteert evidence/ci/junit.xml als een JUnit-rapport, zodat mislukte tests in het samenvoegverzoek verschijnen.
• Vanuit de Studio kan het CI/CD-scherm een GitHub-workflow starten en het bijbehorende bewijsmateriaal downloaden naar evidence/ci-remote/run-<id> in de werkruimte.
• Waar de kopie staat. Een artefact is een kopie van het bewijsmateriaal, inclusief schermafbeeldingen en logboeken, in de opslag van je CI-dienst; bij een gehoste dienst is dat de hardware van iemand anders. Stel de bewaartermijn voor artefacten in volgens je beleid, of bewaar het bewijsmateriaal op je runner en upload alleen evidence/ci/junit.xml.

Problemen oplossen

SEAT_LIMIT op een runner in de cloud of een tijdelijke runner

Elke nieuwe virtuele machine geldt voor de licentie als een nieuwe machine, dus een tijdelijke runner zou voor elke taak een activering nodig hebben. Zodra alle machines van je abonnement actief zijn, wordt activering geweigerd met SEAT_LIMIT: “Alle machines van je abonnement zijn in gebruik. Deactiveer er één in je account.” Gebruik een permanente runner die je zelf host (optie A of B), en deactiveer machines die je niet meer gebruikt onder Licentie & machines in je account (meer over SEAT_LIMIT).

De runner was dagenlang offline

De licentie van een machine moet minstens elke 7 dagen worden gevalideerd. Daarna krijgt de machine nog 4 dagen met een melding, waarna deze overschakelt naar alleen-lezen: testsuites worden pas weer uitgevoerd na een geslaagde controle en het bewijsmateriaal blijft leesbaar. Zodra een runner weer online is, voert nexus license renew de controle opnieuw uit (offline werken).

“geen /etc/machine-id” in een container

De container heeft geen machine-ID die de licentie kan uitlezen. Koppel die van de host: -v /etc/machine-id:/etc/machine-id:ro, of voeg dezelfde regel toe onder volumes: in het compose-bestand.

De taak eindigt met code 2

Er is niets uitgevoerd: geen enkele test kwam overeen met de ID's, of de opdracht was onjuist. Controleer de ID's die aan nexus ci zijn doorgegeven, in tc_ids op GitHub of TC_IDS op GitLab.

Verificatie van hostsleutel mislukt

StrictHostKeyChecking=yes heeft een host geweigerd die niet in known_hosts staat of waarvan de sleutel is gewijzigd. Voeg de hostsleutel toe vanuit een betrouwbare bron, nadat je de vingerafdruk op de host zelf hebt gecontroleerd. Schakel de controle niet uit.