대부분의 API 버그는 특이한 것이 아닙니다. 누락된 필드, 잘못된 상태 코드, 부하 시 타임아웃, 또는 아무도 계약을 확인하지 않아 발생한 호환성을 깨는 변경 등이 그렇습니다. 즉흥적인 테스트는 이러한 문제 중 일부를 우연히 발견하지만, 전략은 의도적으로 이를 잡아냅니다.
API 테스트 전략은 무엇을, 어떤 계층에서, 배포 주기 중 언제 테스트할지에 대한 계획입니다. 이는 어떤 검사가 모든 커밋에서 실행되고, 어떤 검사가 매일 밤 실행되며, 어떤 검사가 릴리스 전에 실행될지 결정합니다. 또한 최소한의 유지보수로 최대의 커버리지를 얻기 위해 노력을 어디에 기울여야 하는지 알려줍니다.
API 테스트 전략이 실제로 의미하는 것
전략은 단 하나의 단언문(assertion)을 작성하기 전에 네 가지 질문에 답합니다.
무엇을 테스트할 것인가? 비즈니스 가치를 지니는 엔드포인트와 흐름. 결제 API는 헬스체크 엔드포인트보다 더 많은 커버리지가 필요합니다. 엔드포인트에 접근하기 쉬운 정도가 아니라 위험도와 트래픽으로 순위를 매기세요.
어떤 계층에서? 일부 검사는 단일 요청에 속합니다. 다른 것들은 두세 개의 서비스가 서로 통신해야 합니다. 모든 검사를 최상위 계층에 두면 테스트 스위트가 느리고 깨지기 쉽습니다.
언제 실행되는가? 빠른 검사는 모든 푸시에서 실행됩니다. 느린 검사는 정해진 일정에 따라 또는 릴리스 전에 실행됩니다. 이 둘을 혼합하면 피드백이 느리거나 커버리지가 얇아집니다.
무엇이 통과로 간주되는가? 200 응답만 확인하는 테스트는 거의 아무것도 알려주지 않습니다. 상태 코드, 스키마, 필드 값, 그리고 예상 응답 시간을 정의하세요.
API에 대한 이 네 가지 질문에 답할 수 있다면, 당신은 전략을 가지고 있는 것입니다. 이 가이드의 나머지 부분에서 세부 사항을 채울 것입니다.
전략이 즉흥적인 테스트를 능가하는 이유
즉흥적인 테스트는 요청을 보내고, 응답을 눈으로 확인하고, 다음으로 넘어가는 것을 의미합니다. 이는 데모에서는 작동하지만, 실제 서비스에서는 세 가지 이유로 무너집니다.
반복되지 않습니다. 다음 사람은 당신의 수동 검사를 다시 실행할 수 없으므로, 회귀가 다시 발생합니다. 저장되고 자동화된 테스트는 매번 동일하게 실행됩니다.
해피 패스(정상적인 흐름) 쪽으로 치우칩니다. 수동으로 테스트할 때, 당신은 작동할 것이라고 예상하는 것을 테스트합니다. 잘못된 페이로드, 만료된 토큰, 또는 10,000개 항목 목록을 보내는 경우는 거의 없습니다. 이러한 경우들이 프로덕션에서 문제를 일으킵니다.
확장되지 않습니다. 40개의 엔드포인트와 5개의 환경을 가진 서비스는 릴리스당 200개의 수동 검사를 의미합니다. 아무도 그것을 수동으로 하지 않으므로, API가 성장함에 따라 커버리지가 줄어듭니다. 전략은 반복 가능한 커버리지를 위해 일회성 설정 비용을 지불하는 것입니다. 즉, 테스트를 한 번 작성하면 당신 없이 모든 변경사항에 대해 실행됩니다.
API 테스트 피라미드
테스트 피라미드는 각 계층에서 얼마나 많은 테스트를 작성해야 하는지에 대한 경험 법칙입니다. 바닥은 넓고, 위는 좁습니다.
/\
/ \ 엔드투엔드 / 워크플로우 테스트 (적고, 느리며, 높은 가치)
/----\
/ \ 통합 / 계약 테스트 (일부, 중간 속도)
/--------\
/ \ 유닛 / 단일 요청 테스트 (많고, 빠르며, 저렴함)
/____________\
최하위 계층: 단일 요청 검사. 각 테스트는 하나의 엔드포인트에 접근하고 응답을 단언합니다. 이는 빠르고, 작성 비용이 저렴하며, 디버깅하기 쉽습니다. 하나가 실패하면 정확히 어떤 엔드포인트가 고장 났는지 알 수 있습니다. 대부분의 테스트가 여기에 속합니다.
중간 계층: 통합 및 계약 검사. 이는 서비스들이 교환하는 데이터의 형태에 동의하는지, 그리고 두세 개의 시스템을 거치는 요청이 올바른 결과를 반환하는지 확인합니다. 더 많은 움직이는 부품을 포함하기 때문에 느리지만, 단일 요청 테스트가 놓치는 오류를 잡아냅니다.
최상위 계층: 엔드투엔드 워크플로우. 이는 여러 엔드포인트에 걸친 전체 사용자 여정(주문 생성, 결제, 상태 확인)을 실행합니다. 가장 큰 신뢰를 주지만 유지보수 비용이 가장 많이 들므로, 수를 적게 유지하고 중요 경로에만 사용하세요.
팀들이 저지르는 실수는 피라미드를 뒤집는 것입니다. 즉, 느린 엔드투엔드 테스트는 많고 빠른 테스트는 거의 없는 것입니다. 이는 긴 피드백 루프와 불안정한 오류를 초래합니다. 하위 계층에서 동일한 버그를 잡을 수 있을 때마다 커버리지를 피라미드 아래로 내리세요.
테스트 유형 및 각 유형이 적용되는 시기
완전한 전략은 여러 테스트 유형을 사용하며, 각 유형은 각기 다른 종류의 오류를 목표로 합니다. 다음은 각 유형이 무엇을 확인하고 언제 사용해야 하는지에 대한 설명입니다.
기능 테스트
기능 테스트는 엔드포인트가 사양에 명시된 대로 작동하는지 확인합니다. 유효한 요청을 보내고, 상태 코드, 응답 스키마, 필드 값을 단언합니다. 이는 테스트 스위트의 기반이며 새로운 엔드포인트에서 가장 먼저 자동화해야 할 것입니다. 심층적인 설명은 API 기능 테스트를 참조하세요.
사용자 엔드포인트에 대한 기능 검사는 다음과 같습니다.
GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
단언문:
- 상태는
200. - 바디는
User스키마와 일치. id는42.email은 유효한 이메일 문자열.
통합 테스트
통합 테스트는 엔드포인트들이 함께 작동하는지, 그리고 API가 종속성(데이터베이스, 결제 제공업체, 다운스트림 서비스)과 올바르게 통신하는지 확인합니다. 기능 테스트는 모의(mocked) 종속성에서는 통과하지만 실제 종속성이 연결되면 여전히 실패할 수 있습니다. 통합 테스트는 그 격차를 메웁니다. 전체 방법은 API 통합 테스트에 설명되어 있습니다.
회귀 테스트
회귀 테스트는 모든 변경 후 기존 스위트를 다시 실행하여 이전에 작동하던 것을 손상시키지 않았음을 확인합니다. 이것이 저장되고 자동화된 스위트가 그 가치를 발휘하는 곳입니다. 새로운 회귀 테스트를 작성하는 것이 아니라, 이미 가지고 있는 테스트를 일정에 따라 그리고 릴리스 전에 실행하는 것입니다. 이를 구성하는 방법은 회귀 테스트를 참조하세요.
계약 테스트
계약 테스트는 API의 제공자와 소비자가 정확한 요청 및 응답 형태에 동의하는지 확인합니다. 이는 파괴적 변경(필드 이름 변경, 타입 변경, 제거된 엔드포인트)이 소비자에 도달하기 전에 잡아냅니다. 다른 팀이나 고객이 의존하는 API를 발행하는 경우, 계약 테스트는 선택 사항이 아닙니다. 자세한 내용은 API 계약 테스트에 있습니다.
부하 및 성능 테스트
부하 테스트는 동시 트래픽 하에서 API가 어떻게 동작하는지 측정합니다. 95번째 백분위수 응답 시간, 오류율, 처리량, 그리고 성능이 저하되는 지점 등을 확인합니다. 출시 전, 예상되는 트래픽 급증 전, 그리고 느린 성능 저하를 감지하기 위해 주기적으로 실행하세요. 이는 기능 테스트와는 별개의 분야이며 다른 도구를 사용합니다. 옵션은 부하 테스트 도구를 참조하세요.
보안 테스트
보안 테스트는 API가 거부해야 할 것을 거부하는지 확인합니다. 토큰 없는 요청, 잘못된 스코프의 요청, 주입 시도, 다른 사용자 데이터에 대한 접근 등이 해당됩니다. 민감한 데이터에 접근하는 모든 엔드포인트는 최소한 인증 및 권한 부여 검사가 필요합니다. 전체 기술 세트는 API 보안 테스트에 있습니다.
다음은 각 유형이 언제 실행되는지에 대한 대략적인 가이드입니다.
| 테스트 유형 | 감지하는 것 | 실행 시기 |
|---|---|---|
| 기능 | 잘못된 상태, 스키마 또는 값 | 모든 커밋 |
| 통합 | 손상된 서비스 간 흐름 | 모든 커밋 또는 매일 밤 |
| 회귀 | 새로 손상된 기존 동작 | 모든 커밋 및 릴리스 전 |
| 계약 | 인터페이스에 대한 파괴적 변경 | 제공자의 모든 커밋 |
| 부하 | 트래픽 하에서의 느려짐 및 실패 | 출시 전 및 예정된 일정 |
| 보안 | 인증, 주입, 데이터 노출 | 릴리스 전 및 예정된 일정 |
긍정, 부정 및 엣지 케이스
각 엔드포인트에 대해 세 가지 종류의 입력을 다루세요. 두 번째와 세 번째를 건너뛰는 것이 실제 스위트에서 가장 흔한 공백입니다.
긍정 케이스는 유효한 입력을 보내고 성공을 기대합니다. 잘 구성된 바디를 가진 사용자 생성 요청은 201과 새 레코드를 반환합니다. 이는 엔드포인트가 작동함을 확인합니다.
부정 케이스는 유효하지 않은 입력을 보내고 깔끔하고 정확한 실패를 기대합니다. 필수 필드가 누락된 경우 500이 아닌 400을 반환해야 합니다. 토큰 없는 요청은 401을 반환해야 합니다. 소유하지 않은 레코드에 대한 요청은 레코드를 반환하지 않고 403 또는 404를 반환해야 합니다. 부정 테스트는 오류 처리를 확인하며, 이는 API가 가장 자주 정보 누출되거나 충돌하는 지점입니다.
엣지 케이스는 유효한 입력의 경계를 밀어붙입니다. 빈 목록, 허용되는 최대 문자열 길이, 0, 음수, 유니코드 이름, 일광 절약 시간 경계의 타임스탬프 등이 있습니다. 이는 Off-by-one 및 오버플로 버그를 찾아냅니다.
확고한 규칙: 모든 긍정 테스트에 대해 최소한 하나의 부정 테스트를 작성하세요. 주문 생성 엔드포인트에 해피 패스 테스트는 하나 있고 음수 수량 또는 누락된 고객 ID에 대한 테스트가 없는 경우, 커버리지는 보이는 것보다 얇습니다.
POST /api/orders HTTP/1.1
Content-Type: application/json
{ "customerId": "c_123", "quantity": -5 }
예상: 상태 400, 바디에 quantity를 명시하는 명확한 유효성 검사 오류 포함. 만약 201 또는 500을 반환한다면, 해피 패스 테스트로는 절대 잡을 수 없는 버그를 발견한 것입니다.
테스트 데이터 및 환경
테스트는 그것이 실행되는 데이터와 환경만큼만 신뢰할 수 있습니다.
전용 테스트 데이터를 사용하라. 프로덕션 레코드를 대상으로 테스트하지 마세요. 특정 행이 존재한다고 가정하지 마세요. 테스트에 필요한 데이터를 생성하거나, 실행 시작 시 알려진 픽스처를 시드(seed)하세요. 현실적이고 다양한 입력을 위해 데이터 생성기는 시간을 절약해줍니다. 현실적인 API 테스트 데이터 생성 방법을 참조하세요.
테스트를 독립적으로 만들라. 각 테스트는 자체 상태를 설정하고 스스로 정리해야 합니다. 이전 테스트가 실행된 것에 의존하는 테스트는 무작위 순서로 실패하는 테스트입니다. 한 요청에서 다음 요청으로 값을 전달해야 할 때(ID, 토큰 등)는 공유 전역 상태를 통하지 않고 시나리오 내에서 명시적으로 하세요.
환경을 격리하라. 로컬 개발, CI, 스테이징, 프로덕션용으로 별도의 환경을 유지하세요. 환경별로 기본 URL, 토큰 및 기타 설정을 저장하여 변수 하나를 바꿔서 동일한 테스트가 어디서든 실행되도록 하세요. 샌드박스와 전체 테스트 환경의 차이를 이해하는 것이 올바른 대상을 선택하는 데 도움이 됩니다. 샌드박스 대 테스트 환경을 참조하세요.
변수로 매개변수화하라. 테스트에서 호스트나 비밀값을 하드코딩하지 마세요. 환경 변수를 참조하여 동일한 시나리오가 수정 없이 로컬, 스테이징, CI에서 실행되도록 하세요.
쉬프트 레프트: 더 많이 뿐만 아니라 더 일찍 테스트하라
쉬프트 레프트는 배포 주기에서 테스트를 더 일찍, 코드가 작성되는 순간에 더 가깝게 이동하는 것을 의미합니다. 버그가 늦게 발견될수록 수정 비용이 더 많이 듭니다. 설계 시점에 발견된 스키마 불일치는 5분짜리 수정 사항입니다. 프로덕션에서 발견된 동일한 불일치는 사고(incident)입니다.
세 가지 실질적인 움직임이 테스트를 왼쪽으로 이동시킵니다.
계약을 먼저 설계하라. 엔드포인트를 구축하기 전에 API의 요청 및 응답 스키마를 정의하세요. 이제 해당 계약에서 테스트와 모의(mock)를 생성할 수 있으며, 구현이 존재하기 전에 인터페이스 테스트를 시작할 수 있습니다.
백엔드가 미완성일 때 모의를 대상으로 테스트하라. 프론트엔드 및 통합 작업이 실제 엔드포인트를 기다릴 필요가 없습니다. 스키마로 구축된 모의 서버는 소비자가 자신의 측면을 병렬로 테스트할 수 있도록 합니다.
모든 커밋에서 빠른 검사를 실행하라. 몇 초 안에 실행되는 기능 및 계약 테스트는 야간 배치 작업이 아니라 개발자의 내부 루프에 속해야 합니다. 개발자가 빨간색 테스트를 빨리 볼수록 수정 비용이 저렴해집니다.
이에 대한 전체 설명은 API 개발의 쉬프트 레프트 테스트에 있습니다. 보상은 간단합니다. 버그를 더 빨리 찾을수록 비용이 적게 듭니다.
CI에서 테스트 자동화
전략은 당신 없이 실행될 때만 실제적입니다. 목표는 모든 푸시에서 테스트 스위트를 실행하고, 실패 시 병합을 차단하며, 읽을 수 있는 보고서를 생성하는 파이프라인입니다.
API 테스트를 위한 일반적인 CI 파이프라인은 세 단계로 구성됩니다.
- 모든 푸시에서: 빠른 기능 및 계약 테스트를 실행하세요. 단언문이 실패하면 빌드를 실패 처리하세요. 이것이 당신의 게이트입니다.
- 매일 밤 또는 릴리스 전: 느린 통합 및 엔드투엔드 스위트, 그리고 부하 및 보안 검사를 실행하세요.
- 항상: 기계가 읽을 수 있는 보고서(JUnit XML이 일반적인 형식)를 발행하여 CI 대시보드에 통과 및 실패 횟수가 표시되도록 하세요.
모든 푸시에서 API 테스트 스위트를 실행하는 최소한의 GitHub Actions 작업은 다음과 같습니다.
name: api-tests
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Run API tests
run: npm test
정확한 명령은 당신의 도구에 따라 달라집니다. 패턴은 어디에서나 동일합니다. 코드를 체크아웃하고, 런타임을 설정하고, 스위트를 실행하며, 0이 아닌 종료 코드가 빌드를 실패 처리하도록 합니다. 캐싱, 환경 비밀, 보고를 포함한 전체 CI 처리는 CI/CD에서 API 테스트 자동화 방법을 참조하세요.
Apidog이 전략에 어떻게 부합하는가
위의 전략은 도구에 구애받지 않습니다. 설계, 테스트, 모의, 문서화를 위한 별도의 도구들로 이를 구성할 수 있습니다. 그 비용은 불일치입니다. 즉, 사양, 테스트, 모의가 동기화되지 않아 그것들을 조정하는 데 시간을 보냅니다.
Apidog은 그것을 한 곳으로 압축합니다. 당신은 API 계약을 설계하고, 그것을 대상으로 테스트 시나리오를 작성하고, 동일한 스키마에서 모의를 생성하고, 문서를 발행합니다. 이 모든 것이 단일 진실의 원천으로부터 이루어집니다. 테스트와 모의가 동일한 계약에서 나오기 때문에, 계약 테스트와 쉬프트 레프트 테스트는 추가적인 작업이 아니라 기본값이 됩니다.
전략의 CI 부분에 대해 Apidog CLI는 저장된 테스트 시나리오와 스위트를 헤드리스(UI 없이)로 실행합니다. 이는 Node 패키지이므로, Node를 실행할 수 있는 모든 CI 단계에 쉽게 통합됩니다.
설치:
npm install -g apidog-cli
CI에서 저장된 시나리오 또는 스위트를 실행하세요. 실행 명령은 플래그 기반입니다. 대상 ID, 환경 ID, 그리고 원하는 리포터를 전달합니다.
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
--access-token은 실행을 인증합니다. 토큰을 CI 비밀로 저장하고 환경 변수로 참조하세요.-t는 실행하려는 시나리오, 폴더 또는 스위트의 ID입니다.-e는 환경 ID이므로, 이 값을 변경하여 동일한 스위트를 스테이징 또는 CI에서 실행할 수 있습니다.-r은cli,html,json,junit중에서 하나 이상의 리포터를 선택합니다.junit출력은 CI 대시보드에 공급되며,html은 사람이 읽을 수 있는 보고서를 제공합니다.
데이터 기반 실행을 위해 CLI를 데이터 파일 또는 저장된 테스트 데이터 ID로 지정하세요.
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioId> \
-e <environmentId> \
-d ./data/users.csv \
-r cli,junit
보고서를 클라우드로 푸시하려면 --upload-report를 추가하거나, 특정 브랜치를 대상으로 실행하려면 --branch를 사용하세요. CLI는 저장된 Apidog 시나리오와 스위트를 실행합니다. 이는 대화형 요청 발송기나 부하 생성기가 아니므로, 피라미드의 성능 계층을 위해 전용 부하 도구와 함께 사용하세요.
시작 전략 체크리스트
처음부터 전략을 구축하는 경우, 다음 목록을 순서대로 진행하세요.
- [ ] 위험도와 트래픽으로 엔드포인트 순위를 매기세요. 상위 엔드포인트를 먼저 다루세요.
- [ ] 각 순위가 매겨진 엔드포인트에 대해 긍정적인 기능 테스트를 작성하세요.
- [ ] 엔드포인트당 최소한 하나의 부정 테스트를 추가하세요 (인증 누락, 유효하지 않은 입력).
- [ ] 목록, 숫자 또는 자유 텍스트를 받는 엔드포인트에 대해 엣지 케이스 테스트를 추가하세요.
- [ ] 다른 팀이나 고객이 사용하는 API에 대해 계약 테스트를 추가하세요.
- [ ] 두 개 이상의 서비스를 거치는 흐름에 대해 통합 테스트를 추가하세요.
- [ ] 환경별 변수와 비밀값을 사용하여 별도의 환경을 설정하세요.
- [ ] 생성되거나 시드된 테스트 데이터를 사용하세요; 테스트를 독립적으로 유지하세요.
- [ ] CI에서 모든 푸시에서 빠른 테스트를 실행하세요; 실패 시 빌드를 실패 처리하세요.
- [ ] 느린 스위트(통합, 부하, 보안)를 매일 밤 또는 릴리스 전에 예약하세요.
- [ ] JUnit 보고서를 발행하여 통과 및 실패 횟수가 보이도록 하세요.
- [ ] API 변경 시 스위트를 검토하세요; 제거된 엔드포인트에 대한 테스트는 삭제하세요.
첫날부터 모든 것을 다 할 필요는 없습니다. 가장 위험한 엔드포인트에 대한 기능 및 부정 테스트부터 시작하고, 그것들을 CI에서 실행하며, 거기서부터 스위트를 확장하세요.
FAQ
API 테스트 전략과 테스트 계획의 차이점은 무엇인가요?
전략은 상위 수준의 접근 방식입니다. 어떤 테스트 유형을 사용하고, 어떤 계층에서, 언제 실행하는지에 대한 것입니다. 테스트 계획은 특정 릴리스 또는 기능에 대한 구체적인 문서입니다. 즉, 정확한 엔드포인트, 케이스, 데이터 및 통과 기준을 명시합니다. 전략은 안정적이며, 계획은 릴리스마다 변경됩니다.
피라미드의 각 계층에는 얼마나 많은 테스트가 있어야 하나요?
정해진 비율은 없지만, 숫자보다 모양이 더 중요합니다. 대부분의 테스트는 하단의 빠른 단일 요청 검사여야 하며, 중간에는 더 적은 통합 및 계약 테스트가, 최상단에는 소수의 엔드투엔드 워크플로우 테스트만 있어야 합니다. 느린 최상위 계층 테스트가 빠른 최하위 계층 테스트보다 많다면, 균형을 재조정하세요.
기능 테스트가 이미 있다면 계약 테스트도 필요한가요?
네, 다른 팀이나 고객이 당신의 API를 사용하는 경우라면 필요합니다. 기능 테스트는 엔드포인트가 올바르게 작동하는지 확인합니다. 계약 테스트는 인터페이스가 소비자에게 호환성을 깨는 방식으로 변경되지 않았는지 확인합니다. 변경은 엔드포인트가 계속 작동하도록 유지하면서도, 그것을 호출하는 모든 사람에게 문제를 일으킬 수 있습니다.
부하 테스트는 얼마나 자주 실행해야 하나요?
모든 출시 또는 예상되는 트래픽 급증 전에 실행하고, 성능 저하를 감지하기 위해 일정에 따라 (매주 또는 매월) 실행하세요. 부하 테스트는 느리고 자원 소모가 많으므로, 모든 커밋에 포함되지 않습니다. 빠른 계층은 CI에 유지하고 부하는 별도로 실행하세요.
전체 전략을 CI에서 자동화할 수 있나요?
반복 가능한 부분은 그렇습니다. 기능, 통합, 계약, 회귀 테스트는 파이프라인에서 깔끔하게 실행되고 병합을 통제합니다. 부하 및 보안 테스트는 느리거나 전용 인프라가 필요하기 때문에 종종 자체 일정에 따라 실행됩니다. Apidog CLI와 같은 헤드리스 테스트 러너는 모든 푸시에서 저장된 시나리오를 실행하여 CI 부분을 처리합니다.