API 회귀 테스트: 호환성 문제 조기 발견법

엔드포인트에 작은 변경 사항을 배포합니다. 코드는 컴파일되고, 새 기능은 작동하며, 배포도 완료됩니다. 이틀 후, 이름을 바꾼 필드가 이전에는 문자열이었는데 이제는 객체가 되어서 모바일 클라이언트가 충돌하기 시작합니다. 아무도 고의로 문제를 일으키려 한 것은 아닙니다. 변경 사항은 로컬에서만 영향을 미치는 것처럼 보였지만, 그렇지 않았습니다.

API 회귀 테스트는 이러한 종류의 오류가 사용자에게 도달하기 전에 잡아내기 위해 존재합니다. 현재 API가 어떻게 동작하는지 설명하는 테스트 스위트를 저장한 다음, 변경 사항이 있을 때마다 이 스위트를 다시 실행합니다. 응답 형태, 상태 코드 또는 핵심 값이 기록된 내용과 달라지면 스위트가 실패하고 정확히 어디에서 문제가 발생했는지 알려줍니다. 이 가이드에서는 무엇을 기준으로 삼아야 하는지, 재사용 가능한 스위트를 구축하는 방법, 그리고 CI에서 자동으로 실행하여 이름 변경이 절대 사고로 이어지지 않도록 하는 방법을 다룹니다.

버튼

API 회귀 테스트란 무엇이며 (API는 왜 퇴보하는가)

회귀 테스트는 변경 후에도 기존 동작이 유지되는지 확인하기 위해 이미 통과한 테스트를 다시 실행하는 것을 의미합니다. API의 경우, "기존 동작"은 소비자가 의존하는 계약입니다: 경로, 상태 코드, 응답 스키마, 그리고 핵심 필드의 값들입니다.

API는 일반적인 이유로 퇴보합니다. 누군가 JSON 필드의 이름을 바꿉니다. 리팩토링으로 인해 200이 204로 변경됩니다. 새로운 유효성 검사 규칙이 이전에는 허용되던 입력을 거부합니다. ORM 업그레이드가 날짜 형식을 소리 없이 변경합니다. 의존성 업데이트가 클라이언트가 파싱하는 오류 메시지를 변경합니다. 이 중 어느 것도 컴파일 오류로 나타나지 않습니다. 이들은 깨진 통합으로 나타나며, 종종 호출자 중 일부에게만 발생합니다.

여기서 중요한 차이점은 다음과 같습니다: API 회귀 테스트는 일반 소프트웨어 회귀 테스트보다 범위가 좁습니다. 전체 앱의 비즈니스 로직을 다시 검증하는 것이 아닙니다. 다른 시스템이 연결되는 부분인 HTTP 인터페이스가 변경되지 않았는지 확인하는 것입니다. 이러한 집중 덕분에 모든 커밋에서 저렴하게 실행할 수 있습니다.

무엇을 기준으로 삼을 것인가

회귀 스위트는 주장하는 내용만큼만 좋습니다. 너무 적게 주장하면 실제 손상이 빠져나갈 수 있습니다. 너무 많이 주장하면 모든 의도적인 변경이 스위트를 실패하게 만듭니다. 소비자가 실제로 알아차릴 필드를 목표로 하세요.

다음 네 가지 계층을 기준으로 삼으십시오:

상태 코드. 모든 엔드포인트는 알려진 입력에 대해 알려진 상태를 반환해야 합니다. 본문이 정상적으로 보이더라도 200이 500이 되거나 201이 200이 되는 것은 회귀입니다.
응답 스키마. 응답의 구조와 유형. 필드 이름, 중첩, 그리고 값이 문자열, 숫자, 배열 또는 객체인지 여부. 스키마 드리프트는 가장 흔한 무언의 중단입니다.
핵심 필드 값. 모든 값은 아니지만, 계약상 의미가 있는 값들: 반드시 존재해야 하는 id, 알려진 집합 내에 있어야 하는 status 열거형, 숫자여야 하는 total 등.
계약. OpenAPI 스펙과 실제 응답 간의 관계. 스펙에서 email이 필수라고 명시했는데 API가 더 이상 이를 반환하지 않으면, 이는 계약 위반입니다. 스펙을 진리의 원천으로 만드는 방법에 대해서는 API 계약 테스트를 참조하십시오.

유용한 규칙: 클라이언트가 오류를 일으킬 만한 내용에 대해 주장하고, 오늘날 페이로드에 있는 내용에 대해서는 주장하지 마십시오. createdAt 타임스탬프는 요청마다 변경되므로, 그 값보다는 유형과 형식을 고정하세요.

다음은 단일 엔드포인트에 대한 최소한의 주장 집합으로, 응답에 대해 실행할 일반적인 검사로 작성되었습니다:

GET /v1/users/42  ->  200
  body.id            is present, type number
  body.email         is present, type string, matches email format
  body.status        is one of ["active", "pending", "suspended"]
  body.roles         type array
  response time      < 800 ms

이 다섯 줄은 계약을 설명합니다. 변경 후 이 중 하나라도 실패하면 회귀가 발생한 것입니다. 응답 본문에 대한 검사 작성에 대한 더 깊이 있는 내용은 API 주장을 참조하십시오.

수동 vs 자동화된 회귀 테스트

수동으로 회귀 테스트를 할 수 있습니다. 변경 후 API 클라이언트를 열고, 저장된 몇 개의 요청을 다시 실행하고, 응답을 육안으로 확인합니다. 이는 엔드포인트 하나에는 작동하지만 열 개가 되면 무너집니다. 사람은 지루한 경우를 건너뛰며, 지루한 경우에 회귀가 숨어 있습니다. 또한 수동 검사는 예약된 작업이 의존성 업데이트를 병합하는 새벽 2시에는 실행할 수 없습니다.

자동화된 회귀 테스트는 반복 작업에서 사람을 제거합니다. 스위트를 한 번 기록하면, 기계가 모든 푸시, 모든 풀 리퀘스트, 모든 배포에서 이를 다시 실행합니다. 그 가치는 단일 실행 속도에 있지 않습니다. 스위트가 매번 실행되며, 아무도 수고할 가치가 있다고 결정할 필요가 없다는 점에 있습니다.

절충점은 초기 작업입니다. 스위트를 구축하고 최신 상태로 유지해야 합니다. 이 유지보수 비용은 실재하지만, 5초짜리 테스트로 잡을 수 있었을 프로덕션 사고 한 건의 비용보다 적습니다.

	수동	자동화
모든 변경 시 실행	아니요, 규율에 따라 다름	예, 기본적으로
적용 범위	일부 엔드포인트	전체 스위트
실행당 비용	사람의 시간 분	컴퓨팅 시간 초
새벽 2시의 오류 감지	아니요	예
선행 노력	낮음	보통

장난감 프로젝트를 넘어서는 모든 것에 대해서는 자동화하십시오.

재사용 가능한 회귀 스위트 구축

회귀 스위트는 저장된 요청들의 집합으로, 각 요청에는 주장이 포함되어 있으며 함께 실행할 수 있도록 그룹화되어 있습니다. 목표는 재사용입니다: 한 번 구축하고 영원히 실행하며, 엔드포인트를 추가할 때 확장하는 것입니다.

변경에도 견딜 수 있도록 스위트를 구성하세요:

기능이 아닌 리소스별로 그룹화하십시오. 모든 /users 테스트를 함께, 모든 /orders 테스트를 함께 모으세요. 사용자 서비스를 건드릴 때, 어떤 그룹을 주시해야 하는지 알 수 있습니다.

변경될 수 있는 모든 것에 환경 변수를 사용하세요. 기본 URL, 인증 토큰, 테넌트 ID는 각 요청에 하드코딩하는 대신 환경에 속해야 합니다. 이를 통해 하나의 설정을 교체하여 동일한 스위트를 로컬, 스테이징 및 프로덕션 환경에서 실행할 수 있습니다.

서로 의존하는 요청을 연결하십시오. 현실적인 흐름은 리소스를 생성하고, 다시 읽어오고, 업데이트하고, 삭제하는 것입니다. 생성 응답에서 id를 추출하여 다음 요청에 전달하십시오. 이는 독립적으로는 나타나지 않고 순서상에서만 나타나는 회귀를 잡아냅니다. 이 부분이 회귀 테스트가 API 통합 테스트와 겹치는 지점입니다.

데이터로 엣지 케이스를 구동하십시오. 거의 동일한 요청 10개 대신, 하나의 요청을 작성하고 유효한 값, 빈 값, 경계 값, 알려진 잘못된 값 등 입력 테이블을 제공하십시오. 각 행은 테스트 케이스가 됩니다. 데이터 기반 테스트는 커버리지를 넓히면서 스위트 크기를 작게 유지합니다.

다음은 단일 유효성 검사 테스트를 위한 데이터 테이블이 CSV 형태로 어떻게 보일 수 있는지입니다:

email,expectedStatus
alice@example.com,201
bob@test.co,201
not-an-email,422
,422
a@b,422

하나의 요청, 다섯 개의 케이스, 상태 코드에 대한 다섯 개의 주장. 새로운 엣지 케이스를 찾을 때마다 행을 추가하면, 새로운 코드 없이 스위트가 확장됩니다.

스위트를 빠르게 유지하십시오. 20분이 걸리는 회귀 스위트는 건너뛰어질 것입니다. 느린 서드파티 의존성을 모의하고, 도구가 허용하는 경우 독립적인 요청을 병렬로 실행하며, 전체 엔드투엔드 흐름은 더 작고 느린 야간 실행을 위해 남겨두십시오.

CI에서 모든 변경 시 스위트 실행

노트북에 있는 회귀 스위트는 노트북만 보호합니다. 핵심은 회귀를 유발할 수 있는 동일한 이벤트, 즉 풀 리퀘스트와 메인 브랜치로의 병합 시 지속적 통합(CI)에서 이를 실행하는 것입니다.

패턴은 CI 시스템 전반에 걸쳐 동일합니다. 헤드리스 러너를 설치하고, 저장된 스위트를 가리키게 한 다음, 주장이 실패하면 빌드를 실패 처리합니다. Apidog은 바로 이 목적으로 명령줄 러너를 제공합니다. Node로 설치하십시오:

npm install -g apidog-cli

그런 다음 저장된 테스트 시나리오 또는 스위트를 ID로, 선택된 환경에 대해 실행하고 보고서를 생성합니다:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit

이를 자세히 살펴보겠습니다:

--access-token은 실행을 인증합니다. 토큰은 CI 시크릿으로 저장하고, 절대로 저장소에 두지 마십시오.
-t는 실행할 시나리오, 폴더 또는 스위트의 ID입니다.
-e는 환경 ID이므로, 하나의 값을 변경하여 동일한 스위트가 스테이징 또는 프로덕션을 대상으로 할 수 있습니다.
-r은 보고서 형식을 나열합니다. cli는 콘솔에 출력하고, html은 읽기 쉬운 보고서를 생성하며, junit은 CI가 테스트별 통과/실패를 표시하기 위해 파싱할 수 있는 XML을 내보냅니다.

이 러너는 헤드리스입니다. Node를 실행할 수 있는 모든 CI 단계에 적합하므로, 동일한 명령이 GitHub Actions, GitLab CI, Jenkins 또는 CircleCI에서 작동합니다. 다음은 모든 풀 리퀘스트에서 스위트를 실행하는 GitHub Actions 작업입니다:

name: API Regression
on: [pull_request]
jobs:
  regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '22'
      - run: npm install -g apidog-cli
      - run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

시나리오가 실패하면 러너는 0이 아닌 값으로 종료되고 작업은 실패합니다. 누군가가 확인할 때까지 풀 리퀘스트는 차단됩니다. 전체 복사-붙여넣기 파이프라인과 더 많은 CI 패턴은 CI/CD용 Apidog CLI 및 GitHub Actions에서 API 테스트를 자동화하는 방법을 참조하십시오.

스위트에 데이터 파일을 제공하려면 -d를 사용하여 전달하십시오:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit

자체 API 버전을 가진 기능 브랜치를 테스트하시나요? 기본값 대신 해당 브랜치에 저장된 스위트를 실행하려면 --branch를 추가하십시오. 클라우드에 실행 기록을 유지하려면 --upload-report 플래그를 붙이십시오.

스키마 및 계약 차이점 비교

주장은 동작상의 회귀를 잡아냅니다. 스키마 차이점 비교는 정의상의 회귀를 잡아내며, 종종 배포하기 전에 잡아냅니다.

아이디어는 다음과 같습니다: OpenAPI 스펙은 저장소에 있는 버전 관리된 파일입니다. 누군가가 이를 편집하면, 새 스펙을 이전 스펙과 비교하고 변경 사항을 분류합니다. 선택적 필드를 추가하는 것은 안전합니다. 필드를 제거하거나, 이름을 바꾸거나, 유형을 강화하거나, 선택적 필드를 필수로 만드는 것은 파괴적 변경입니다. 차이점 비교 도구는 풀 리퀘스트에서 파괴적 변경 사항에 플래그를 지정하여, 검토자가 YAML의 장벽 대신 “이것은 user.phone을 제거합니다”와 같이 볼 수 있도록 합니다.

이를 실제 API에 대한 계약 테스트와 결합하십시오. 각 실행에서 실제 응답을 현재 스키마에 대해 유효성 검사합니다. 스펙이 API가 더 이상 반환하지 않는 필드를 약속하거나, API가 스펙에서 금지하는 유형을 반환하면 검사가 실패합니다. 이것이 양면 보호입니다: 스펙 차이점 비교는 계약에 대한 의도적인 편집을 잡아내고, 계약 테스트는 계약에서 멀어지는 코드를 잡아냅니다.

파괴적 변경이 항상 버그는 아닙니다. 때로는 필드를 제거할 의도일 수도 있습니다. 차이점 비교의 목적은 그러한 결정을 명시적으로 만들고, 클라이언트를 놀라게 하는 대신 버전 관리 및 사용 중단 프로세스를 통해 처리하는 것입니다. 의도적으로 수행하는 변경 사항을 처리하는 방법에 대해서는 API를 대규모로 버전 관리하고 사용 중단하는 방법을 참조하십시오.

Apidog이 회귀 스위트를 실행하는 방법

Apidog은 위에 설명된 모든 부분을 한곳에서 다루므로, 스위트와 스펙이 서로 가까이 유지됩니다.

테스트 시나리오를 시각적으로 구축합니다: 요청을 연결하고, 한 응답에서 다음 응답으로 값을 추출하며, 상태, 스키마 및 필드 값에 대한 주장을 첨부합니다. API 디자인과 테스트가 동일한 프로젝트에 존재하므로, 스키마를 두 번 작성할 필요 없이 엔드포인트의 저장된 스키마에 대해 응답의 유효성을 검사할 수 있습니다. 디자인이 변경되면 테스트가 검사하는 스키마도 함께 변경됩니다.

데이터 기반 케이스의 경우, CSV 또는 JSON 데이터셋을 시나리오에 첨부하면 Apidog이 행당 하나의 케이스를 실행합니다. 관련 시나리오를 테스트 스위트에 저장하여 단일 실행으로 전체 리소스 또는 흐름을 연습할 수 있습니다.

apidog-cli 러너는 위에서 보여준 것처럼 저장된 스위트를 헤드리스로 CI에 가져옵니다. 저장된 시나리오와 스위트를 실행합니다. 이는 대화형 요청 송신기도 아니고 부하 생성기도 아닙니다. 단 하나의 작업을 수행합니다: 회귀 스위트를 다시 실행하고 통과된 내용을 보고합니다. 이 좁은 범위 덕분에 Node를 실행할 수 있는 모든 CI 단계에 통합될 수 있습니다. CLI와 스크립팅된 워크플로우에 대해서는 Apidog CLI CI/CD 파이프라인 가이드를 참조하십시오.

시작 워크플로우

이번 주에 테스트 전략을 재구축하지 않고도 채택할 수 있는 순서는 다음과 같습니다:

가장 많이 호출되는 엔드포인트 5개를 선택하십시오. 회귀 위험은 트래픽이 집중되는 곳에 집중됩니다. 거기서부터 시작하십시오.
각 엔드포인트에 주장을 포함한 요청을 저장하십시오. 상태 코드, 응답 스키마, 그리고 두세 개의 핵심 필드 각각. 이것이 당신의 기준선입니다.
하나의 연결된 흐름을 추가하십시오. 핵심 리소스에 대한 생성, 읽기, 업데이트, 삭제. 이는 독립된 테스트가 놓치는 교차 요청 회귀를 잡아냅니다.
하나의 유효성 검사가 많은 엔드포인트에 데이터 테이블을 추가하십시오. 몇 개의 유효한, 빈, 그리고 잘못된 입력.
풀 리퀘스트에서 CI에 연결하십시오. apidog-cli를 설치하고, -r junit으로 스위트를 실행하며, 실패 시 병합을 차단하십시오.
버그가 놓칠 때 스위트를 확장하십시오. 놓친 모든 프로덕션 회귀는 새로운 테스트 케이스가 됩니다. 스위트는 자체적인 놓침을 통해 강해집니다.

1단계부터 4단계까지는 오후 한나절이면 됩니다. 5단계는 단일 CI 파일입니다. 그 후 스위트는 자체적으로 실행되며, 실제 상황에서 새로운 실패 모드를 알게 될 때만 확장합니다. 그 피드백 루프가 핵심입니다: 사고가 될 뻔했던 이름 변경은 풀 리퀘스트에서 빨간색 체크 표시로 바뀝니다.

자주 묻는 질문 (FAQ)

API 회귀 테스트는 일반 회귀 테스트와 어떻게 다른가요? 일반 회귀 테스트는 UI 및 비즈니스 로직을 포함한 전체 시스템에 걸쳐 애플리케이션 동작을 다시 검증합니다. API 회귀 테스트는 이를 HTTP 표면, 즉 경로, 상태 코드, 응답 스키마 및 핵심 필드 값으로 좁힙니다. 이러한 좁은 초점 덕분에 모든 커밋에서 실행할 수 있을 만큼 빠르며, 다른 시스템이 연결되는 부분을 정확히 대상으로 합니다.

회귀 스위트를 얼마나 자주 실행해야 하나요? API에 영향을 미칠 수 있는 모든 변경 시 실행해야 합니다. 실제로는 모든 풀 리퀘스트와 메인 브랜치로의 모든 병합 시 CI에서 자동으로 실행됩니다. 풀 리퀘스트를 위한 빠른 핵심 스위트와 야간 빌드를 위한 더 크고 느린 엔드투엔드 실행을 유지하여 커밋별 검사가 신속하게 유지되도록 하십시오.

취약한 스위트를 피하기 위해 무엇을 주장해야 하나요? 소비자가 오류를 일으킬 만한 내용에 대해 주장하십시오. 상태 코드, 응답 구조 및 유형, ID 및 상태 열거형과 같이 계약상 의미가 있는 필드의 값을 고정하십시오. 타임스탬프와 같이 요청마다 변경되는 값의 경우, 리터럴 값보다는 유형과 형식을 주장하십시오. 변동성 있는 데이터에 대해 과도하게 주장하는 것이 잘못된 실패의 주요 원인입니다.

코드를 작성하지 않고 API 회귀 테스트를 실행할 수 있나요? 예. Apidog과 같은 도구를 사용하면 시나리오와 주장을 시각적으로 구축한 다음 apidog-cli를 사용하여 CI에서 헤드리스로 실행할 수 있습니다. 인터페이스를 통해 스위트를 한 번 저장하면 명령줄 러너가 파이프라인에서 이를 다시 실행하므로, 수동으로 테스트 하네스를 작성할 필요 없이 테스트가 자동으로 실행됩니다.

의도적인 파괴적 변경은 어떻게 처리해야 하나요? 클라이언트를 놀라게 하는 테스트 실패로 나타나게 하는 대신, 버전 관리 및 사용 중단 프로세스를 통해 처리하십시오. 스키마 차이점 비교를 사용하여 검토에서 변경 사항에 플래그를 지정하고, 엔드포인트의 버전을 지정하거나 필드를 선택 사항으로 먼저 추가한 다음, 변경 사항이 의도적이고 소비자에게 전달되면 회귀 기준선을 의도적으로 업데이트하십시오.