CI/CD에서 테스트 실행하기
Studio의 CI/CD 화면은 GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI 또는 Bitbucket용 파이프라인 파일을 작성합니다. 이 가이드에서는 해당 파일이 실행하는 작업, 단일 종합 판정 검사, 실행 통과 후 선택적 배포, 작업을 실행할 수 있는 세 가지 위치, 비밀 값, 생성되는 JUnit XML 및 증거 자료, CI 환경에서 발생하는 오류를 다룹니다.
최종 업데이트:
작성: Verdict System LLC의 Nexus StudioQA 팀.
파이프라인 파일
CI/CD 화면에서 제공업체, 브라우저, 검사 항목, 작업 실행 위치를 선택한 다음 파일을 생성하세요. Studio는 먼저 로컬에서 파일을 검증하며, 같은 화면에서 커밋하고 푸시할 수도 있습니다. 터미널에서는 nexus init --ci github 또는 nexus init --ci gitlab으로 동일한 파일을 작성할 수 있습니다.
| 구성 요소 | GitHub Actions | GitLab CI |
|---|---|---|
| 파일 | .github/workflows/nexus-ci.yml | .gitlab-ci.yml |
| 실행 조건 | 풀 리퀘스트, main 또는 master로의 푸시, tc_ids 입력값을 사용하는 수동 실행(workflow_dispatch). 야간 회귀 테스트를 켜면 UTC 기준 schedule cron이 추가되며, 기본값은 0 6 * * *입니다. | 프로젝트의 파이프라인 규칙을 따릅니다. 파일에는 일정이 없습니다: 야간에 실행하려면 GitLab에서 파이프라인 일정을 추가하세요. |
| Runner | 클라우드 호스팅 실행기에서는 runs-on: ubuntu-latest를 사용하고 mcr.microsoft.com/playwright:v1.62.1-noble 이미지 안에서 실행; 자체 실행기에서는 runs-on: [self-hosted] 사용 | 이미지는 mcr.microsoft.com/playwright:v1.62.1-noble; 자체 실행기는 tags: [self-hosted] |
| 단계 | actions/checkout@v4; Docker를 사용하지 않는 자체 시스템에서만 Node.js 22와 함께 actions/setup-node@v4 사용 (이미지에는 Node.js와 시스템 라이브러리가 이미 포함됨); npm ci; npx playwright install, 동일한 자체 시스템에서는 --with-deps 추가; node bin/nexus.js ci --all, 또는 선택한 테스트 ID 지정 | npm ci; TC_IDS 변수 또는 --all을 사용하는 node bin/nexus.js ci. 이미지에는 브라우저가 이미 포함되어 있습니다. |
| 결과물 | actions/upload-artifact@v4, if: always(), 이름 nexus-evidence, 경로 evidence/ | artifacts: when: always, reports: junit: evidence/ci/junit.xml, paths: evidence/ |
브라우저가 두 개 이상이면 GitHub는 fail-fast: false로 브라우저별 작업을 하나씩 실행하며, 각 작업에 --project=<browser>를 추가합니다. 선택한 검사 항목에 따라 --visual, --a11y, --chaos=, --loop= 또는 --no-retry가 추가됩니다.
Jenkins, Azure DevOps, CircleCI 및 Bitbucket
나머지 네 제공업체에서도 동일한 명령인 node bin/nexus.js ci --all을 사용하고, 브라우저마다 한 번씩 실행하며, 각 제공업체의 JUnit 게시 기능을 이용합니다. 실행이 실패해도 evidence/는 산출물로 보관됩니다. Jenkins, CircleCI, Bitbucket은 mcr.microsoft.com/playwright:v1.62.1-noble 이미지에서 실행되며; Azure DevOps는 ubuntu-latest 에이전트에서 먼저 브라우저를 설치한 후 실행됩니다.
| 제공업체 | 파일 | 실패한 테스트 표시 위치 |
|---|---|---|
| Jenkins | Jenkinsfile | 빌드의 테스트 결과 페이지 |
| Azure DevOps | azure-pipelines.yml | 실행의 테스트 탭 및 테스트 계획의 실행 목록 |
| CircleCI | .circleci/config.yml | 작업의 테스트 탭 |
| Bitbucket | bitbucket-pipelines.yml | 파이프라인의 테스트 탭 |
이 네 제공업체는 각자의 저장소에서 비밀 값을 읽습니다. Studio는 해당 저장소에 추가할 키 이름만 값 없이 나열하며, 저장소에 직접 기록하지 않습니다. 아래의 종합 판정 검사와 배포 작업은 GitHub Actions 및 GitLab CI용입니다.
종료 코드와 JUnit XML
nexus ci는 지정한 테스트(TC1,TC2) 또는 --all로 모든 테스트를 실행하고, 통과하면 0, 실패하면 1, 아무것도 실행되지 않았거나 명령이 잘못되었으면 2로 종료합니다. JUnit XML은 evidence/ci/junit.xml에 저장됩니다; --junit=<path>를 사용하면 다른 위치에 저장할 수 있습니다.
전체 행렬을 위한 단일 종합 판정 검사
여러 브라우저를 사용하면 GitHub는 브라우저마다 하나씩 검사를 표시합니다. 생성된 워크플로는 Nexus verdict라는 작업을 추가합니다. 이 작업은 브라우저 중 하나가 실패해도 모든 브라우저의 실행이 끝난 후 실행되며, 모든 브라우저가 통과해야만 통과로 표시됩니다. 브랜치 보호 규칙에서는 브라우저별 검사 대신 이 단일 검사를 필수로 지정하세요.
통과 후 배포
CI/CD 화면에서 통과 후 배포를 선택하면 배포 작업이 추가됩니다. 이 작업은 메인 브랜치에 푸시할 때, 전체 테스트가 통과한 경우에만 실행됩니다: 실행이 실패하면 건너뜁니다. GitHub에서는 종합 판정 검사가 끝날 때까지 기다린 후 production 환경에서 실행되므로 환경 보호 규칙이 적용됩니다.
| 대상 | 주요 기능 | 읽어 오는 비밀 값 |
|---|---|---|
| 배포 훅 (GitHub, GitLab) | 호스팅 업체가 제공하는 배포 URL에 POST 요청 전송 | NEXUS_DEPLOY_HOOK |
| Cloudflare (GitHub) | wrangler deploy | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
| Vercel (GitHub) | vercel pull, build 및 deploy --prebuilt --prod | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
| SSH 및 Docker Compose (GitHub) | 서버의 폴더에서 docker compose pull 및 up -d 실행 | DEPLOY_SSH_HOST, DEPLOY_SSH_USER, DEPLOY_SSH_KEY, DEPLOY_SSH_KNOWN_HOSTS, DEPLOY_SSH_DIR |
- 비밀 값은 이름으로만 참조. 각 비밀 값은 스크립트 본문에 포함되지 않고 환경 변수로 해당 단계에 전달됩니다. 작업은 먼저 각 비밀 값의 존재 여부를 확인합니다: 누락된 비밀 값이 있으면 해당 이름을 표시하며 실패합니다.
- SSH는 서버의 키를 확인합니다. 호스트 키는
DEPLOY_SSH_KNOWN_HOSTS에서 가져옵니다; 호스트 키 확인은 절대 비활성화하지 않습니다. - 최소 권한. 배포 훅과 SSH 작업에는 저장소 권한이 부여되지 않습니다; Cloudflare와 Vercel에는 코드를 체크아웃할 수 있도록 읽기 권한이 부여됩니다.
작업 실행 위치: 세 가지 옵션
모든 옵션에는 활성화된 컴퓨터가 필요합니다: 엔진은 활성화되지 않은 컴퓨터에서 테스트 모음을 실행하지 않으며, 활성화된 각 컴퓨터는 요금제의 컴퓨터 수에 포함됩니다(요금제와 컴퓨터). 클라우드 호스팅 실행기인 runs-on: ubuntu-latest는 작업마다 새 가상 머신을 시작하므로 활성화 상태를 유지하지 못합니다; 계속 유지되는 자체 실행기를 사용하세요.
옵션 A: Studio가 설치된 컴퓨터의 자체 호스팅 실행기
- Nexus StudioQA가 설치되고 활성화된 Windows 11 PC 또는 미니 PC에 실행기를 등록하세요: GitHub에서는 저장소의 설정, Actions, 실행기, 새 자체 호스팅 실행기에서; GitLab에서는 설정, CI/CD, 실행기에서 등록합니다.
- CI/CD 화면에서 내 컴퓨터를 선택하세요. 그러면 파일에 GitHub의 경우
runs-on: [self-hosted], GitLab의 경우tags: [self-hosted]가 지정됩니다. - Studio를 활성화한 Windows 사용자 계정으로 러너를 실행하세요. 엔진은 해당 사용자의 프로필에 있는
.nexus-studioqa\license.json에서 활성화 정보를 읽으므로, 다른 계정으로 실행되는 러너 서비스는 활성화 정보를 찾지 못합니다.
작업은 이 기기의 활성화 정보를 사용합니다: 기기당 활성화 1개가 이미 요금제에 반영되어 있으며, 파이프라인에는 키를 넣지 않습니다. Studio의 경고대로, 자체 호스팅 러너는 비공개 저장소에서만 사용하세요: 공개 저장소에서는 누구든 풀 리퀘스트를 열어 사용자 기기에서 코드를 실행할 수 있습니다.
옵션 B: VPS의 컨테이너에서 실행되는 러너
Ubuntu 24.04 LTS x86_64, Docker Engine 및 Compose v2가 설치되어 있고 SSH 키 인증으로 접속하는 VPS입니다. 요금제의 기기 1대로 계산됩니다.
- CI/CD 화면에서 내 기기 + Docker를 선택하세요. Studio는 파이프라인 파일 외에도
docker-compose.nexus-studioqa-runner.yml,Dockerfile.runner및 러너의 진입점 스크립트 2개를 작업 공간에 작성합니다.Dockerfile.runner는mcr.microsoft.com/playwright:v1.62.1-noble을 기반으로 합니다. - 화면에는 Studio 자체 터미널이 아닌 VPS의 SSH 세션에 붙여 넣을 명령이 표시됩니다. GitHub의 경우 유효 시간이 1시간인 등록 토큰을 가져와
REPO_URL,RUNNER_TOKEN및RUNNER_NAME을 설정하고; GitLab의 경우GITLAB_URL및GITLAB_RUNNER_TOKEN을 설정합니다. 그런 다음:
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
첫 번째 줄은 GitHub용이고, 두 번째 줄은 GitLab용입니다. Linux 컨테이너 내부에서 라이선스는 /etc/machine-id로 기기를 식별합니다: 호스트의 파일을 /etc/machine-id:/etc/machine-id:ro와 같이 읽기 전용으로 마운트하고, 러너 홈의 .nexus-studioqa 폴더를 볼륨에 보관하여 다시 빌드해도 활성화 정보가 유지되도록 하세요. nexus license activate와 키를 사용해 수동으로 한 번만 활성화하고, 파이프라인 파일에서는 절대 활성화하지 마세요.
현재 러너 이미지는 VPS에서 Dockerfile.runner로 빌드됩니다. 저장소에는 아직 컨테이너 레지스트리가 없습니다: Studio의 VPS 런타임에서 실행할 이미지는 다음 릴리스에서 GitHub Container Registry에 게시됩니다.
옵션 C: CI 작업이 SSH를 통해 호스트에서 실행을 시작
어떤 실행기를 사용하든 작업은 간소하게 유지되며, 테스트 모음은 소유한 호스트에서 실행됩니다. 해당 호스트의 경로에 작업 공간과 엔진을 두는 방식으로, Studio의 SSH 런타임이 요구하는 구성입니다. CI/CD 화면은 이 작업을 생성하지 않습니다; 다음은 Studio 자체 SSH 런타임이 사용하는 옵션입니다:
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
- 키 인증만 사용합니다.
BatchMode=yes는 비밀번호를 묻지 않습니다. CI 비밀 값에 저장된 개인 키를 작업에서만 읽을 수 있는 파일에 기록하고, 작업이 끝나면 삭제하세요. StrictHostKeyChecking=yes. 호스트 키는 실행기의known_hosts에 미리 등록되어 있어야 합니다: 호스트의 공개 키 행을 CI 변수에 저장하고 첫ssh실행 전에 해당 파일에 기록하세요. 절대no로 설정하지 마세요.- 종료 코드가 반환됩니다.
ssh는 원격 명령의 코드로 종료되므로 테스트 모음이 실패하면 해당 단계도 실패하며,scp는 JUnit XML을 포함한 증거 자료를 가져와 산출물 저장 단계에 전달합니다. - 호스트는 자체적으로 라이선스를 확인하며 요금제의 기기 한 대로 집계됩니다.
비밀 정보
- 토큰, 웹훅 URL, SSH 개인 키는 CI 비밀 값으로 저장하세요: GitHub에서는 설정, 비밀 값 및 변수, Actions에서 저장하거나
gh secret set <KEY>를 사용하세요; GitLab에서는 설정, CI/CD, 변수에서 마스킹된 변수로 저장하세요. 저장소, 파이프라인 파일 또는 로그에는 절대 남기지 마세요. - 생성된 GitHub 워크플로는
secrets.<KEY>에서 연동 키와 CI 토큰만 읽으며, Nexus 단계에서만 사용합니다: Telegram, Slack, Teams, Jira, Azure Boards 및 GitHub Issues의 키, 알림 설정 스위치,NEXUS_CI_LICENSE가 이에 해당합니다. CI/CD 화면에서 이를 자동으로 설정합니다: 설정에GITHUB_CI_TOKEN을 저장한 경우 GitHub API를 통해, 그렇지 않은 경우gh secret set으로 설정합니다. 어떤 값도 출력되지 않습니다. - 라이선스 키는 CI에 넣지 마세요. 호스팅 실행기는 계정 포털에서 발급한 별도의 CI 토큰인
NEXUS_CI_LICENSE를 사용합니다: 반드시 마스킹된 비밀 값으로만 저장하세요. 영구 실행기는 대신 수동으로 한 번만 활성화할 수 있습니다: 키는 한 번 전송되며 보관되지 않습니다. - 어떤 단계에서도 비밀 값을 출력하지 마세요. 엔진은 JUnit 실패 메시지나 로그처럼 증거 자료로 저장하는 텍스트에서 비밀 값을 제거합니다; 작업 자체의 콘솔 출력에서는 제거하지 않으며, CI 서비스는 비밀 값으로 저장된 값만 마스킹합니다.
JUnit XML 및 증거 자료를 산출물로 저장
- GitHub는 실행 성공 여부와 관계없이
evidence/를nexus-evidence로 업로드하며, 행렬을 사용하면 브라우저별로nexus-evidence-<browser>를 하나씩 업로드합니다. JUnit XML은 그 안의evidence/ci/junit.xml에 있습니다. - GitLab은
evidence/를 보관하고evidence/ci/junit.xml을 JUnit 보고서로 등록하므로, 병합 요청에 실패한 테스트가 표시됩니다. - Studio의 CI/CD 화면에서 GitHub 워크플로 실행을 시작하고 해당 증거 자료를 작업 공간의
evidence/ci-remote/run-<id>로 다운로드할 수 있습니다. - 사본이 저장되는 위치. 산출물은 스크린샷과 로그를 포함한 증거 자료의 사본으로, CI 서비스의 저장소에 보관됩니다; 호스팅 서비스라면 다른 주체의 하드웨어에 저장됩니다. 정책에서 허용하는 산출물 보관 기간을 설정하거나, 증거 자료를 실행기에 보관하고
evidence/ci/junit.xml만 업로드하세요.
문제 해결
클라우드 호스팅 또는 임시 실행기에서 발생하는 SEAT_LIMIT
라이선스는 새 가상 머신을 각각 새 기기로 인식하므로, 임시 실행기는 작업마다 활성화해야 합니다. 요금제에서 허용하는 모든 기기가 활성화되면 SEAT_LIMIT 오류와 함께 활성화가 거부됩니다: “요금제의 모든 기기가 사용 중입니다. 계정에서 한 대를 비활성화하세요.” 영구 자체 호스팅 실행기(옵션 A 또는 B)를 사용하고, 계정의 라이선스 & 기기에서 더 이상 사용하지 않는 기기를 비활성화하세요(SEAT_LIMIT 자세히 알아보기).
실행기가 며칠 동안 오프라인 상태였음
각 컴퓨터의 라이선스는 최소 7일마다 검증을 받아야 합니다. 이후 4일 동안 안내가 표시된 뒤 읽기 전용으로 전환됩니다: 검증에 성공할 때까지 테스트 모음은 실행되지 않으며, 증거 자료는 계속 열람할 수 있습니다. 실행기가 다시 온라인 상태가 되면 nexus license renew로 재검증할 수 있습니다 (오프라인 작업).
컨테이너에서 “no /etc/machine-id” 발생
컨테이너에 라이선스 검증 시 읽을 컴퓨터 ID가 없습니다. 호스트의 ID를 마운트하세요: -v /etc/machine-id:/etc/machine-id:ro, 또는 compose 파일의 volumes: 아래에 같은 줄을 추가하세요.
작업이 종료 코드 2로 종료됨
아무것도 실행되지 않았습니다: ID와 일치하는 테스트가 없거나 명령이 잘못되었습니다. nexus ci에 전달한 ID를 확인하세요. GitHub에서는 tc_ids, GitLab에서는 TC_IDS에 지정되어 있습니다.
호스트 키 검증 실패
StrictHostKeyChecking=yes가 known_hosts에 없거나 키가 변경된 호스트를 거부했습니다. 호스트 자체에서 키 지문을 확인한 다음, 신뢰할 수 있는 출처에서 얻은 호스트 키를 추가하세요. 검증을 끄지 마세요.