OpenAPI 또는 GraphQL 스키마가 있다면 Schemathesis는 단 하나의 어설션도 작성하지 않고 수천 개의 테스트 케이스로 변환할 수 있습니다. Schemathesis는 사양을 읽고, 예상치 못한 유효한 입력을 생성하며, 이를 API에 전송하고, 응답이 계약을 위반하는 지점을 보고합니다. 이 가이드에서는 Schemathesis가 무엇인지, 설치 및 실행 방법, 속성 기반 테스팅이 실제로 의미하는 바, 그리고 Apidog의 기능 및 계약 테스트 워크플로와 어떻게 조화를 이루는지 설명합니다.
Schemathesis란 무엇인가요?
Schemathesis는 스키마에서 API 테스트를 자동으로 생성하는 오픈 소스 Python 도구입니다. OpenAPI 또는 GraphQL 정의를 지정하면, 이미 선언한 유형, 형식 및 제약 조건에서 테스트 케이스를 구축합니다. 이는 Python용 속성 기반 테스팅 라이브러리인 Hypothesis를 기반으로 구축되었으며, MIT 라이선스에 따라 배포됩니다.
핵심 아이디어는 간단합니다. 여러분의 사양은 이미 유효한 요청과 응답이 어떻게 생겼는지 설명합니다. Schemathesis는 그 설명을 진리의 원천으로 삼아 실행 중인 API가 실제로 이를 준수하는지 확인합니다. API가 500을 반환하거나, 선언된 스키마를 위반하는 응답을 보내거나, 거부해야 할 입력을 수락하는 경우 Schemathesis는 이를 표시합니다.
명령줄에서 schemathesis run (또는 단축 별칭 st run)으로 실행할 수 있습니다. CLI 대신 pytest에서 실행하려는 경우 Python 통합 기능도 있습니다. 대부분의 팀은 설정이 거의 필요 없기 때문에 CLI로 시작합니다.
속성 기반 테스팅의 의미
대부분의 API 테스트는 예제 기반입니다. 요청을 작성하고, 특정 응답을 어설션하며, 해당 단일 케이스에 따라 테스트가 통과하거나 실패합니다. 이는 유용하지만, 테스트를 작성하려고 생각했던 버그만 잡을 수 있습니다.
속성 기반 테스팅은 접근 방식을 뒤집습니다. 하나의 고정된 예시 대신, 항상 유지되어야 하는 속성을 설명한 다음, 도구가 수백 가지 입력을 생성하여 해당 속성을 깨뜨리려고 시도하게 합니다. Schemathesis의 경우, 속성은 대략적으로 다음과 같습니다: "어떤 유효한 요청도 서버를 충돌시키거나 스키마를 위반하는 응답을 생성해서는 안 됩니다."
Schemathesis는 사양의 제약 조건에서 입력을 생성합니다. 필드가 최소값이 1인 정수라면, 1, 큰 숫자, 경계 값, 그리고 기본적인 유효성 검사를 방해하는 종류의 입력을 시도합니다. 테스트가 실패하면 Hypothesis는 버그를 재현하는 가장 작은 사례로 입력을 축소하므로, 4KB의 무작위 페이로드 대신 최소한의 읽기 쉬운 재현을 얻을 수 있습니다.
이는 인터페이스에 무작위 입력을 던져서 무엇이 넘어지는지 확인하는 몽키 테스팅과는 다릅니다. 속성 기반 테스팅은 구조화되어 있습니다. 스키마를 사용하여 그럴듯하고 목표 지향적인 입력을 생성하며, 사양이 알려주었기 때문에 올바른 결과가 무엇인지 알고 있습니다.
Schemathesis 설치 및 실행
Schemathesis는 Python 패키지이므로 Python 3와 pip가 필요합니다. 다음 일반적인 방법으로 설치하세요:
pip install schemathesis
uv가 설정되어 있다면 uvx schemathesis를 사용하여 영구 설치 없이 실행할 수도 있습니다. 설치가 완료되면, 기본 명령은 스키마와 기본 URL을 가리킵니다:
st run http://127.0.0.1:8000/openapi.json
스키마가 URL 뒤가 아닌 디스크에 있다면, 파일 경로를 전달하고 Schemathesis에 실제 API가 어디에 있는지 알려주세요:
st run ./openapi.yaml --url http://127.0.0.1:8000
인증된 API의 경우, 헤더를 추가합니다:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis는 사양의 모든 작업을 발견하고, 각 작업에 대한 케이스를 생성하며, 어떤 검사가 통과했고 어떤 검사가 실패했는지 요약을 출력합니다. 실패 시에는 전송된 정확한 요청이 함께 제공되므로, 이를 curl이나 다른 API 클라이언트에서 다시 실행할 수 있습니다. 주요 버전 간에 플래그 이름과 기본값이 변경될 수 있으므로, 이 블로그 스니펫을 포함하여 어떤 블로그 스니펫도 맹신하지 말고 설치된 버전에 대해 st run --help를 확인하세요.
Schemathesis가 찾아내는 것
기본 검사는 사양이 약속하는 것과 서버가 수행하는 것 사이의 격차를 목표로 합니다. 다음은 주로 발견되는 사항입니다.
| 문제 | 내용 |
|---|---|
| 서버 오류 | 요청이 처리된 4xx 또는 유효한 응답 대신 500을 트리거할 때 |
| 스키마 위반 | 응답 본문이 해당 상태 코드에 대해 선언한 스키마와 일치하지 않을 때 |
| 상태 코드 불일치 | API가 사양에 문서화되지 않은 상태 코드를 반환할 때 |
| 콘텐츠 타입 불일치 | 응답 콘텐츠 타입이 사양에서 광고하는 것과 일치하지 않을 때 |
| 상태 유지 버그 | 단독으로 작동하는 작업이 현실적인 다단계 워크플로 내에서 실패할 때 |
마지막 항목은 좀 더 자세히 살펴볼 가치가 있습니다. Schemathesis는 상태 유지 테스트를 실행할 수 있는데, 이는 사양의 링크를 기반으로 작업을 함께 연결합니다. 예를 들어, 리소스를 생성하고, 가져오고, 삭제하는 식입니다. 업데이트 후 잘못된 상태를 보고하는 리소스와 같이 순서에 의해서만 나타나는 버그는 단일 요청 테스트로는 찾기 어렵습니다. 상태 유지 단계는 이러한 시퀀스를 상태 머신으로 구동합니다.
훅(hook)을 사용하여 기본 동작을 확장할 수 있습니다. 훅은 데이터 생성을 사용자 정의하고, 자신만의 검사를 추가하거나, 어떤 작업을 테스트할지 필터링할 수 있게 해주는 Python 함수입니다. 이것이 팀이 Schemathesis를 인증 흐름이나 사양에서 표현할 수 없는 명확하지 않은 제약 조건이 있는 API에 적용하는 방법입니다.
Schemathesis를 언제 사용해야 하는가
Schemathesis는 합리적으로 정확한 OpenAPI 또는 GraphQL 사양이 있고, 광범위하고 저렴한 엣지 케이스 커버리지를 원할 때 제 역할을 합니다. 이는 수동 테스트를 작성하지 않을 유형의 실패(예: 처리되지 않은 입력, 문서화되지 않은 오류 형태, 사양과 구현 간의 계약 불일치)를 찾는 데 강력합니다.
다음과 같은 경우에 적합합니다:
- OpenAPI 사양을 유지 관리하고 실제 서버에 대해 강제하고 싶을 때.
- 처리되지 않은 500 오류가 걱정되고 CI에 퍼징 레이어를 추가하고 싶을 때.
- API에 순서가 중요한 상태 유지 워크플로가 있을 때.
- 팀이 이미 Python을 사용하고
pip및pytest에 익숙할 때.
스키마가 설명하는 것만 테스트할 수 있으므로, 사양이 부실하거나 오래된 경우에는 적합하지 않습니다. 입력이 불량하면 출력도 불량합니다. 또한 예제 기반 기능 테스트를 대체하지도 않습니다. 엔드포인트가 절대 충돌하지 않는다는 것을 아는 것은 알려진 입력에 대해 올바른 값을 반환한다는 것을 아는 것과는 다릅니다. 이 둘 모두를 원할 것입니다.
Schemathesis와 Apidog: 각각의 역할
Apidog와 Schemathesis는 서로 다른 문제를 해결하며, 나란히 잘 작동합니다. Apidog는 API 설계, 디버깅, 테스팅, 모킹 및 문서화를 위한 올인원 플랫폼입니다. Schemathesis는 속성 기반 퍼저에 중점을 둡니다. 여기서는 경계에 대해 솔직해지는 것이 중요합니다.
Apidog는 속성 기반 퍼징을 수행하지 않습니다. 가장 유사한 기능은 무작위 입력을 보내 충돌을 일으키는 몽키 테스팅입니다. 이는 유용하지만, 스키마 기반 속성 테스팅과는 다릅니다. Schemathesis는 사양의 제약 조건에서 입력을 생성하고 스키마에 대해 응답을 확인합니다. 따라서 속성 기반 퍼징이 필요한 경우 Apidog가 아닌 Schemathesis를 사용해야 합니다.
Apidog가 적합한 곳은 해당 퍼징 단계를 둘러싼 나머지 수명 주기입니다.
| 워크플로 단계 | Schemathesis | Apidog |
|---|---|---|
| 사양 기반 속성 퍼징 | 예, 핵심 기능 | 아니요 |
| 시각적 API 설계 및 사양 편집 | 아니요 | 예 |
| 예제 기반 기능 테스트 | 제한적 | 예, 시각적 테스트 빌더 |
| 사양에 대한 계약 테스트 | 부분적, 스키마 검사를 통해 | 예, 전용 워크플로 |
| 스키마 기반 모크 서버 | 아니요 | 예, 스마트 모크 |
| CI 테스트 러너 | 예, st run |
예, apidog run |
| 자동 생성 문서 | 아니요 | 예 |
실용적인 조합은 다음과 같습니다. Apidog에서 사양을 설계하고 유지 관리하며, 여기에서 기능 테스트 케이스와 모크 서버를 생성하고, apidog run을 사용하여 CI에서 실행합니다. 그런 다음, 엣지 케이스 충돌 및 계약 위반을 위해 동일한 사양을 퍼징하는 Schemathesis 단계를 추가합니다. 이 두 계층은 서로 다른 버그 클래스를 감지합니다. Apidog는 API가 알려진 경우에 대해 올바르게 작동하는지 확인하고, Schemathesis는 이를 깨뜨리는 알 수 없는 경우를 찾아냅니다.
목표가 퍼징 실행보다는 사양을 실행 가능한 기능 스위트로 전환하는 것이라면, Apidog는 OpenAPI 사양에서 API 테스트 컬렉션을 직접 생성할 수 있으며, 해당 흐름을 시도하려면 Apidog를 다운로드할 수 있습니다.
자주 묻는 질문
Schemathesis는 무료인가요?
네, 그렇습니다. Schemathesis는 MIT 라이선스에 따라 오픈 소스이며, CLI는 pip install schemathesis를 통해 무료로 설치 및 실행할 수 있습니다. 관리형 경험을 원하는 팀을 위한 호스팅 상업적 제품도 있지만, 로컬 및 CI에서 실행하는 핵심 도구는 무료입니다.
schemathesis run과 st run의 차이점은 무엇인가요?
둘은 동일한 명령입니다. st는 schemathesis의 짧은 별칭이므로, st run과 schemathesis run은 정확히 동일한 작업을 수행합니다. 선호하는 것을 사용하세요. 둘 다 스키마 경로 또는 URL과 --url, --header와 같은 옵션을 사용합니다.
Schemathesis가 기능 API 테스트를 대체할 수 있나요?
아니요, 그럴 의도도 아닙니다. Schemathesis는 API가 충돌하지 않고 응답이 스키마와 일치하는지 확인합니다. 할인 계산이 올바른지 등 비즈니스 로직을 검증하지는 않습니다. 이를 위해서는 여전히 예제 기반 기능 및 계약 테스트가 필요하며, 이는 Apidog에서 구축하고 실행할 수 있습니다. Schemathesis는 대체제가 아닌 추가적인 퍼징 계층으로 간주하세요.
Schemathesis는 GraphQL과 함께 작동하나요?
네, 그렇습니다. Schemathesis는 OpenAPI 및 GraphQL 스키마를 모두 지원합니다. GraphQL의 경우, 스키마의 타입 정의에서 쿼리를 생성하고 OpenAPI에 정의된 REST API와 동일한 방식으로 응답을 확인합니다.
결론
Schemathesis는 한 가지 작업에 특화된 강력한 도구입니다: OpenAPI 또는 GraphQL 사양을 가져와 속성 기반 생성을 통해 실제 API에 대해 스트레스 테스트를 수행합니다. 이는 예제 기반 테스트가 놓치는 충돌 및 계약 위반을 찾아내며, CI에 추가하는 데 거의 비용이 들지 않습니다. Schemathesis가 하지 않는 것은 설계, 모크, 문서화 또는 비즈니스 로직 검증입니다.
바로 이 지점에서 Apidog가 Schemathesis를 보완합니다. Apidog에서 사양을 설계하고, 기능 테스트와 모크를 생성하며, apidog run으로 CI에서 실행하고, 결과를 문서화하는 이 모든 작업을 한 곳에서 수행한 다음, 그 위에 Schemathesis를 퍼징 계층으로 추가할 수 있습니다. 해당 워크플로의 설계 및 기능 측면을 구축하려면 Apidog를 다운로드하고, 엣지 케이스 탐색은 Schemathesis에 맡기세요.