무엇을 검증하는가
계약이 곧 케이스가 됩니다.
엔드포인트마다 기대 응답을 케이스로 적고, 실제 응답과 비교합니다. 성공 경로만 보지 않습니다. 거절해야 할 요청이 실제로 거절되는지, 다른 사용자의 주문을 조회하는 요청이 실제로 차단되는지까지 같은 실행에서 확인합니다.
- 응답 스키마 — 필드, 타입, 필수값이 계약과 같은지 비교합니다.
- 상태 코드 — 24시간 취소 규칙을 넘긴 요청이 409로 돌아오는지처럼, 성공·거절·충돌 코드를 규칙대로 확인합니다.
- 권한 — 다른 사용자, 다른 역할의 요청이 403으로 막히는지 봅니다.
케이스와 실행
케이스는 세 곳에서 옵니다.
API 케이스도 UI 케이스와 같은 방식으로 만듭니다. 요구사항 문서와 저장소 코드에서 초안을 만들고, 담당자가 직접 쓴 케이스를 더합니다. PR이 열리면 바뀐 엔드포인트에 맞는 신규·수정·삭제 케이스를 제안하고, 승인된 것만 세트에 들어갑니다.
- 문서 기반 — 기능 목록과 요구사항에서 엔드포인트별 입력값과 기대 결과를 뽑습니다.
- 코드 기반 — 라우트, 핸들러, 입력 검증 로직에서 오류 경로와 경계값을 끌어냅니다.
- PR 제안 — 변경 내용을 읽어 케이스를 제안하고 담당자가 승인하거나 거절합니다.
- 자동 실행 규칙 — 저장소 · 브랜치 · 변경 경로 패턴을 정해 push와 PR마다 실행합니다.
결과와 판정
실패한 호출에는 요청과 응답이 남습니다.
실패한 케이스마다 보낸 요청, 받은 응답, 실행 로그가 붙습니다. 결제 API가 상한 초과 안내를 빠뜨렸다면 어느 필드가 비었는지까지 보입니다. 심각도가 릴리스 판정을 정합니다.
- 치명·주요 실패가 하나라도 있으면 FAIL입니다.
- 경미·사소 실패만 있으면 CONDITIONAL, 사람이 보고 결정합니다.
- 같은 커밋에서 결과가 뒤집히는 검증은 격리됩니다. 계속 실행되지만 판정을 FAIL로 만들지 못하고, 그 실행은 CONDITIONAL이 됩니다.
- 실패는 Jira 이슈로 자동 발행되고, 재검증 결과와 연결됩니다.
검증 항목
한 번의 실행에서 확인하는 것.
케이스마다 검증 항목을 조합해 기대 결과를 적습니다. 하나라도 어긋나면 그 케이스는 실패로 기록됩니다.
응답 스키마
필드 이름, 타입, 필수 여부, 중첩 구조가 계약과 일치하는지 비교합니다.
상태 코드
200·201·400·403·409처럼 상황별로 정해진 코드가 실제로 돌아오는지 확인합니다.
권한·역할
등록한 테스트 계정으로 호출해, 허용되지 않은 역할의 요청이 차단되는지 봅니다.
오류 메시지
거절 응답에 사유와 안내 문구가 빠지지 않았는지 확인합니다.
데이터 무결성
생성한 뒤 조회했을 때 같은 값이 돌아오는지, 취소 뒤 상태가 바뀌는지 이어서 검증합니다.
CI 파이프라인 실행
GitHub Actions 워크플로 단계로 실행해 PR마다 결과를 받습니다.
API 명세 연동 미리보기
OpenAPI 명세를 등록하면 엔드포인트 목록과 스키마가 케이스 초안에 바로 쓰입니다.
릴리스 게이팅 미리보기
판정이 FAIL이면 PR 체크를 실패시키거나 배포를 막습니다.
자주 묻는 질문
API 검증 도입 전에 확인할 것
화면이 없는 서버·API 프로젝트만 있어도 쓸 수 있나요?
OpenAPI 명세가 꼭 있어야 하나요?
이미 있는 단위 테스트나 CI 파이프라인을 대체하나요?
운영 데이터에 접근하나요?
사람은 어떤 일을 하나요?
UI 검증 결과와 따로 보나요?
엔드포인트 하나부터 시작합니다.
저장소와 대상 URL을 연결한 뒤 보통 5분이면 첫 실행까지 갑니다. 데모에서 API 계약 검증 결과가 릴리스 판정으로 이어지는 과정을 봅니다.
sales@qoretix.com+82-33-242-0210평일 10:00 – 18:00 KST