요약
Jenkins에서 ReadyAPI 테스트를 실행하는 것은 testrunner 명령줄 도구와 SmartBear Jenkins 플러그인을 통해 가능하지만, 빌드 에이전트에 ReadyAPI를 설치해야 하며 빈번한 구성 문제가 발생합니다. Apidog의 CI/CD 통합은 에이전트 소프트웨어 요구사항이나 실행당 라이선스 비용 없이 간단한 npm 설치 CLI를 통해 작동합니다.
서론
CI/CD 파이프라인에 API 테스트를 통합하는 것은 테스트 팀이 할 수 있는 가장 가치 있는 일 중 하나입니다. 코드가 스테이징 또는 프로덕션에 도달하기 전에 모든 풀 리퀘스트에서 회귀(regression)를 감지하는 것은 설정 노력의 가치가 있습니다.
ReadyAPI는 명령줄 testrunner 도구와 공식 SmartBear Jenkins 플러그인이라는 두 가지 메커니즘을 통해 Jenkins 통합을 지원합니다. 둘 다 작동하지만, 각각 복잡성을 동반합니다. 이 가이드는 Jenkins와 ReadyAPI를 설정하는 방법, 발생할 수 있는 일반적인 문제, 그리고 Apidog가 더 적은 인프라 오버헤드로 동일한 파이프라인 통합을 제공하는 방법을 다룹니다.
Jenkins에서 ReadyAPI 설정하기: testrunner 접근 방식
testrunner는 ReadyAPI의 명령줄 실행 엔진입니다. Jenkins가 ReadyAPI 테스트를 헤드리스(headless)로 실행해야 할 때, 프로젝트 파일을 가리키는 인수를 사용하여 testrunner를 호출합니다.
사전 요구 사항:
API 테스트를 실행하는 모든 Jenkins 에이전트에 ReadyAPI가 설치되어 있어야 합니다. 이것이 가장 큰 운영 요구 사항입니다. 5개의 빌드 에이전트가 있고 그 중 어느 하나에서 ReadyAPI 테스트가 실행된다면, 5개 모두에 ReadyAPI가 설치되어야 합니다. 이는 다음을 초래합니다:
- ReadyAPI 업데이트 시 설치 유지보수 부담.
- 라이선스 문제: 각 에이전트 설치에 자체 라이선스가 필요합니까? SmartBear의 CI/CD 라이선스 정책은 계약에 따라 다릅니다. 귀하의 계정 팀과 확인하십시오.
- 클라우드 기반 에이전트의 에이전트 이미지 크기 및 시작 시간 증가.
기본 testrunner 명령어:
Linux/macOS에서:
/path/to/ReadyAPI/testrunner.sh \
-r \
-f /path/to/results \
-s "TestSuiteName" \
-c "TestCaseName" \
/path/to/project.xml
Windows에서:
C:\ReadyAPI\testrunner.bat ^
-r ^
-f C:\results ^
-s "TestSuiteName" ^
-c "TestCaseName" ^
C:\projects\project.xml
주요 testrunner 플래그:
-r: JUnit 호환 XML 보고서 생성-f <directory>: 결과 출력 디렉토리-s <name>: 특정 테스트 스위트 실행 (모두 실행하려면 생략)-c <name>: 특정 테스트 케이스 실행 (모두 실행하려면 생략)-e <environment>: 사용할 환경 지정-P <name>=<value>: 프로젝트 속성 재정의
Jenkins 파이프라인 단계:
Jenkinsfile에서:
stage('API Tests') {
steps {
sh '''
/opt/readyapi/testrunner.sh \
-r \
-f ${WORKSPACE}/test-results \
-e ${ENVIRONMENT} \
${WORKSPACE}/project.xml
'''
junit 'test-results/*.xml'
}
}
junit 단계는 결과를 Jenkins에 게시하여 빌드 보고서에 실패가 표시되도록 합니다.
SmartBear Jenkins 플러그인 사용하기
SmartBear는 Jenkins 플러그인 디렉토리에서 ReadyAPI용 Jenkins 플러그인을 제공합니다. 이 플러그인은 쉘 명령을 수동으로 작성할 필요 없이 Jenkins UI에서 빌드 단계를 제공합니다.
설치 방법:
- Jenkins > Jenkins 관리 > 플러그인 관리로 이동합니다.
- “SmartBear ReadyAPI Functional Testing”을 검색합니다.
- 설치하고 Jenkins를 재시작합니다.
설치 후, Jenkins 전역 설정에서 ReadyAPI 설치 경로를 구성한 다음, 빌드 단계 드롭다운에서 선택하여 빌드 작업에 ReadyAPI 테스트 단계를 추가합니다.
이 플러그인은 인수를 자동으로 구성하고 결과를 Jenkins의 테스트 보고에 통합합니다. Groovy 파이프라인 스크립트보다 GUI 구성을 선호하는 팀에게 이 플러그인은 설정 시간을 단축해 줍니다.
플러그인 제한 사항: 이 플러그인은 특정 Jenkins 버전 및 ReadyAPI 버전에 종속됩니다. 플러그인 업데이트는 ReadyAPI 릴리스와 Jenkins 릴리스 모두에 뒤처집니다. 최신 ReadyAPI를 실행하는 팀은 플러그인 업데이트를 기다려야 하는 호환성 문제에 직면할 수 있습니다.
일반적인 Jenkins + ReadyAPI 문제
testrunner가 시작 시 멈춤. ReadyAPI는 Java/Swing 애플리케이션입니다. CI에서 헤드리스로 실행될 때, 때때로 GUI 구성 요소를 초기화하려고 시도합니다. 이 문제가 발생하면 DISPLAY 환경 변수를 설정하거나 -Djava.awt.headless=true JVM 인수를 사용하십시오.
라이선스 유효성 검사 실패. ReadyAPI는 시작 시 라이선스를 검증합니다. CI 에이전트가 SmartBear의 라이선스 서버에 연결할 수 없는 경우 (제한된 기업 네트워크에서 흔함), 테스트 실패가 아닌 라이선스 오류와 함께 테스트가 실패합니다. 플로팅 라이선스 서버 설정 또는 오프라인 라이선스를 구성해야 합니다.
메모리 부족 오류. testrunner의 기본 JVM 힙 설정은 보수적입니다. 대규모 테스트 스위트 또는 많은 데이터 파일이 있는 프로젝트는 -Xmx 설정을 조정해야 할 수 있습니다. testrunner.sh 또는 testrunner.bat 파일을 편집하여 힙을 늘리십시오:
-Xms128m -Xmx1024m
프로젝트 파일의 경로 문제. ReadyAPI 프로젝트는 경로를 사용하여 외부 파일(데이터 소스, 스키마, 스크립트)을 참조합니다. CI에서 실행할 때, 작업 디렉토리가 올바르게 설정된 경우에만 상대 경로가 작동합니다. 프로젝트 파일의 절대 경로는 프로젝트가 여러 시스템 간에 이동할 때 문제를 일으킵니다. 경로에 프로젝트 속성을 사용하고 런타임에 -P 플래그를 통해 설정하십시오.
로컬에서는 통과하지만 CI에서 실패하는 테스트. 주로 환경 차이로 인해 발생합니다: 외부 파일의 다른 데이터, 다른 환경 변수 값 또는 하드코딩된 경로. testrunner -e 인수에 명시적인 환경 선택과 함께 ReadyAPI의 환경 기능을 사용하십시오.
Apidog Jenkins 통합: 더 간단한 접근 방식
Apidog의 CLI 러너는 npm을 통해 설치되며 빌드 에이전트에 데스크톱 애플리케이션이 필요하지 않습니다.
Jenkins 에이전트에 설치:
npm install -g apidog-cli
또는 파이프라인 단계에서:
npm ci
# apidog-cli is in devDependencies
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'
}
}
ReadyAPI와의 주요 차이점:
에이전트에 데스크톱 애플리케이션이 없습니다. Apidog CLI는 경량 Node.js 패키지입니다. 몇 분이 아닌 몇 초 만에 설치할 수 있습니다. GUI 초기화 문제나 라이선스 서버 연결 요구 사항이 없습니다.
실행당 라이선스 문제 없음. Apidog는 CI 실행당 비용을 청구하지 않습니다. 파이프라인이 요구하는 만큼 하루에 여러 테스트 사이클을 실행하십시오.
환경 변수 또는 플래그를 통한 환경 구성. Jenkins 자격 증명 저장소에서 직접 자격 증명 및 기본 URL을 환경 변수로 전달하십시오:
withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}
GitHub Actions 비교:
GitHub Actions를 사용하는 팀의 경우, Apidog 접근 방식은 마찬가지로 깔끔합니다:
- name: Run API tests
run: |
npm install -g apidog-cli
apidog run collection.json --environment staging
env:
API_BASE_URL: ${{ vars.STAGING_URL }}
API_KEY: ${{ secrets.API_KEY }}
ReadyAPI의 동등한 기능은 ReadyAPI가 설치된 자체 호스팅 러너 또는 복잡한 Docker 이미지 빌드를 필요로 합니다. 둘 다 그리 간단하지 않습니다.
ReadyAPI에서 Apidog로 CI/CD 마이그레이션
테스트 스위트를 마이그레이션하고 CI/CD 구성을 동시에 업데이트해야 하는 경우:
- ReadyAPI에서 API 정의를 내보내고 Apidog로 가져옵니다.
- Jenkins 에이전트에 Apidog CLI를 설치합니다.
- 기존 ReadyAPI 단계와 함께 파이프라인에 Apidog 테스트 단계를 추가합니다.
- 둘 다 병렬로 실행합니다. 실패율과 테스트 커버리지를 비교합니다.
- Apidog의 커버리지에 확신이 생기면 ReadyAPI 단계를 제거합니다.
- 다음 에이전트 이미지 새로 고침 시 빌드 에이전트에서 ReadyAPI를 제거합니다.
자주 묻는 질문
ReadyAPI의 testrunner는 별도의 CI 라이선스를 필요로 합니까?SmartBear의 CI/CD 사용에 대한 라이선스 정책은 계약에 따라 다릅니다. 일부 계약에는 표준 라이선스에 CI/CD 실행 권한이 포함되어 있으며, 다른 계약에는 별도의 계약이 필요합니다. CI 실행이 포함되어 있다고 가정하기 전에 계약을 확인하거나 SmartBear 계정 관리자에게 문의하십시오.
ReadyAPI 테스트를 Docker 컨테이너에서 실행할 수 있습니까?네, 노력하면 가능합니다. ReadyAPI가 설치된 Docker 이미지를 빌드하고 이를 Jenkins 에이전트 컨테이너로 사용할 수 있습니다. 이미지는 크고(ReadyAPI는 데스크톱 애플리케이션임) 헤드리스 구성이 필요합니다. 작동하지만 컨테이너화된 CI 환경용으로 구축된 도구에 비해 복잡성을 더합니다.
Apidog는 Jenkins에서 병렬 테스트 실행을 지원합니까?네. 여러 Apidog CLI 인스턴스를 병렬 Jenkins 단계에서 실행할 수 있으며, 각 인스턴스는 다른 컬렉션 또는 환경을 실행합니다. 병렬 실행은 Apidog CLI가 아닌 Jenkinsfile을 통해 제어됩니다.
Apidog는 Jenkins용으로 어떤 테스트 보고서 형식을 생성합니까?Apidog의 CLI는 JUnit XML 보고서를 생성할 수 있으며, Jenkins는 이를 기본적으로 구문 분석하여 테스트 결과 섹션에 표시합니다. 이 형식은 ReadyAPI의 testrunner가 생성하는 것과 동일합니다.
Apidog 테스트 스크립트는 CLI 러너와 동일한 프로세스에서 실행됩니까?네. JavaScript 테스트 스크립트는 Apidog CLI의 Node.js 프로세스 내에서 실행됩니다. 별도로 구성해야 할 스크립트 실행 환경은 없습니다.
공식 Apidog Jenkins 플러그인이 있습니까?Apidog CLI는 Jenkins에서 쉘 단계로 실행되며, 전용 플러그인이 필요하지 않습니다. 이 접근 방식은 Jenkins 또는 Apidog가 새 버전을 릴리스할 때 업데이트가 필요한 플러그인 기반 통합보다 유지보수하기 더 간단합니다.
ReadyAPI의 Jenkins 통합은 작동하지만, 상당한 인프라 관리가 필요합니다. 포괄적인 API 테스트 커버리지를 유지하면서 CI/CD 설정을 단순화하려는 팀에게 Apidog의 CLI 접근 방식은 에이전트 소프트웨어 요구사항, 라이선스 서버 종속성 및 복잡한 환경 구성과 같은 가장 일반적인 문제점을 제거합니다.