90초 만에 OpenAPI 명세에서 실행 가능한 테스트 스위트 구축하기 - 가이드

시간을 측정해 보았습니다: Petstore-clone openapi.yaml 파일을 도구에 붙여넣은 후, 로컬 모의 서버(mock)를 대상으로 생성된 41개의 테스트가 통과하는 것을 확인하기까지 단 87초가 걸렸습니다.

이 수치는 저를 놀라게 했습니다.

많은 엔지니어와 마찬가지로, 저 또한 수년간 수동으로 API 테스트를 구축하며 시간을 보냈습니다. 성숙한 프레임워크를 사용하더라도, 프로세스는 대개 문서를 읽고, 엔드포인트(endpoint)를 이해하며, 테스트 데이터를 생성하고, 어설션(assertion)을 작성하고, 인증(authentication)을 처리한 다음, API가 진화함에 따라 이 모든 것을 유지 관리하는 과정을 포함합니다.

**OpenAPI 테스트 생성 (openapi test generation)**에 대한 약속은 수년 동안 존재해 왔지만, 대부분의 구현체는 가치가 낮은 보일러플레이트(boilerplate) 코드를 생성하거나, 너무 많은 수동 설정이 필요하여 시간 절약 효과가 사라지곤 합니다.

이 가이드는 실제 실험 과정을 기록합니다: 간단한 OpenAPI 명세를 가져와 90초 이내에 실행 가능한 API 테스트 스위트로 변환하는 과정입니다.

내가 시작한 4줄짜리 openapi.yaml

엄밀히 말하면, 전체 명세가 네 줄 길었던 것은 아닙니다. 실제 OpenAPI 파일에는 모든 엔드포인트 정의, 스키마(schema), 그리고 응답(response)이 포함되어 있었습니다.

하지만 사용자 관점에서 프로세스는 본질적으로 다음과 같이 간단했습니다:

openapi: 3.0.3
info:
  title: "Petstore Clone"
...

저는 완성된 OpenAPI 문서를 생성기에 업로드했습니다.

명세에는 다음 내용이 포함되어 있었습니다:

• 12개의 엔드포인트 (endpoints)
• 반려동물(pets)에 대한 CRUD 작업
• 사용자 관리 엔드포인트
• 검색 및 필터링 작업
• 표준 HTTP 응답 정의
• 인증 요구 사항
• JSON 스키마 (JSON schema) 정의

특별히 복잡한 것은 없었습니다.

목표는 엣지 케이스(edge cases)로 시스템을 시험하는 것이 아니었습니다. 대신, 현대적인 OpenAPI에서 테스트로 (openapi to tests) 이어지는 도구가 실제 팀에서 사용할 만한 실용적인 테스트 스위트를 생성할 수 있는지 평가하고 싶었습니다.

업로드 프로세스는 단 몇 초밖에 걸리지 않았습니다.

그다음 흥미로운 부분이 시작되었습니다.

생성기가 추론한 것 vs 나에게 입력을 요구한 것

자동화된 테스트 생성에서 가장 큰 우려 사항 중 하나는 설정 오버헤드(configuration overhead)입니다.

많은 도구들이 자동화를 광고하지만, 사용자에게 즉시 수십 개의 설정 화면을 제시합니다.

이 경우, 생성기(generator)는 다음과 같은 사항들을 성공적으로 추론했습니다:

엔드포인트 커버리지 (Endpoint Coverage)

생성기는 다음 항목들을 자동으로 식별했습니다:

• GET 엔드포인트 (GET endpoints)
• POST 엔드포인트 (POST endpoints)
• PUT 작업 (PUT operations)
• DELETE 작업 (DELETE operations)
• 쿼리 파라미터 (Query parameters)
• 경로 파라미터 (Path parameters)

수동 매핑(manual mapping)은 전혀 필요하지 않았습니다.

요청 페이로드 (Request Payloads)

OpenAPI 스키마 (schemas)에는 이미 유효한 요청 본문 (request bodies)이 기술되어 있었습니다.

생성기는 해당 스키마를 사용하여 현실적인 페이로드 (payload) 예시를 생성했습니다.

예를 들어, 다음과 같이 생성하는 대신:

{
  "name": "string"
}

실제 요청과 더 유사한 구조화된 테스트 데이터 (structured test data)를 생성했습니다.

응답 검증 (Response Validation)

도구는 다음 항목들을 자동으로 추출했습니다:

• 예상 상태 코드 (Expected status codes)
• 응답 스키마 정의 (Response schema definitions)
• 필수 속성 (Required properties)
• 데이터 타입 (Data types)

이것이 생성된 어설션 (assertions)의 기반이 되었습니다.

인증 요구사항 (Authentication Requirements)

명세서 (specification)에는 베어러 토큰 인증 (bearer token authentication)이 포함되어 있었습니다.

생성기는 이 요구사항을 즉시 인식했습니다.

나에게 요구한 사항

높은 수준의 자동화에도 불구하고, 몇 가지 입력 사항에는 여전히 사람의 개입이 필요했습니다.

환경 URL (Environment URL)

생성기는 API가 어디에서 실행되고 있는지 알 수 없었습니다.

나는 모의 서버 (mock server)를 위해 다음을 제공했습니다:

인증 값 (Authentication Values)

명세서는 인증 메커니즘을 기술했지만, 실제 자격 증명 (credentials)은 기술하지 않았습니다.

나는 샘플 토큰을 입력했습니다.

동적 테스트 데이터 (Dynamic Test Data)

몇몇 엔드포인트는 리소스가 먼저 생성되어야 하는 것에 의존했습니다.

생성기는 합리적인 기본값 (defaults)을 제안했지만, 나는 일관성을 보장하기 위해 이러한 관계들을 검토했습니다.

전반적으로 수동 설정은 1분도 채 걸리지 않았습니다.

그 균형은 적절하게 느껴졌습니다.

시스템은 명세서로부터 구조적 정보를 처리하는 동시에, 환경 특화적인 세부 사항은 사용자에게 맡겼습니다.

내가 작성하는 것을 잊었을 법한, 생성된 3가지 테스트

가장 가치 있는 부분은 뻔한 해피 패스 (happy-path) 테스트를 생성하는 것이 아니었습니다.

어떤 엔지니어라도 다음과 같은 것은 작성할 수 있습니다:

• Pet 생성 (Create Pet)
• Pet 조회 (Get Pet)
• Pet 수정 (Update Pet)
• Pet 삭제 (Delete Pet)

진정한 가치는 수동 구현 과정에서 자주 누락되는 테스트에서 나왔습니다.

1. 유효하지 않은 열거형 값 (Invalid Enum Values)

한 엔드포인트는 다음과 같은 반려동물 상태 (pet status) 값을 허용했습니다:

{
  "status": "available"
}

명세서(specification)에는 허용되는 열거형 (enum) 값들이 정의되어 있었습니다.

제너레이터는 유효하지 않은 값을 제출하는 네거티브 테스트 (negative tests)를 자동으로 생성했습니다.

예시에는 다음과 같은 내용이 포함되었습니다:

{
  "status": "invalid-status"
}

그리고 적절한 유효성 검사 (validation) 응답을 확인했습니다.

이것이 바로 많은 팀이 작성하려고 의도하지만, 우선순위에서 밀려 거의 작성하지 못하는 바로 그 유형의 테스트입니다.

2. 필수 필드 누락 (Missing Required Fields)

스키마 (schema)는 여러 속성 (properties)을 필수 (required)로 표시했습니다.

제너레이터는 각 필수 속성을 체계적으로 제거하며 서버의 동작을 확인했습니다.

예시에는 다음과 같은 내용이 포함되었습니다:

• 이름 (name) 누락
• 카테고리 (category) 누락
• 식별자 (identifier) 누락

하나의 일반적인 유효성 검사 테스트를 만드는 대신, 여러 개의 타겟팅된 시나리오를 생성했습니다.

이를 통해 테스트 커버리지 (coverage)가 크게 향상되었습니다.

3. 경계 조건 테스트 (Boundary Condition Testing)

한 검색 엔드포인트는 페이지 크기 (page size) 파라미터를 허용했습니다.

제너레이터는 OpenAPI 명세서로부터 숫자 제약 조건 (numeric constraints)을 식별하고 경계값 주변의 테스트를 생성했습니다.

예시에는 다음과 같은 내용이 포함되었습니다:

• 최솟값 (Minimum values)
• 최댓값 (Maximum values)
• 허용 범위를 살짝 벗어난 값들 (Values just outside accepted ranges)

경계값 테스트 (Boundary testing)는 종종 가치 높은 결함을 발견해내지만, 추가적인 노력이 필요하기 때문에 흔히 간과되곤 합니다.

생성된 테스트 스위트 (suite)에는 이러한 케이스들이 자동으로 포함되었습니다.

이 세 가지 카테고리만으로도 이번 실험의 가치는 충분했습니다.

모의 서버(Mock) 및 실제 서비스에 대한 스위트 실행

생성된 스위트는 먼저 모의 서버 (mock server)를 대상으로 실행되었습니다.

이를 통해 즉각적인 피드백을 얻을 수 있었습니다.

1단계: 모의 검증 (Mock Validation)

모의 서비스 대상 실행 결과:

• 41개 테스트 실행
• 41개 테스트 통과

이를 통해 다음 사항들이 검증되었습니다:

• 엔드포인트 정의가 정확함
• 요청 구조 (request structures)가 명세와 일치함
• 생성된 단언문 (assertions)이 문서화된 응답과 일치함

전체 과정은 단 몇 초밖에 걸리지 않았습니다.

이 단계에서 우리는 애플리케이션 로직 (application logic)을 테스트하고 있었던 것이 아닙니다.

우리는 계약 준수 (contract compliance)를 테스트하고 있었습니다.

이는 중요한 차이점입니다.

2단계: 실제 서비스 검증 (Real Service Validation)

다음으로, 저는 동일한 테스트 스위트를 실행 중인 구현체 (implementation)를 대상으로 지정했습니다.

여기서부터 상황이 더 흥미로워졌습니다.

몇몇 테스트가 구현체와 문서 사이의 불일치를 드러냈습니다.

예시는 다음과 같습니다:

• 응답 속성 (response properties) 누락
• 잘못된 상태 코드 (status codes)
• 명세와 다른 검증 동작 (validation behavior)

이 중 어느 것도 치명적인 문제는 아니었습니다.

하지만, 이것들은 시간이 흐르면서 축적되는 전형적인 드리프트 (drift) 유형을 나타냈습니다.

생성된 테스트들은 이러한 차이점들을 즉각적으로 강조해 주었습니다.

이는 swagger에서 api 테스트 생성하기 (generate api tests from swagger) 워크플로우의 가장 강력한 유스케이스 중 하나를 입증했습니다:

구현 동작을 문서화된 계약 (documented contracts)과 일치하게 유지하는 것.

OpenAPI 코드 생성 (Code Generation)이 가장 도움이 되는 부분

많은 팀이 이미 OpenAPI codegen을 사용하여 다음을 생성하고 있습니다:

• SDK
• 클라이언트 라이브러리 (Client libraries)
• 서버 스텁 (Server stubs)
• 문서화 (Documentation)

테스트 생성은 동일한 철학의 자연스러운 확장입니다.

명세에는 이미 다음 내용이 포함되어 있습니다:

• 엔드포인트 정의 (Endpoint definitions)
• 파라미터 (Parameters)
• 스키마 (Schemas)
• 제약 조건 (Constraints)
• 인증 모델 (Authentication models)

왜 팀들이 테스트 프레임워크 내부에서 이러한 지식을 수동으로 다시 만들어야 할까요?

명세로부터 직접 테스트를 생성함으로써, 팀은 중복을 줄이고 일관성을 개선할 수 있습니다.

생성된 스위트는 단일 진실 공급원 (single source of truth)으로부터 파생된 또 다른 산출물 (artifact)이 됩니다.

API가 진화함에 따라, 테스트를 재생성하는 것은 수동으로 작성된 방대한 양의 상용구 코드 (boilerplate)를 유지 관리하는 것보다 훨씬 쉬워집니다.

생성기가 여전히 틀리는 부분 (그리고 해결 방법)

완벽한 자동화 도구는 없습니다.

이 도구 역시 마찬가지입니다.

제가 직면했던 가장 큰 한계점들은 다음과 같습니다.

비즈니스 로직 이해 (Business Logic Understanding)

생성기는 구조를 이해합니다.

하지만 의도 (intent)를 이해하지는 못합니다.

예를 들어:

할인 API는 다음과 같은 사항을 요구할 수 있습니다:

• Gold 고객은 20%를 받습니다.
• Silver 고객은 10%를 받습니다.
• 신규 고객은 5%를 받습니다.

OpenAPI 명세 (specification)에는 이러한 규칙이 포함되는 경우가 드뭅니다.

그 결과, 생성기 (generator)는 의미 있는 비즈니스 검증 (business-validation) 테스트를 자동으로 생성할 수 없습니다.

우회 방법 (Workaround)

생성된 테스트를 기본 계층 (baseline layer)으로 사용하세요.

그 위에 커스텀 비즈니스 규칙 (business-rule) 테스트를 추가하십시오.

생성된 테스트 스위트 (suites)를 다음 항목에 대한 커버리지 (coverage)로 생각하십시오:

• 계약 (Contracts)
• 검증 (Validation)
• 인증 (Authentication)
• 데이터 타입 (Data types)
• 응답 스키마 (Response schemas)

도메인 특화 동작 (domain-specific behavior)은 수동으로 작성된 테스트에 유지하십시오.

복잡한 워크플로우 시나리오 (Complex Workflow Scenarios)

다단계 비즈니스 여정 (business journeys)은 여전히 까다로운 과제로 남아 있습니다.

예를 들어:

1. 계정 생성
2. 이메일 인증
3. 구독 구매
4. 플랜 업그레이드
5. 환불 요청

생성기는 이 흐름의 조각들을 생성할 수는 있지만, 전체 라이프사이클 (lifecycle)을 올바르게 조립하지 못할 수도 있습니다.

우회 방법 (Workaround)

먼저 기초적인 엔드포인트 (endpoint) 테스트를 생성하십시오.

그런 다음, 생성된 자산 (assets)을 재사용 가능한 컴포넌트 (components)로 사용하여 워크플로우 테스트를 구축하십시오.

테스트 데이터 의미론 (Test Data Semantics)

생성된 페이로드 (payloads)는 구조적으로는 유효합니다.

하지만 항상 논리적으로 의미가 있는 것은 아닙니다.

예를 들어:

{
  "firstName": "Test",
  "email": "abc@example.com"
...

은 기술적으로 유효합니다.

하지만 실제 운영 시나리오 (production scenarios)에서는 종종 더 정교한 데이터셋 (datasets)이 필요합니다.

우회 방법 (Workaround)

생성 후에는 생성된 픽스처 데이터 (fixture data)를 재사용 가능한 테스트 데이터 라이브러리 (test data libraries)로 교체하십시오.

이렇게 하면 자동화를 유지하면서도 현실성을 높일 수 있습니다.

마치며

프로세스 시간을 측정하고, 생성된 스위트를 검토하며, 모의 서비스 (mock services)와 실제 서비스 모두에 대해 실행해 본 결과, 저의 결론은 명확합니다:

OpenAPI 기반 테스트 생성은 더 이상 신기한 기술이 아닙니다. 이는 기본 API 커버리지를 빠르게 구축하는 실용적인 방법이 되고 있습니다.

이것이 숙련된 QA 엔지니어를 대체할까요?

아니요.

이것이 커스텀 테스트의 필요성을 없앨까요?

절대 아닙니다.

하지만 명세 (specification)가 이미 존재한다면, 수십 개의 반복적인 계약 검증 (contract-validation) 테스트를 수동으로 만드는 것은 더 이상 엔지니어링 시간을 가장 효율적으로 사용하는 방법처럼 느껴지지 않습니다.

가장 강력한 결과는 41개의 테스트가 자동으로 생성되었다는 점이 아니었습니다.

가장 강력한 결과는 그 41개의 테스트가 문서(documentation)와 구현(implementation) 사이의 간극을 즉각적으로 드러냈으며, 제가 아마도 미루거나 잊어버렸을 여러 시나리오를 커버했다는 점입니다.

만약 여러분이 자신의 API를 위해 **OpenAPI 테스트 생성 (openapi test generation)**을 탐색하고 있다면, 명세(specifications)를 실행 가능한 스위트(suites)로 직접 변환하는 현대적인 접근 방식들을 평가해 볼 가치가 있습니다.

OpenAPI 테스트 자동화 페이지에서 더 자세히 알아보세요: https://totalshiftleft.ai/openapi-test-automation

API 계약(contract)에 이미 지식이 포함되어 있다면, 자동화가 테스트 스위트의 첫 번째 버전을 구축하도록 맡기는 것이 점점 더 명백한 선택이 되고 있습니다.