Apidog에서 자동화 API 테스트 스케줄링 방법 (클라우드, 러너, CLI)

통과한 테스트 스위트는 계속 통과할 때만 의미가 있습니다. 오늘은 정상인 결제 흐름도 새벽의 종속성 호환성 변경, 주말의 인증서 만료, 설정 드리프트로 인해 언제든 중단될 수 있습니다. 고객의 불만으로 문제를 발견하지 않으려면, 사람이 직접 실행하지 않아도 API 테스트를 정기적으로 돌리고 실패 즉시 알림을 받도록 구성해야 합니다.

지금 Apidog를 사용해 보세요

Apidog의 예약 작업(Scheduled Tasks)은 저장된 테스트 시나리오를 지정한 주기로 실행하고, Runner와 알림 채널을 연결하는 기능입니다. 이 글에서는 예약 작업을 구성하는 방법, 현재 제약 사항, CLI와 cron을 사용하는 대안을 단계별로 설명합니다.

처음 API 모니터링을 구성한다면 API 모니터링 가이드도 함께 참고하세요. UI 필드와 동작의 기준은 Apidog 예약 작업 문서입니다.

예약 작업 기능은 현재 베타로 표시됩니다. 또한 예약 실행 가능 횟수는 요금제에 따라 달라질 수 있으므로, 짧은 실행 주기를 설정하기 전에 제한을 확인하세요.

예약 작업이 하는 일

예약 작업은 하나 이상의 저장된 API 테스트 시나리오를 반복 실행합니다. 대표적인 활용 사례는 다음과 같습니다.

• 핵심 API의 야간 회귀 테스트
• 스테이징 환경의 6시간 단위 스모크 테스트
• 주말 전체 건전성 점검
• 프로덕션 결제·인증·주문 흐름의 주기적 확인

작업에는 다음 구성이 저장됩니다.

1. 실행할 테스트 시나리오
2. 대상 환경
3. 실행 주기
4. 실행할 Runner
5. 실패 시 알림 채널

이 기능은 웹 스크래퍼나 데이터 수집 스케줄러가 아닙니다. 페이지를 크롤링하거나 선택자를 정의하는 대신, 기존 API 테스트 시나리오의 어설션, 연결된 요청, 추출 변수 등을 실행합니다. 결과도 데이터셋이 아니라 API 계약의 통과·실패 보고서입니다.

시작 전: 자체 호스팅 Runner 준비

예약 작업을 실행하려면 먼저 자체 호스팅 Runner를 구성해야 합니다.

Runner는 테스트 요청을 실제로 보내는 머신입니다. 예약 작업이 시작되면 Apidog 데스크톱 클라이언트에서 요청을 실행하는 것이 아니라, 선택한 Runner가 테스트 스위트를 실행합니다.

다음과 같은 환경을 Runner로 사용할 수 있습니다.

• CI 서버
• 항상 켜져 있는 소형 서버
• 전용 VM
• API와 같은 VPC에 배치된 머신

Runner는 예약된 시간에 실행 중이어야 하며 Apidog에서 접근할 수 있어야 합니다.

현재 Runner 선택 시 주의할 점

Runner 대상에는 다음 옵션이 표시될 수 있습니다.

• Apidog Cloud — 출시 예정
• 자체 호스팅 Runner

현재는 Apidog Cloud를 사용할 수 없으므로 자체 호스팅 Runner를 선택해야 합니다.

또한 테스트 요청은 Runner의 네트워크에서 전송됩니다. 따라서 다음 요소가 결과에 영향을 줄 수 있습니다.

• Runner의 리전
• VPN 연결 여부
• 방화벽과 보안 그룹
• 내부 DNS
• API와 Runner 간 네트워크 경로

로컬 실행과 예약 실행 결과가 다르다면, 먼저 Runner의 네트워크 환경을 확인하세요.

단계별: 예약 작업 생성하기

예시로 사용자 가입, 상품 조회, 장바구니 추가, Stripe 결제를 포함하는 전자상거래 API의 야간 회귀 테스트를 구성해 보겠습니다.

1. 테스트 모듈에서 예약 작업 열기

Apidog 클라이언트에서 테스트 모듈을 엽니다.

테스트 폴더 트리에서 예약 작업(Scheduled Tasks) 을 선택하면 프로젝트의 예약 작업을 확인하고 관리할 수 있습니다. 이 영역에서 다음을 확인할 수 있습니다.

• 등록된 모든 작업
• 작업 활성화 상태
• 작업별 실행 주기
• 작업별 실행 기록

2. 새 작업 만들기

+ 새로 만들기를 클릭해 예약 작업을 생성합니다.

작업이 많아질 경우 폴더를 만들어 다음처럼 그룹화하세요.

예약 작업
├── production
│   ├── 야간 회귀 테스트
│   └── 결제 API 건전성 검사
└── staging
    ├── 6시간 스모크 테스트
    └── 배포 후 검증

작업 이름과 설명은 목적이 분명하게 드러나도록 작성합니다.

작업 이름: 야간 회귀 - 프로덕션
설명: 가입, 상품 조회, 장바구니, Stripe 테스트 결제 핵심 경로 검사

각 작업은 활성화/비활성화 토글로 제어할 수 있습니다. 서비스 점검이나 대규모 마이그레이션 기간에는 삭제하지 않고 일시적으로 비활성화하면 됩니다.

3. 실행할 테스트 시나리오 선택

테스트 시나리오(Test Scenario) 에서 하나 이상의 시나리오를 선택합니다.

전자상거래 회귀 테스트라면 다음 시나리오를 하나의 작업에 포함할 수 있습니다.

• 가입 및 로그인
• 상품 탐색 및 장바구니 추가
• Stripe 테스트 카드 결제

각 시나리오에는 개별 실행 설정을 적용할 수 있습니다.

• 환경
• 테스트 데이터
• 반복 횟수
• 지연 시간
• 요청 및 응답 저장 여부

모든 시나리오에 동일한 설정을 적용하려면 동일한 실행 구성 사용(Use same execution config) 을 활성화하세요.

환경은 특히 중요합니다.

목적	권장 환경
야간 프로덕션 모니터링	Production
배포 전 스모크 테스트	Staging
기능 검증	Development 또는 Test

하나의 예약 작업에서 여러 환경을 혼합할 수도 있지만, 운영과 스테이징처럼 성격이 다른 검사는 별도 작업으로 분리하는 편이 관리하기 쉽습니다.

4. 실행 주기 설정

실행 주기(Run Cycle) 또는 실행 모드(Run Mode) 필드에서 주기를 설정합니다. UI 화면에 따라 라벨은 다를 수 있지만 같은 설정을 의미합니다.

예를 들면 다음과 같습니다.

• 매주 일요일 오후 11시
• 6시간마다
• 8시간마다
• 매일 오전 2시

권장 예시는 다음과 같습니다.

테스트 유형	권장 주기
야간 회귀 테스트	매일 업무 시간 전
스테이징 스모크 테스트	6시간마다
주말 건전성 검사	주 1회
핵심 API 상태 확인	요금제 한도 내에서 더 짧은 주기

야간 회귀 테스트는 업무 시간 전에 문제를 발견할 수 있고, 6시간 단위 스테이징 테스트는 환경 부하와 피드백 속도 사이의 균형을 맞추기 좋습니다.

5. 실행 위치 선택

Runner, 실행 위치(Runs On) 또는 실행 대상(Run On) 필드에서 자체 호스팅 Runner를 선택합니다.

여러 Runner가 있다면 API와 가장 가까운 네트워크 위치를 선택하세요. 예를 들어 프로덕션 API가 특정 VPC에 있다면, 해당 VPC 내부 또는 연결된 네트워크의 Runner를 선택하는 것이 좋습니다.

권장:
Production API → Production VPC의 Runner
Staging API    → Staging 네트워크의 Runner
Internal API   → VPN 또는 내부망에 연결된 Runner

모든 테스트 요청은 이 Runner에서 시작됩니다. 즉, 실제 사용자 또는 서비스가 API에 접근하는 경로와 유사한 네트워크를 선택해야 더 현실적인 결과를 얻을 수 있습니다.

6. 알림 설정

알림(Notification) 을 활성화하고 알림 채널을 연결합니다.

지원되는 채널은 다음과 같습니다.

• Slack
• Teams
• Webhook
• Jenkins
• Email

이메일 설정에서는 프로젝트 멤버 주소를 자동 완성할 수 있으며, 온콜 메일링 리스트나 공유 받은 편지함처럼 프로젝트 외부 주소도 직접 입력할 수 있습니다.

알림 시점도 선택할 수 있습니다.

• 모든 실행 후
• 실패 시에만

일반적인 야간 회귀 테스트는 실패 시에만 알림을 보내는 것이 좋습니다. 정상 실행 알림이 계속 쌓이면 실제 장애 신호를 놓치기 쉽습니다.

반대로 롤아웃이나 마이그레이션 기간에는 모든 실행 후 알림을 사용해 작업이 실제로 실행되고 있는지 확인할 수 있습니다.

7. 저장하고 활성화하기

설정을 저장한 뒤 작업 토글을 활성화합니다.

활성화된 작업은 지정한 주기에 따라 실행됩니다. 예정된 점검이나 의도적인 장애 구간에서는 작업을 삭제하지 말고 비활성화하세요.

8. 실행 기록 확인

실행이 끝나면 Runner의 결과가 서버로 자동 업로드됩니다.

클라이언트에서 다음 경로를 열어 실행 결과를 확인합니다.

예약 작업 → 실행 기록
Scheduled Tasks → Run History

실행 기록에서 확인할 수 있는 항목은 다음과 같습니다.

• 통과·실패 여부
• 실패한 시나리오
• 실패한 어설션
• 실행 시각
• 각 실행의 상세 결과

Slack이나 이메일 알림을 받았다면, 실행 기록에서 실패 원인과 요청·응답 컨텍스트를 확인하세요.

고급 설정

변수 공유 범위 선택

시나리오 간 데이터를 전달해야 한다면 변수 공유 범위를 적절히 설정합니다. Apidog은 다음 수준을 제공합니다.

1. 현재 테스트 시나리오 내에서만 공유
2. 현재 예약 작업의 모든 테스트 시나리오에서 공유
3. 현재 예약 작업 폴더의 모든 예약 작업에서 공유

가능한 한 가장 좁은 범위를 선택하세요.

예를 들어 가입 시나리오에서 생성한 사용자 ID를 결제 시나리오가 사용해야 한다면, 같은 예약 작업 내 공유를 사용할 수 있습니다. 반면 관련 없는 작업까지 인증 토큰이나 주문 ID를 공유하면 예상하지 못한 의존성이 생길 수 있습니다.

실행 간 변수 값 유지

실행 간에 캡처한 값을 유지하려면 테스트 시나리오 디자인 화면에서 변수 값 유지(Keep variable values) 를 활성화해야 합니다.

이 옵션이 필요한 경우는 다음과 같습니다.

• 이전 실행에서 생성한 주문 ID를 다음 실행에서도 사용해야 하는 경우
• 갱신된 토큰 값을 유지해야 하는 경우
• 실행 간 상태를 기반으로 검증해야 하는 경우

이 옵션이 비활성화되어 있으면 각 예약 실행은 새로운 상태로 시작합니다. 실행 간 데이터 의존성이 있다면 테스트가 조용히 실패할 수 있습니다.

폴더로 작업 분리

예약 작업이 늘어나면 폴더로 분리하세요.

예약 작업
├── production-monitoring
├── staging-smoke-tests
├── release-validation
└── migration-checks

폴더 단위 변수 공유 범위도 사용할 수 있으므로, 관련된 작업끼리만 공통 설정을 공유하도록 구성할 수 있습니다.

요금제 실행 한도 확인

예약 실행 가능 횟수는 구독 요금제에 따라 다릅니다. 매시간 실행처럼 공격적인 주기를 설정하기 전에 현재 플랜의 한도를 확인하세요.

더 복잡한 구성은 다음 자료를 참고할 수 있습니다.

• 고급 예약 작업
• API 테스트 시나리오의 조건부 로직
• CI의 야간 API 테스트 실행

Apidog CLI와 cron으로 자동화하기

예약 작업 UI 대신 Apidog CLI를 사용해 저장된 시나리오를 헤드리스로 실행할 수도 있습니다.

CLI 자체에는 예약 명령어가 없습니다. 스케줄링은 cron, GitHub Actions 또는 기존 CI 도구에서 처리합니다.

먼저 CLI를 설치하고 토큰으로 인증합니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

그다음 시나리오 ID와 환경 ID를 지정해 실행합니다.

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> \
  -e <ENV_ID> \
  -r cli,junit

옵션 의미는 다음과 같습니다.

옵션	설명
-t	테스트 시나리오 ID
-e	환경 ID
-r	리포터 지정

리포터는 쉼표로 구분해 여러 개를 지정할 수 있습니다.

cli
html
junit

토큰 설정과 설치 과정은 Apidog CLI 설치 가이드를 참고하세요.

cron으로 매일 새벽 2시에 실행하기

cron을 사용하는 서버라면 다음처럼 등록할 수 있습니다.

0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1

이 설정은 매일 오전 2시에 시나리오 4471을 환경 88에서 실행하고, JUnit 결과를 생성하며 로그를 run.log에 추가합니다.

GitHub Actions에서 예약 실행하기

GitHub Actions의 예약 트리거를 사용해도 됩니다. JUnit 보고서를 기존 CI 대시보드와 연동할 수 있습니다.

cron과 GitHub Actions 기반 구성은 다음 문서를 참고하세요.

• GitHub Actions schedule 트리거
• CI/CD 파이프라인의 Apidog CLI

자주 묻는 질문

Apidog Cloud에서 예약 테스트를 실행할 수 있나요?

아직은 아닙니다. Runner 대상에 Apidog Cloud가 출시 예정으로 표시되므로, 현재는 자체 호스팅 Runner를 등록하고 선택해야 합니다.

예약 작업은 얼마나 자주 실행할 수 있나요?

요금제가 허용하는 범위에서 실행할 수 있습니다. 6시간마다 또는 매주 일요일 오후 11시처럼 유연하게 설정할 수 있지만, 예약 실행 횟수는 구독에 따라 제한됩니다. 정확한 한도는 가격 페이지에서 확인하세요.

실패했을 때만 알림을 받으려면 어떻게 하나요?

작업의 알림 설정에서 모든 실행 대신 실패 시에만을 선택하고 Slack, Teams, Webhook, Jenkins 또는 Email 채널을 추가하세요.

정상적인 밤에는 채널을 조용하게 유지하면서, 실제 실패가 발생했을 때만 알림을 받을 수 있습니다. 빠른 상태 확인이 필요하다면 가벼운 API 건전성 검사와 함께 운영할 수 있습니다.

예약 실행 결과가 로컬 실행과 다른 이유는 무엇인가요?

예약 작업은 노트북이 아니라 Runner 머신에서 요청을 전송합니다. Runner의 네트워크, 리전, VPN, 방화벽, DNS 설정이 응답에 영향을 줄 수 있습니다.

이는 예상된 동작이며, 실제 서비스 환경에 더 가까운 결과를 제공하는 경우가 많습니다.

변수가 매 실행마다 초기화됩니다. 무엇을 확인해야 하나요?

테스트 시나리오 디자인 화면에서 변수 값 유지(Keep variable values) 옵션을 확인하세요.

이 옵션이 비활성화되어 있으면 모든 예약 실행이 새 상태로 시작됩니다. 실행 간 캡처 값에 의존하는 테스트라면 반드시 활성화해야 합니다.

마무리

예약 테스트는 API 상태를 추측하는 대신 지속적으로 검증하게 만듭니다.

1. 테스트 시나리오를 작성합니다.
2. 자체 호스팅 Runner를 등록합니다.
3. 실행 주기를 설정합니다.
4. 실패 알림을 Slack 또는 이메일에 연결합니다.
5. 실행 기록으로 결과를 추적합니다.

UI 기반 예약 작업이 적합하지 않거나 기존 CI에 통합해야 한다면, Apidog CLI와 cron 또는 GitHub Actions를 조합할 수 있습니다.

첫 번째 예약 회귀 테스트를 구성하려면 Apidog를 다운로드하세요. 시작은 무료이며 신용카드가 필요하지 않습니다.