불안정한 API는 누군가 테스트하는 것을 잊어서 실패하는 경우가 드뭅니다. 대신, 실행된 테스트가 잘못된 것을 확인했거나, 200 상태 코드 외에는 아무것도 확인하지 않았기 때문에 실패합니다. 잘 작성된 API 테스트 케이스는 출시 전에 깨진 계약을 포착하는 것과 사후에 서비스 중단을 설명하는 것의 차이입니다.
이 가이드에서는 API 테스트 케이스가 무엇인지, 좋은 테스트 케이스에 필요한 필드는 무엇인지, 그리고 처음부터 테스트 케이스를 작성하는 방법을 안내합니다. 로그인 엔드포인트에 대한 완전한 예시를 살펴본 다음, Apidog에서 스크립트 작성 없이 동일한 테스트를 구축하는 방법을 알아봅니다.
API 테스트 케이스는 실제로 무엇인가
API 테스트 케이스는 특정 조건에서 하나의 엔드포인트가 올바르게 작동하는지 확인하는 데 사용되는 입력, 작업 및 예상 결과의 정의된 집합입니다. 이는 테스트 시나리오보다 범위가 좁습니다. 시나리오는 "사용자 로그인 확인"이라고 말합니다. 테스트 케이스는 "유효한 자격 증명을 /auth/login으로 POST하고 800ms 이내에 본문에 JWT가 포함된 200 응답을 확인"이라고 말합니다.
각 케이스는 단일 동작을 목표로 합니다. 이러한 집중은 중요합니다. 광범위하고 다목적인 테스트가 실패할 경우, 어떤 부분이 문제인지 여전히 조사해야 합니다. 집중된 케이스가 실패하면 실패 이름이 답을 알려줍니다. 케이스가 시나리오 및 스크립트와 어떻게 관련되는지 아직 파악 중이라면, 테스트 시나리오 vs 테스트 케이스 및 테스트 케이스 vs 테스트 스크립트가 명확하게 선을 그어줍니다.
API 테스트는 일반적으로 다섯 가지 측면을 다루며, 케이스는 이 모든 측면에 걸쳐 있어야 합니다:
- 기능성(Functional): 엔드포인트가 유효한 입력에 대해 올바른 데이터를 반환하는가?
- 부정적(Negative): 잘못된 입력을 올바른 오류 및 상태 코드로 거부하는가?
- 성능(Performance): 허용 가능한 시간 예산 내에서 응답하는가?
- 보안(Security): 인증, 권한 부여 및 입력 제한을 강제하는가?
- 계약(Contract): 응답이 문서화된 스키마와 일치하는가?
해피 패스만 확인하는 테스트 스위트는 실제 사용자가 빈 비밀번호 필드를 보낼 때까지 계속 통과할 것입니다.
테스트 케이스 템플릿이 필요한 이유
빈 페이지에서 각 케이스를 작성하면 일관성 없는 커버리지가 발생합니다. 어떤 엔지니어는 예상 상태 코드를 기록하고, 다른 엔지니어는 응답 본문을 기록하며, 세 번째 엔지니어는 "작동해야 함"이라고 씁니다. 템플릿은 항상 동일한 구조를 강제함으로써 이를 해결합니다.
공유 템플릿은 네 가지 구체적인 이점을 제공합니다. 모든 케이스가 동일한 필드를 가지고 있어 누락된 부분이 명확하게 보이므로 커버리지를 감사할 수 있습니다. 새로운 테스터가 다섯 가지 형식 대신 하나의 형식을 읽기 때문에 온보딩 속도가 빨라집니다. 구조화된 케이스는 복제 및 조정이 쉽기 때문에 릴리스 간에 케이스를 재사용할 수 있습니다. 그리고 각 케이스가 요구 사항 또는 엔드포인트로 다시 연결되므로 추적성이 유지됩니다.
템플릿은 또한 자동화를 현실적으로 만듭니다. 구조화된 케이스는 자동화된 테스트 단계에 깔끔하게 매핑됩니다. 모호한 케이스는 기계가 실행하기 전에 다시 작성해야 합니다.
강력한 API 테스트 케이스의 구성 요소
완벽한 API 테스트 케이스 템플릿에는 다음 필드가 포함됩니다. 모든 케이스에 이 모든 필드가 필요한 것은 아니지만, 핵심 세트는 협상할 수 없습니다.
| 필드 | 목적 |
|---|---|
| 테스트 케이스 ID | 고유 참조, 예: AUTH-LOGIN-001 |
| 제목 | 테스트 중인 동작을 설명하는 한 줄 |
| 엔드포인트 | 메서드 및 경로, 예: POST /auth/login |
| 사전 조건 | 실행 전 필요한 상태, 예: "사용자 존재" |
| 헤더 | 필수 요청 헤더 |
| 요청 본문 / 매개변수 | 정확한 입력 페이로드 |
| 예상 상태 | 예상하는 HTTP 코드 |
| 예상 응답 | 확인할 본문 필드, 스키마 또는 값 |
| 예상 응답 시간 | 대기 시간 예산 |
| 우선순위 | 치명적, 높음, 중간, 낮음 |
| 테스트 유형 | 기능적, 부정적, 보안, 성능 |
팀에서 가장 자주 건너뛰는 필드는 예상 응답 시간과 예상 응답 본문입니다. 이를 건너뛰면 빈 페이로드와 함께 200을 반환하거나, 올바른 페이로드를 3초 늦게 반환하는 동안에도 테스트가 "통과"하게 됩니다.
API 테스트 케이스를 단계별로 작성하는 방법
먼저 API 문서를 읽으세요. 필수 매개변수, 인증 방법, 문서화된 상태 코드 및 응답 스키마를 기록하세요. 모든 테스트 케이스는 문서화된 동작에 대한 주장(claim)이므로, 문서는 진실의 원천입니다. OpenAPI 사양을 읽어 테스트 컬렉션을 생성하는 도구는 시작 스켈레톤을 제공할 수 있습니다.
테스트할 가치가 있는 조건을 나열하세요. 단일 엔드포인트의 경우 일반적으로 다음을 의미합니다: 유효한 입력, 누락된 각 필수 필드, 잘못된 형식의 각 필드, 권한 없는 요청, 만료된 토큰 및 너무 큰 페이로드. 각 조건은 하나의 케이스가 됩니다.
별도의 테스트 데이터를 준비하세요. 부정적 케이스는 정확히 한 가지 방식으로 잘못된 데이터가 필요합니다. 케이스 전체에서 동일한 페이로드를 재사용하면 한 가지 경로만 실행하므로 버그를 숨길 수 있습니다.
예상 결과를 정확하게 작성하세요. "성공을 반환한다"는 단언(assertion)이 아닙니다. "200을 반환하고, 본문에 비어 있지 않은 `token` 문자열이 포함되며, `expires_in`이 3600과 같다"가 단언입니다. 여기서 정확성이 케이스를 실행할 가치가 있게 만듭니다.
실행 가능한 스위트에 케이스를 추가하세요. 스프레드시트의 케이스는 의도를 문서화합니다. 테스트 도구의 케이스는 통과 또는 실패를 생성합니다. 관련 케이스를 그룹화하여 전체 엔드포인트가 한 번의 클릭으로 실행되도록 하세요. 테스트 스위트는 바로 이를 위해 존재합니다.
케이스를 최신 상태로 유지하세요. API가 변경될 때 케이스도 함께 변경됩니다. 오래된 스키마를 단언하는 오래된 케이스는 없는 것보다 나쁩니다. 잘못된 이유로 실패하고 팀이 빨간색 빌드를 무시하도록 훈련시키기 때문입니다.
작동 예시: 로그인 엔드포인트 테스트
표준 인증 엔드포인트를 살펴보겠습니다: POST /auth/login은 이메일과 비밀번호를 받아 JWT를 반환합니다. 다음은 이를 적절하게 다루는 네 가지 케이스입니다.
AUTH-LOGIN-001: 유효한 자격 증명 (기능적, 중요)
- 엔드포인트:
POST /auth/login - 사전 조건: 이메일
dana@example.com을 가진 사용자가 존재함 - 본문:
{"email": "dana@example.com", "password": "Correct-Horse-9"} - 예상 상태:
200 - 예상 응답: 본문에 비어 있지 않은
token(문자열),token_type이Bearer와 같음,expires_in이3600과 같음 - 예상 응답 시간: 800ms 미만
AUTH-LOGIN-002: 잘못된 비밀번호 (부정적, 중요)
- 본문:
{"email": "dana@example.com", "password": "wrong"} - 예상 상태:
401 - 예상 응답:
error가invalid_credentials와 같음;token필드 없음 - 참고: 메시지는 이메일이 존재하는지 여부를 드러내서는 안 됩니다.
AUTH-LOGIN-003: 비밀번호 필드 누락 (부정적, 높음)
- 본문:
{"email": "dana@example.com"} - 예상 상태:
400 - 예상 응답:
error가validation_error와 같음;details가password필드를 지칭함
AUTH-LOGIN-004: 잘못된 형식의 이메일 (부정적, 중간)
- 본문:
{"email": "not-an-email", "password": "Correct-Horse-9"} - 예상 상태:
400 - 예상 응답:
error가validation_error와 같음
네 가지 케이스, 하나의 엔드포인트, 그리고 이미 계약, 오류 형태, 상태 코드, 그리고 지연 시간 예산을 확인하고 있습니다. 이메일 필드에 SQL-인젝션 문자열에 대한 보안 케이스를 추가하면 모든 커밋에서 실행할 가치가 있는 스위트가 됩니다.
Apidog에서 동일한 테스트 케이스 작성하기
위의 네 가지 케이스를 한 줄의 스크립트도 작성하지 않고 실행할 수 있습니다. Apidog에서는 API 테스트 케이스가 시각적으로 구축됩니다.
- 엔드포인트 가져오기 또는 정의. OpenAPI 파일, Postman 컬렉션에서
POST /auth/login을 가져오거나 직접 정의합니다. 요청 스키마는 모든 단언의 기초가 됩니다. - 요청 데이터 추가. AUTH-LOGIN-001 케이스에 대한 본문을 입력합니다. 데이터 기반 커버리지를 위해 CSV 또는 JSON 파일을 첨부하여 하나의 케이스가 모든 자격 증명 행에 대해 실행되도록 합니다. 이것이 데이터 기반 API 테스트가 거의 동일한 네 가지 케이스를 하나로 대체하는 방법입니다.
- 단언을 시각적으로 설정. 클릭하여 상태가 200과 같고,
token이 존재하며 비어 있지 않은 문자열이고,expires_in이 3600과 같고, 응답 시간이 800ms 미만인지 단언합니다. 스크립트가 필요 없습니다. - 케이스를 테스트 시나리오로 그룹화. 모든 네 가지 로그인 케이스를 하나의 시나리오에 추가하여 엔드포인트를 단일 실행으로 완전히 실행합니다.
- 보고서 실행 및 읽기. Apidog는 시나리오를 실행하고, 케이스별 통과/실패 보고서를 생성하며, 문제가 발생한 정확한 단언을 표시합니다. 시나리오를 로컬에서, 스케줄에 따라 또는 CI 내에서 실행할 수 있습니다.
스크립트 작성이 잘못되었다는 것이 아닙니다. 구조화된 시각적 케이스가 더 빠르게 작성되고, 검토하기 쉽고, 미묘하게 잘못될 가능성이 적다는 것입니다. 코드가 필요할 때도 Apidog는 사용자 지정 스크립트를 작성할 수 있도록 합니다. 완전히 스크립트 없는 워크플로의 경우, Postman 없이 API 테스트하기는 더 광범위한 접근 방식을 다룹니다.
피해야 할 일반적인 실수
상태 코드만 단언. 200은 요청이 처리되었음을 의미하지만 응답이 올바르다는 것을 의미하지는 않습니다. 항상 본문 필드를 단언하세요.
엔드포인트당 하나의 거대한 케이스. 실패할 경우 아무것도 배우지 못합니다. 조건별로 분할하세요.
재사용된 테스트 데이터. 모든 부정적 케이스가 동일한 페이로드를 보내면 하나의 실패 모드만 테스트하게 됩니다.
지연 시간 단언 없음. 응답 시간을 측정하는 것이 없으면 성능 저하가 조용히 지나갑니다.
자동화되지 않는 케이스. 어떤 실행기도 실행하지 않는 문서화된 케이스는 테스트가 아니라 주석입니다. 모든 빌드에서 실행되는 스위트 안에 케이스를 이동하세요. OpenAPI 사양에서 테스트 스크립트 생성은 해당 스위트를 빠르게 부트스트랩하는 방법입니다.
예시를 따라 네 가지 로그인 케이스를 직접 구축하고 싶다면 Apidog를 다운로드하세요.
자주 묻는 질문
하나의 엔드포인트에 몇 개의 테스트 케이스가 필요한가요? 해피 패스, 모든 필수 필드 실패, 하나의 인증 실패, 그리고 하나의 보안 탐색을 다루기에 충분해야 합니다. 간단한 엔드포인트의 경우 4~6개의 케이스; 복잡한 엔드포인트의 경우 더 많을 수 있습니다.
API가 구축되기 전에 케이스를 작성해야 하나요? 네. 설계에 따라 케이스를 작성하는 "설계 우선" 방식은 계약의 누락 부분을 일찍 발견합니다. 이를 AI 기반 테스트 케이스 생성과 결합하여 첫 번째 세트를 빠르게 초안하고 수동으로 다듬으세요.
케이스 저장을 위한 스프레드시트 또는 테스트 도구? 스프레드시트는 의도를 문서화하지만 실행할 수는 없습니다. 케이스는 항상 녹색이거나 빨간색이 되도록 실행하고 결과를 보고하는 도구에 보관하세요.
테스트 케이스와 테스트 시나리오의 차이점은 무엇인가요? 시나리오는 상위 수준의 목표("로그인 확인")이고, 케이스는 그 안의 구체적이고 실행 가능한 하나의 확인입니다. 테스트 시나리오 vs 테스트 케이스를 참조하세요.