Uruchamiaj testy z CI/CD
Ekran CI/CD w Studio tworzy plik potoku dla GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI lub Bitbucket. Ten przewodnik opisuje, co uruchamia ten plik, pojedynczą kontrolę wyniku końcowego, opcjonalne wdrożenie po pomyślnym przebiegu, trzy miejsca uruchamiania zadania, sekrety, pozostawiane pliki JUnit XML i materiały dowodowe oraz błędy napotykane na maszynie CI.
Ostatnia aktualizacja:
Autorzy to zespół Nexus StudioQA, Verdict System LLC.
Plik potoku
Na ekranie CI/CD wybierz dostawcę, przeglądarki, kontrole i miejsce uruchamiania zadania, a następnie wygeneruj plik. Studio najpierw sprawdza plik lokalnie i umożliwia utworzenie zatwierdzenia oraz wypchnięcie go z tego samego ekranu. W terminalu polecenie nexus init --ci github lub nexus init --ci gitlab tworzy ten sam plik.
| Część | GitHub Actions | GitLab CI |
|---|---|---|
| Plik | .github/workflows/nexus-ci.yml | .gitlab-ci.yml |
| Wyzwalacze | Żądania scalenia, wysłanie zmian do main lub master oraz uruchomienie ręczne (workflow_dispatch) z parametrem wejściowym tc_ids. Przy włączonych nocnych testach regresji, wpis cron schedule w UTC, domyślnie 0 6 * * *. | Reguły potoku Twojego projektu. Plik nie zawiera harmonogramu: aby uruchamiać zadanie co noc, dodaj harmonogram potoku w GitLab. |
| Runner | runs-on: ubuntu-latest dla wykonawcy w chmurze, w obrazie mcr.microsoft.com/playwright:v1.62.1-noble; runs-on: [self-hosted] dla własnego wykonawcy | Obraz mcr.microsoft.com/playwright:v1.62.1-noble; tags: [self-hosted] dla własnego runnera |
| Kroki | actions/checkout@v4; actions/setup-node@v4 z Node.js 22, tylko na własnej maszynie bez Dockera (obraz zawiera już Node.js i biblioteki systemowe); npm ci; npx playwright install, z --with-deps na tej samej maszynie; node bin/nexus.js ci --all lub wybrane identyfikatory testów | npm ci; node bin/nexus.js ci ze zmienną TC_IDS lub --all. Obraz zawiera już przeglądarki. |
| Artefakty | actions/upload-artifact@v4, if: always(), nazwa nexus-evidence, ścieżka evidence/ | artifacts: when: always, reports: junit: evidence/ci/junit.xml, paths: evidence/ |
W przypadku wielu przeglądarek GitHub uruchamia osobne zadanie dla każdej z nich, z ustawieniem fail-fast: false, a każde zadanie dodaje --project=<browser>. Wybrane kontrole dodają --visual, --a11y, --chaos=, --loop= lub --no-retry.
Jenkins, Azure DevOps, CircleCI i Bitbucket
Pozostali czterej dostawcy otrzymują to samo polecenie, node bin/nexus.js ci --all, po jednym przebiegu na przeglądarkę, publikowanie wyników JUnit za pomocą własnego mechanizmu dostawcy oraz katalog evidence/ zachowywany jako artefakt nawet po nieudanym przebiegu. Jenkins, CircleCI i Bitbucket korzystają z obrazu mcr.microsoft.com/playwright:v1.62.1-noble; Azure DevOps korzysta z agenta ubuntu-latest i najpierw instaluje przeglądarki.
| Dostawca | Plik | Nieudane testy są widoczne w |
|---|---|---|
| Jenkins | Jenkinsfile | Strona Test Result danej kompilacji |
| Azure DevOps | azure-pipelines.yml | Karta Tests danego przebiegu oraz Test Plans, Runs |
| CircleCI | .circleci/config.yml | Karta Tests danego zadania |
| Bitbucket | bitbucket-pipelines.yml | Karta Tests danego potoku |
Ci czterej dostawcy odczytują sekrety z własnych magazynów. Studio wyświetla klucze, które należy tam dodać, bez wartości, i nie zapisuje niczego w tych magazynach. Opisane poniżej kontrola wyniku końcowego i zadanie wdrożenia dotyczą GitHub Actions i GitLab CI.
Kody zakończenia i JUnit XML
nexus ci uruchamia wskazane testy (TC1,TC2) lub wszystkie przy użyciu --all i kończy działanie z kodem 0, gdy testy przejdą pomyślnie, 1 w razie niepowodzenia i 2, gdy nic nie uruchomiono lub polecenie było nieprawidłowe. Zapisuje JUnit XML w evidence/ci/junit.xml; --junit=<path> zapisuje go w innym miejscu.
Jedna kontrola wyniku końcowego dla całej macierzy
Przy wielu przeglądarkach GitHub pokazuje osobną kontrolę dla każdej z nich. Wygenerowany przepływ pracy dodaje zadanie o nazwie Nexus verdict, które uruchamia się po wszystkich tych kontrolach, nawet jeśli któraś zakończyła się niepowodzeniem, i ma status pomyślny tylko wtedy, gdy testy we wszystkich przeglądarkach zakończyły się powodzeniem. Ustaw tę jedną kontrolę jako wymaganą w regule ochrony gałęzi zamiast osobnej kontroli dla każdej przeglądarki.
Wdrożenie po pomyślnym przebiegu
Zaznacz wdrożenie po pomyślnym przebiegu na ekranie CI/CD, aby dodać zadanie wdrożenia. Uruchamia się ono tylko po wypchnięciu zmian do głównej gałęzi i tylko po pomyślnym przebiegu zestawu testów: nieudany przebieg powoduje jego pominięcie. W GitHub czeka na kontrolę wyniku końcowego i działa w środowisku production, więc obowiązują reguły ochrony środowiska.
| Cel | Co robi | Odczytywane sekrety |
|---|---|---|
| Wyzwalacz wdrożenia (GitHub, GitLab) | Wysyła żądania POST na adres URL wdrożenia udostępniony przez dostawcę hostingu | NEXUS_DEPLOY_HOOK |
| Cloudflare (GitHub) | wrangler deploy | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
| Vercel (GitHub) | vercel pull, build i deploy --prebuilt --prod | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
| SSH i Docker Compose (GitHub) | docker compose pull i up -d w folderze na Twoim serwerze | DEPLOY_SSH_HOST, DEPLOY_SSH_USER, DEPLOY_SSH_KEY, DEPLOY_SSH_KNOWN_HOSTS, DEPLOY_SSH_DIR |
- Sekrety tylko po nazwie. Każdy sekret trafia do kroku jako zmienna środowiskowa, nigdy jako tekst skryptu, a zadanie najpierw sprawdza każdy z nich: brak sekretu powoduje błąd z jego nazwą.
- SSH sprawdza klucz serwera. Klucz hosta pochodzi z
DEPLOY_SSH_KNOWN_HOSTS; sprawdzanie klucza hosta nigdy nie jest wyłączane. - Minimalne uprawnienia. Zadania wyzwalacza wdrożenia i SSH nie otrzymują żadnych uprawnień do repozytorium; Cloudflare i Vercel otrzymują dostęp do odczytu, aby pobrać kod.
Miejsce uruchamiania zadania: trzy opcje
Każda opcja wymaga komputera z aktywacją: silnik nie uruchamia zestawów testów na komputerze bez aktywacji, a każdy aktywowany komputer wlicza się do limitu Twojego planu (plany i komputery). Runner w chmurze, runs-on: ubuntu-latest, uruchamia nową maszynę wirtualną dla każdego zadania, więc nigdy nie zachowuje aktywacji; użyj własnego runnera działającego na stałym komputerze.
Opcja A: własny runner na komputerze ze Studio
- Na komputerze PC lub mini PC z Windows 11, na którym zainstalowano i aktywowano Nexus StudioQA, zarejestruj runnera: w GitHub, w repozytorium, wybierz Ustawienia, Actions, Runnery, Nowy własny runner; w GitLab wybierz Ustawienia, CI/CD, Runnery.
- Na ekranie CI/CD wybierz Mój komputer. Plik będzie wtedy zawierał
runs-on: [self-hosted]w GitHub lubtags: [self-hosted]w GitLab. - Uruchom runnera jako użytkownik systemu Windows, który aktywował Studio. Silnik odczytuje aktywację z profilu tego użytkownika, z pliku
.nexus-studioqa\license.json, więc usługa runnera działająca na innym koncie jej nie znajdzie.
Zadanie korzysta z aktywacji tego komputera: jedna aktywacja na komputer, już uwzględniona w Twoim planie, bez klucza w potoku. Używaj runnera na własnej infrastrukturze wyłącznie z prywatnym repozytorium, zgodnie z ostrzeżeniem Studio: w publicznym repozytorium każdy, kto otworzy żądanie scalenia, może uruchomić kod na Twoim komputerze.
Opcja B: runner na serwerze VPS, w kontenerze
Serwer VPS z systemem Ubuntu 24.04 LTS x86_64, Docker Engine i Compose v2, z dostępem przez SSH z uwierzytelnianiem kluczem. Liczy się jako jeden komputer w Twoim planie.
- Na ekranie CI/CD wybierz Mój komputer + Docker. Oprócz pliku potoku Studio zapisuje w obszarze roboczym pliki
docker-compose.nexus-studioqa-runner.yml,Dockerfile.runneroraz dwa skrypty startowe runnera.Dockerfile.runnerbazuje na obraziemcr.microsoft.com/playwright:v1.62.1-noble. - Na ekranie widać polecenia do wklejenia w sesji SSH na serwerze VPS, a nie w terminalu samego Studio. W przypadku GitHub pobierany jest token rejestracyjny ważny przez 1 godzinę i ustawiane są zmienne
REPO_URL,RUNNER_TOKENiRUNNER_NAME; w przypadku GitLab,GITLAB_URLiGITLAB_RUNNER_TOKEN. Następnie:
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
Pierwszy wiersz dotyczy GitHub, drugi GitLab. W kontenerze z systemem Linux licencja identyfikuje komputer na podstawie /etc/machine-id: zamontuj ten plik z hosta tylko do odczytu, /etc/machine-id:/etc/machine-id:ro, a folder .nexus-studioqa z katalogu domowego runnera przechowuj na woluminie, aby zachować aktywację po ponownym zbudowaniu obrazu. Aktywuj raz, ręcznie, za pomocą nexus license activate i swojego klucza, nigdy z pliku potoku.
Obecnie obraz runnera jest budowany na serwerze VPS na podstawie Dockerfile.runner. Repozytorium nie ma jeszcze rejestru kontenerów: obraz opublikowany w GitHub Container Registry, z którego korzysta środowisko wykonawcze VPS w Studio, pojawi się w następnej wersji.
Opcja C: zadanie CI uruchamia wykonanie na hoście przez SSH
Zadanie pozostaje niewielkie, niezależnie od środowiska wykonawczego, a zestawy testów działają na Twoim hoście, gdzie obszar roboczy i silnik znajdują się pod określoną ścieżką, zgodnie z wymaganiami środowiska uruchomieniowego SSH w Studio. Ekran CI/CD nie generuje tego zadania; oto opcje używane przez środowisko uruchomieniowe SSH samego 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
- Tylko uwierzytelnianie kluczem.
BatchMode=yesnigdy nie pyta o hasło. Zapisz klucz prywatny z sekretu CI w pliku, który może odczytać tylko zadanie, i usuń go po zakończeniu zadania. StrictHostKeyChecking=yes. Klucz hosta musi już znajdować się w plikuknown_hostsśrodowiska wykonawczego: przechowuj wiersz z kluczem publicznym hosta w zmiennej CI i zapisz go w tym pliku przed pierwszym wywołaniemssh. Nigdy nie ustawiaj wartościno.- Kod zakończenia jest zwracany.
sshkończy działanie z kodem zdalnego polecenia, więc krok kończy się niepowodzeniem, gdy zestaw testów nie przejdzie, ascppobiera materiały dowodowe, w tym JUnit XML, na potrzeby kroku zapisywania artefaktów. - Host sprawdza własną licencję i jest liczony jako jedna maszyna w Twoim planie.
Sekrety
- Przechowuj tokeny, adresy URL webhooków i klucze prywatne SSH jako sekrety CI: w GitHub w Settings, Secrets and variables, Actions lub za pomocą
gh secret set <KEY>; w GitLab jako maskowane zmienne w Settings, CI/CD, Variables. Nigdy w repozytorium, pliku potoku ani dzienniku. - Wygenerowany przepływ pracy GitHub odczytuje tylko klucze integracji i token CI z
secrets.<KEY>, i tylko w krokach Nexus: klucze Telegram, Slack, Teams, Jira, Azure Boards i GitHub Issues, przełączniki powiadomień orazNEXUS_CI_LICENSE. Ekran CI/CD ustawia je za Ciebie: przez API GitHub, jeśli zapiszeszGITHUB_CI_TOKENw Ustawieniach, lub za pomocągh secret setw przeciwnym razie. Nic nie jest wypisywane. - Klucz licencyjny nie powinien trafiać do CI. Hostowany moduł wykonawczy używa osobnego tokenu CI,
NEXUS_CI_LICENSE, z portalu konta: przechowuj go wyłącznie jako zamaskowany sekret. Trwały moduł wykonawczy można zamiast tego aktywować jednorazowo, ręcznie: klucz jest wysyłany raz i nie jest zachowywany. - Nigdy nie wypisuj sekretu w kroku. Silnik usuwa sekrety z tekstu zapisywanego jako materiał dowodowy, takiego jak komunikaty o niepowodzeniach JUnit i dzienniki; nie usuwa ich z danych wyjściowych konsoli samego zadania, a usługa CI maskuje tylko wartości zapisane jako sekrety.
JUnit XML i materiały dowodowe jako artefakty
- GitHub przesyła
evidence/jakonexus-evidence, a przy użyciu macierzy osobnynexus-evidence-<browser>dla każdej przeglądarki, niezależnie od tego, czy uruchomienie zakończyło się powodzeniem czy niepowodzeniem. Plik JUnit XML znajduje się wewnątrz, wevidence/ci/junit.xml. - GitLab zachowuje
evidence/i udostępniaevidence/ci/junit.xmljako raport JUnit, dzięki czemu nieudane testy są widoczne w żądaniu scalenia. - W Studio ekran CI/CD umożliwia uruchomienie przepływu pracy GitHub i pobranie jego materiałów dowodowych do
evidence/ci-remote/run-<id>w obszarze roboczym. - Gdzie znajduje się kopia. Artefakt to kopia materiałów dowodowych, w tym zrzutów ekranu i dzienników, przechowywana w usłudze CI; w przypadku usługi hostowanej jest to sprzęt należący do kogoś innego. Ustaw okres przechowywania artefaktów zgodny ze swoją polityką lub zachowaj materiały dowodowe w swoim środowisku wykonawczym i przesyłaj tylko
evidence/ci/junit.xml.
Rozwiązywanie problemów
SEAT_LIMIT w środowisku wykonawczym hostowanym w chmurze lub tymczasowym
Każda nowa maszyna wirtualna jest dla licencji nową maszyną, więc tymczasowe środowisko wykonawcze wymagałoby aktywacji dla każdego zadania. Gdy wszystkie maszyny w Twoim planie są aktywne, aktywacja jest odrzucana z błędem SEAT_LIMIT: “Wszystkie maszyny w Twoim planie są w użyciu. Dezaktywuj jedną na swoim koncie.” Użyj trwałego środowiska wykonawczego na własnym hoście (opcja A lub B) i dezaktywuj maszyny, których już nie używasz, w sekcji Licencja i maszyny na swoim koncie (więcej o SEAT_LIMIT).
Środowisko wykonawcze było offline przez kilka dni
Licencja komputera musi być weryfikowana co najmniej raz na 7 dni. Potem przez kolejne 4 dni wyświetlane jest powiadomienie, a następnie włączany jest tryb tylko do odczytu: zestawy testów nie są uruchamiane do czasu pomyślnej weryfikacji, a materiały dowodowe pozostają dostępne do odczytu. Gdy komputer wykonawczy odzyska połączenie, nexus license renew ponawia weryfikację (praca bez połączenia).
„brak /etc/machine-id” w kontenerze
Kontener nie ma identyfikatora komputera, który można odczytać na potrzeby licencji. Zamontuj identyfikator hosta: -v /etc/machine-id:/etc/machine-id:ro, lub dodaj ten sam wiersz w sekcji volumes: pliku compose.
Zadanie kończy się kodem 2
Nic nie zostało uruchomione: żaden test nie pasował do identyfikatorów lub polecenie było nieprawidłowe. Sprawdź identyfikatory przekazane do nexus ci, w tc_ids na GitHub lub TC_IDS na GitLab.
Weryfikacja klucza hosta nie powiodła się
Ustawienie StrictHostKeyChecking=yes spowodowało odrzucenie hosta, którego nie ma w known_hosts lub którego klucz uległ zmianie. Dodaj klucz hosta z zaufanego źródła, po sprawdzeniu jego odcisku bezpośrednio na hoście. Nie wyłączaj weryfikacji.