DEV Community

Cover image for 아피독 대 스키마테시스: 기능 및 계약 테스트 대 속성 기반 퍼징
Rihpig
Rihpig

Posted on • Originally published at apidog.com

아피독 대 스키마테시스: 기능 및 계약 테스트 대 속성 기반 퍼징

Apidog와 Schemathesis를 비교하고 있다면, 먼저 “둘 중 하나”가 아니라 “CI에서 각각 어떤 책임을 맡길 것인가”로 접근하는 편이 실용적입니다. Schemathesis는 OpenAPI 또는 GraphQL 스키마를 기반으로 예상하지 못한 입력을 생성해 버그를 찾는 속성 기반 퍼저이고, Apidog는 API 설계, 기능 테스트, 계약 테스트, 목(mock), 문서화, CI 실행을 한 작업 공간에서 관리하는 API 플랫폼입니다. API 테스트의 전체 범주를 정리하려면 API 테스팅 궁극 가이드를 참고하고, Schemathesis 자체 동작은 오픈 소스 문서 및 GitHub 소스에서 확인할 수 있습니다.

오늘 Apidog를 사용해 보세요

요약

Schemathesis는 속성 기반 퍼저입니다. OpenAPI 또는 GraphQL 스키마를 입력으로 받아 API가 다음과 같은 문제를 일으키는지 자동으로 탐색합니다.

  • 서버 오류를 반환하는 엣지 케이스 입력
  • 문서화된 스키마와 다른 응답
  • 유효하지 않은 데이터가 2xx로 통과하는 검증 누락

Schemathesis는 Python 속성 기반 테스팅 라이브러리인 Hypothesis를 기반으로 하며, 사람이 직접 테스트 케이스로 작성하지 않은 입력 조합을 찾아내는 데 강합니다.

Apidog는 올인원 API 플랫폼입니다. API를 시각적으로 설계하고, 어설션으로 기능 및 계약 테스트를 작성하며, CSV 또는 JSON 기반 데이터 주도 테스트를 실행하고, 엔드포인트를 목(mock)하며, apidog run으로 CI/CD에 연결할 수 있습니다. REST, gRPC, WebSocket, SSE, SOAP, GraphQL을 한 작업 공간에서 다룰 수 있습니다.

정리하면 다음과 같습니다.

  • Schemathesis: 스키마 기반으로 알 수 없는 엣지 케이스를 찾는 도구
  • Apidog: 팀이 의도적으로 설계하고 유지 관리하는 API 테스트와 협업 워크플로우를 운영하는 도구

두 도구는 같은 문제를 해결하지 않습니다. CI에서는 서로 다른 계층으로 나누어 사용하는 것이 가장 현실적입니다.

Schemathesis가 잘하는 일

Schemathesis는 스키마를 계약으로 보고, 그 계약을 깨뜨릴 수 있는 입력을 자동으로 생성합니다. 선언된 타입, 필수 필드, enum, 길이 제한, 숫자 범위 같은 제약 조건을 기반으로 요청을 만들고, 응답이 스펙과 일치하는지 확인합니다.

기본적으로 다음 유형의 문제를 찾는 데 적합합니다.

  • 수동 테스트에 없던 입력으로 발생하는 500 Internal Server Error
  • 응답 스키마 불일치
    • 문서화되지 않은 필드
    • 잘못된 타입
    • 누락된 필수 필드
  • 잘못된 요청이 검증되지 않고 2xx로 처리되는 문제
  • API가 스펙에 정의되지 않은 상태 코드를 반환하는 문제

예를 들어 OpenAPI 스키마가 있다면 Schemathesis는 다음처럼 CLI에서 실행할 수 있습니다.

schemathesis run openapi.yaml --base-url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

원격 스키마를 사용하는 경우에는 다음처럼 실행할 수 있습니다.

schemathesis run https://api.example.com/openapi.json
Enter fullscreen mode Exit fullscreen mode

CI에서 Docker로 실행하려면 다음과 같은 형태로 구성할 수 있습니다.

docker run --rm schemathesis/schemathesis:stable \
  run https://api.example.com/openapi.json \
  --base-url https://api.example.com
Enter fullscreen mode Exit fullscreen mode

Schemathesis의 실용적인 장점은 실패 케이스를 축소한다는 점입니다. 큰 페이로드가 실패를 유발하면, Hypothesis 기반 축소 과정을 통해 문제를 재현하는 더 작은 입력을 찾아냅니다. 디버깅할 때 “어떤 최소 입력이 API를 깨뜨리는지”를 빠르게 확인할 수 있습니다.

또한 한 응답의 데이터를 다음 요청에 활용하는 방식으로 작업을 연결할 수 있어, 단일 엔드포인트뿐 아니라 실제 요청 시퀀스도 테스트할 수 있습니다.

다만 Schemathesis는 테스트 엔진입니다. API 설계, 팀 협업, 목(mock), 문서화, 비엔지니어용 UI를 제공하는 플랫폼은 아닙니다. 이미 스키마가 있다고 가정하고, Python 및 CLI 중심으로 동작합니다. 복잡한 비즈니스 로직을 사람이 읽기 쉬운 기능 테스트 시나리오로 관리하는 목적과도 다릅니다.

Apidog가 잘하는 일

Apidog는 퍼징 주변의 API 라이프사이클을 담당합니다. 특히 팀이 API를 설계하고, 합의된 동작을 테스트하고, CI에서 반복 실행해야 할 때 유용합니다.

Apidog에서는 다음 작업을 하나의 흐름으로 구성할 수 있습니다.

  1. OpenAPI 기반 편집기로 API를 시각적으로 설계합니다.
  2. 스펙을 API의 진실의 원천으로 유지합니다.
  3. 시각적 어설션으로 기능 테스트를 작성합니다.
  4. 여러 요청을 테스트 시나리오로 연결합니다.
  5. 단계 간 데이터를 전달합니다.
  6. 실행 중인 API가 스펙과 일치하는지 계약 테스트를 실행합니다.
  7. CSV 또는 JSON 파일로 데이터 주도 테스트를 실행합니다.
  8. 백엔드 구현 전에도 실제와 유사한 응답으로 엔드포인트를 목(mock)합니다.
  9. apidog run 명령어를 사용해 CI/CD에서 테스트를 실행합니다.
  10. REST, gRPC, WebSocket, SSE, SOAP, GraphQL을 한 곳에서 테스트합니다.

예를 들어 데이터 주도 테스트는 다음처럼 CI에서 실행할 수 있습니다.

apidog run -d test-data.csv
Enter fullscreen mode Exit fullscreen mode

또는 JSON 데이터를 사용할 수 있습니다.

apidog run -d test-data.json
Enter fullscreen mode Exit fullscreen mode

Apidog의 핵심은 “생성형 퍼징”이 아니라 “의도적인 테스트 자동화”입니다. 예를 들어 다음과 같은 테스트는 사람이 명확히 정의해야 합니다.

  • 유효한 주문 생성 요청은 201을 반환해야 한다.
  • 응답에는 orderId가 있어야 한다.
  • 만료된 토큰은 401을 반환해야 한다.
  • 결제 플로우의 1단계에서 생성된 cartId를 3단계 요청에 전달해야 한다.
  • 특정 비즈니스 상태에서는 주문 취소가 불가능해야 한다.

이런 테스트는 팀이 검토하고 유지 관리하는 기능 테스트 스위트에 속합니다.

주의할 점도 있습니다. Apidog는 인터페이스에 무작위 입력을 던지는 몽키 테스팅을 지원하지만, 이것은 Schemathesis의 속성 기반 테스팅과 다릅니다.

  • 몽키 테스팅: 무작위적이고 비구조적인 입력
  • 속성 기반 테스팅: 스키마의 타입과 제약 조건을 바탕으로 전략적으로 생성한 입력

따라서 진정한 속성 기반 퍼징이 필요하다면 Schemathesis를 사용해야 합니다. Apidog는 설계, 테스트 시나리오, 계약 테스트, 목(mock), 다중 프로토콜 테스트, CI 실행에 강합니다.

정면 비교

기능 Apidog Schemathesis
주요 역할 기능 테스트, 계약 테스트, 설계, 목(mock), 문서 스키마 기반 속성 기반 퍼징
테스트 작성 방식 시각적 어설션, 코드 없는 시나리오 스키마에서 자동 생성, 코드 내 속성
입력 전략 의도적 케이스, CSV/JSON 데이터 주도 테스트 스키마 입력 공간 전반을 탐색하는 생성 입력
알 수 없는 엣지 케이스 발견 제한적. 몽키 테스팅은 가능하지만 속성 기반은 아님 핵심 강점
스키마/스펙 계약 확인 계약 테스트 지원 스펙 기반 응답 유효성 검사
프로토콜 REST, gRPC, WebSocket, SSE, SOAP, GraphQL OpenAPI 기반 REST, GraphQL
목(Mocking) 내장 스마트 목 지원하지 않음
API 설계 및 문서 시각적 디자이너, 자동 문서 지원하지 않음
CI/CD 모든 파이프라인에서 apidog run 실행 CLI, Docker, GitHub Action, pytest
인터페이스 데스크톱 앱, CLI CLI, Python 라이브러리
주 사용자 개발자, QA, 기술 리더, 프론트엔드, 문서 작성자 Python/CLI에 익숙한 엔지니어

비교의 핵심은 간단합니다.

  • Apidog는 넓고 의도적인 API 테스트 및 협업 계층입니다.
  • Schemathesis는 좁지만 깊은 생성형 퍼징 계층입니다.

CI에서 둘 다 사용하는 방법

두 도구를 함께 사용할 때는 역할을 분리해야 합니다. 같은 테스트를 두 번 작성하는 방식이 아니라, 하나의 스키마를 공유하고 각 도구가 다른 리스크를 처리하게 만드는 방식이 좋습니다.

1. Apidog로 의도적인 테스트 계층을 구성합니다

Apidog에는 사람이 명확히 기대 결과를 정의할 수 있는 테스트를 넣습니다.

예시는 다음과 같습니다.

  • 정상적인 회원가입 요청은 201을 반환한다.
  • 중복 이메일은 409를 반환한다.
  • 로그인 성공 시 access token이 응답에 포함된다.
  • 만료된 token으로 보호된 API를 호출하면 401이 반환된다.
  • 주문 생성 후 결제 요청까지 이어지는 시나리오가 성공한다.
  • API 응답이 OpenAPI 스펙과 일치한다.

이 계층은 결정론적이어야 합니다. 즉, 정상이라면 항상 통과해야 합니다. 따라서 CI의 블로킹 게이트로 두기에 적합합니다.

예시 CI 단계는 다음과 같습니다.

apidog run
Enter fullscreen mode Exit fullscreen mode

데이터 파일을 사용한다면 다음처럼 실행합니다.

apidog run -d cases.csv
Enter fullscreen mode Exit fullscreen mode

이 계층의 목표는 “우리가 의도한 비즈니스 동작이 깨지지 않았는지”를 확인하는 것입니다.

2. Schemathesis로 생성적 퍼징 계층을 구성합니다

Schemathesis에는 사람이 직접 생각하기 어려운 입력 조합 탐색을 맡깁니다.

예시는 다음과 같습니다.

schemathesis run openapi.yaml --base-url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

또는 배포된 환경을 대상으로 실행합니다.

schemathesis run https://api.example.com/openapi.json \
  --base-url https://api.example.com
Enter fullscreen mode Exit fullscreen mode

이 계층은 다음 문제를 찾는 데 사용합니다.

  • 특정 문자열 길이에서 발생하는 서버 오류
  • nullable 처리 누락
  • enum 외 값 처리 문제
  • 숫자 범위 검증 누락
  • 배열 크기 또는 중첩 객체 처리 문제
  • 응답 스키마 불일치

퍼징은 실행 시간이 길거나 결과가 다소 시끄러울 수 있습니다. 따라서 일반적으로 다음 중 하나로 분리하는 것이 좋습니다.

  • 별도 CI job
  • nightly build
  • release candidate 검증 단계
  • staging 환경 대상 정기 실행

예를 들어 GitHub Actions에서는 Apidog 테스트를 PR 블로킹 단계로 두고, Schemathesis는 별도 job 또는 스케줄 작업으로 분리할 수 있습니다.

name: API Tests

on:
  pull_request:
  schedule:
    - cron: "0 2 * * *"

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Apidog tests
        run: apidog run

  schemathesis-fuzzing:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    steps:
      - uses: actions/checkout@v4
      - name: Run Schemathesis
        run: schemathesis run openapi.yaml --base-url https://api.example.com
Enter fullscreen mode Exit fullscreen mode

3. 스키마를 공유 계약으로 유지합니다

두 도구를 연결하는 핵심은 OpenAPI 또는 GraphQL 스키마입니다.

Apidog는 스키마를 다음 작업의 기준으로 사용합니다.

  • API 설계
  • 목(mock)
  • 문서화
  • 계약 테스트
  • 기능 테스트 시나리오 관리

Schemathesis는 같은 스키마를 사용해 입력을 생성하고 응답을 검증합니다.

따라서 스키마가 부정확하면 두 도구 모두 약해집니다. 반대로 스키마 품질을 높이면 두 도구 모두 더 강력해집니다.

실무에서는 다음 규칙을 추천합니다.

  • API 변경은 먼저 스키마에 반영합니다.
  • 스키마 변경은 코드 리뷰 대상에 포함합니다.
  • 필수 필드, enum, nullable, format, min/max 제약 조건을 적극적으로 명시합니다.
  • 실제 응답과 문서화된 응답이 다르면 계약 테스트에서 실패하게 만듭니다.
  • Schemathesis에서 발견한 스키마 불일치는 API 버그인지 스키마 버그인지 분류합니다.

추천 워크플로우

실제 팀에서는 다음 순서로 적용하면 중복 없이 효과를 얻을 수 있습니다.

단계 1: Apidog에서 API 스펙을 정리합니다

먼저 OpenAPI 스펙을 정리합니다. 엔드포인트, 요청 바디, 응답 바디, 상태 코드, 인증 방식, 에러 응답을 명확하게 정의합니다.

특히 Schemathesis를 함께 사용할 계획이라면 다음 항목을 가능한 구체적으로 작성해야 합니다.

components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          minLength: 1
        quantity:
          type: integer
          minimum: 1
          maximum: 100
Enter fullscreen mode Exit fullscreen mode

제약 조건이 구체적일수록 Schemathesis가 더 의미 있는 입력을 생성할 수 있습니다.

단계 2: Apidog에서 핵심 기능 시나리오를 작성합니다

다음으로 사람이 반드시 보장해야 하는 기능 흐름을 테스트로 만듭니다.

예시는 다음과 같습니다.

  1. 사용자 로그인
  2. 상품 조회
  3. 장바구니 추가
  4. 주문 생성
  5. 결제 요청
  6. 주문 상태 확인

이런 흐름은 단일 요청 테스트보다 시나리오 테스트로 관리하는 것이 좋습니다. 앞 단계의 응답 값을 다음 단계 요청에 전달해야 하기 때문입니다.

단계 3: 데이터 주도 테스트를 추가합니다

같은 시나리오를 여러 입력으로 반복해야 한다면 CSV 또는 JSON 데이터를 사용합니다.

예를 들어 회원가입 테스트에서는 다음과 같은 케이스를 분리할 수 있습니다.

email,password,expectedStatus
valid@example.com,StrongPassword123!,201
invalid-email,StrongPassword123!,400
valid2@example.com,short,400
Enter fullscreen mode Exit fullscreen mode

CI에서는 다음처럼 실행합니다.

apidog run -d signup-cases.csv
Enter fullscreen mode Exit fullscreen mode

단계 4: Schemathesis를 별도 퍼징 단계로 추가합니다

Apidog 테스트가 안정적으로 동작하면 Schemathesis를 추가합니다.

schemathesis run openapi.yaml --base-url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

처음에는 실패가 많이 나올 수 있습니다. 이때 모든 실패를 즉시 제품 버그로 보지 말고 다음처럼 분류합니다.

  • 실제 API 버그
  • 스키마 정의 누락
  • 응답 문서화 누락
  • 유효성 검증 정책 미정
  • 테스트 환경 데이터 문제

분류 후 스키마와 API를 함께 개선하면 이후 실행 결과가 훨씬 유용해집니다.

단계 5: CI 정책을 분리합니다

권장 정책은 다음과 같습니다.

  • Apidog 기능/계약 테스트: PR마다 실행, 실패 시 머지 차단
  • Schemathesis 퍼징: nightly 또는 별도 job으로 실행
  • 릴리스 전: 두 계층 모두 실행
  • 스키마 변경 PR: Apidog 계약 테스트와 Schemathesis 실행을 함께 검토

이렇게 하면 빠른 피드백과 깊은 엣지 케이스 탐색을 동시에 얻을 수 있습니다.

자주 묻는 질문

Apidog는 Schemathesis의 대안인가요?

부분적으로만 그렇습니다. 스키마에서 생성된 속성 기반 퍼징이 필요하다면 Apidog는 Schemathesis의 완전한 대체재가 아닙니다. Apidog는 그 기능을 제공하는 도구가 아닙니다.

하지만 설계, 기능 테스트, 계약 테스트, 목(mock), 문서화, CI 실행을 하나의 플랫폼에서 관리하려는 목적이라면 Apidog가 라이프사이클의 더 넓은 영역을 다룹니다. 실무적으로는 대체재라기보다 보완재로 보는 것이 맞습니다.

계약 테스트 관점에서는 Apidog에서 계약 테스트가 어떻게 작동하는지를 확인할 수 있습니다.

속성 기반 API 테스트와 기능 API 테스트의 차이는 무엇인가요?

기능 테스트는 사람이 의도적으로 정의한 특정 케이스를 검증합니다.

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

이 입력을 보내면 이 상태 코드와 이 응답이 와야 한다.
Enter fullscreen mode Exit fullscreen mode

속성 기반 테스트는 많은 생성 입력에 대해 일반적인 속성을 검증합니다.

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

어떤 유효하지 않은 입력이 와도 서버는 500을 반환하면 안 된다.
모든 2xx 응답은 선언된 스키마와 일치해야 한다.
Enter fullscreen mode Exit fullscreen mode

기능 테스트는 설계된 동작을 검증하고, 속성 기반 테스트는 예상하지 못한 동작을 찾습니다. 둘 다 필요합니다.

Apidog도 퍼징을 하나요?

Apidog에는 무작위 입력을 보내는 몽키 테스팅 기능이 있습니다. 하지만 이것은 속성 기반 퍼징이 아닙니다.

속성 기반 퍼징은 스키마의 타입과 제약 조건을 바탕으로 입력을 전략적으로 생성하고, 실패를 최소 재현 케이스로 축소합니다. 이 목적에는 Schemathesis가 적합합니다.

Apidog의 강점은 다음에 있습니다.

  • 의도적인 기능 테스트
  • 계약 테스트
  • 데이터 주도 테스트
  • 다중 프로토콜 테스트
  • API 설계
  • 목(mock)
  • 문서화
  • CI/CD 실행

같은 CI 파이프라인에서 둘 다 실행할 수 있나요?

네. 흔히 사용하는 구성입니다.

권장 방식은 다음과 같습니다.

  • apidog run: PR마다 실행하는 블로킹 게이트
  • schemathesis run: 별도 job 또는 nightly job
  • 둘 다 같은 OpenAPI 또는 GraphQL 스키마 사용

Apidog 테스트는 결정론적이므로 항상 통과해야 하는 기준으로 두기 좋습니다. Schemathesis는 더 많은 입력을 탐색하므로 실행 시간이 길거나 새 결함을 많이 발견할 수 있습니다. 따라서 별도 단계로 분리하면 CI 운영이 안정적입니다.

둘 중 하나만 선택해야 한다면 무엇을 먼저 도입해야 하나요?

현재 상태에 따라 다릅니다.

API 스펙, 테스트 시나리오, 목(mock), 문서화, CI 실행이 정리되어 있지 않다면 Apidog부터 도입하는 편이 좋습니다. 팀이 공유할 기준과 반복 가능한 테스트 스위트를 먼저 만드는 것이 중요하기 때문입니다.

이미 OpenAPI 스키마가 잘 정리되어 있고, 기능 테스트도 충분하지만 엣지 케이스 버그가 계속 나온다면 Schemathesis를 추가하는 것이 효과적입니다.

결론

Schemathesis는 강력한 속성 기반 퍼저입니다. OpenAPI 또는 GraphQL 스키마에서 입력을 생성해 사람이 직접 작성한 테스트가 놓치는 엣지 케이스와 계약 불일치를 찾아냅니다.

Apidog는 그 주변의 API 테스트 플랫폼입니다. 시각적 설계, 기능 테스트, 계약 테스트, 데이터 주도 실행, 목(mock), 문서화, CI/CD, 그리고 REST, gRPC, WebSocket, SSE, SOAP, GraphQL 지원을 제공합니다.

실용적인 전략은 다음과 같습니다.

  1. Apidog로 스키마, 문서, 목(mock), 기능 테스트, 계약 테스트를 관리합니다.
  2. apidog run으로 CI에서 결정론적 테스트를 실행합니다.
  3. Schemathesis로 같은 스키마를 퍼징해 예상하지 못한 입력 문제를 찾습니다.
  4. 두 도구의 기준이 되는 스키마를 지속적으로 정확하게 유지합니다.

현재 설정이 한쪽에만 의존하고 있다면 다른 계층을 추가하십시오. 의도적이고 유지 관리되는 테스트 스위트와 설계 계층이 필요하다면 Apidog를 다운로드하고, 생성적 퍼징에는 Schemathesis를 사용하며, 공유 스키마로 두 도구를 연결하십시오. Apidog는 무료로 사용해 볼 수 있고, 기능 테스트가 Apidog에 준비되면 CI 연결은 apidog run 한 명령어로 시작할 수 있습니다.

Top comments (0)