지난달 저는 우리 팀의 API 테스트 어설션 (Assertions) 2,400개를 검토했습니다. 그중 91%가 세 가지 범주에 속했습니다.

그 숫자는 저를 놀라게 했습니다.

낮아서가 아닙니다.

너무 높았기 때문입니다.

저는 수십 가지의 어설션 패턴을 발견할 것이라 예상했습니다:

• 헤더 어설션 (Header assertions)
• 페이지네이션 어설션 (Pagination assertions)
• 보안 어설션 (Security assertions)
• 성능 어설션 (Performance assertions)
• 데이터베이스 검증 (Database validations)
• 커스텀 비즈니스 규칙 (Custom business rules)

하지만 대신, 우리가 작성한 거의 모든 것은 단 세 가지 버킷(buckets)으로 그룹화될 수 있었습니다.

중복된 패턴을 제거하고 어설션을 분류했을 때, 91%가 다음 항목에 해당했습니다:

1. 스키마 어설션 (Schema Assertions)
2. 아이덴티티 어설션 (Identity Assertions)
3. 사이드 이펙트 어설션 (Side-Effect Assertions)

남은 9%는요?

그들 대부분은 아마 존재해서는 안 되는 것들일 것입니다.

만약 여러분이 REST API 테스트를 구축하거나 유지 관리하고 있다면, 이 세 가지 범주를 이해하는 것만으로도 테스트에 대한 사고방식을 획기적으로 단순화할 수 있습니다.

왜 대부분의 API 테스트 스위트가 유지 관리하기 어려워지는가

많은 테스트 스위트가 유기적으로 성장합니다.

한 개발자가 다음과 같이 작성합니다:

expect(response.status).toBe(200);

다른 개발자가 다음을 추가합니다:

expect(response.body.name).toBe('John');

또 다른 누군가는 다음을 추가합니다:

expect(response.body.items.length).toBe(3);

결국 스위트에는 수천 개의 어설션이 포함됩니다.

그중 상당수는:

• 서로 중복됩니다.
• 구현 세부 사항 (implementation details)을 검증합니다.
• 신뢰도를 높이지 않으면서 유지 관리 부담만 늘립니다.

목표는 더 많은 어설션을 작성하는 것이 아닙니다.

목표는 실제로 중요한 어설션을 작성하는 것입니다.

1. 스키마 어설션 (Schema Assertions) (대부분의 테스트가 생략하는 것)

이것은 가장 과소평가된 유형의 API 어설션입니다.

스키마 어설션은 다음 질문에 답합니다:

응답이 여전히 계약 (contract)과 일치하는가?

만약 여러분의 엔드포인트가 다음과 같이 반환한다고 가정해 봅시다:

{
  "id": 123,
  "name": "John Smith",
...

내일 누군가가 이를 다음과 같이 변경합니다:

{
  "id": "123",
  "fullName": "John Smith"
...

엔드포인트는 여전히 다음과 같이 반환합니다:

200 OK

하지만 소비자(consumers)들은 즉시 오류가 발생할 수 있습니다.

이것이 바로 스키마 어설션이 중요한 이유입니다.

스키마 어설션이 검증하는 것

• 필수 필드(Required fields) 존재 여부
• 데이터 타입 (Data types)의 정확성
• 필드 누락 여부
• 배열 (Arrays)의 올바른 구조 포함 여부
• 응답 계약 (Response contracts)의 호환성 유지

JSON 스키마 어설션 (JSON Schema Assertion) 예시

expect(response.body).toMatchSchema({
  type: 'object',
  required: ['id', 'name'],
...

팀들이 이를 건너뛰는 이유

왜냐하면 다음과 같은 검증이

expect(response.status)
  .toBe(200);

충분하다고 느껴지기 때문입니다.

하지만 그렇지 않습니다.

제가 목격한 가장 큰 API 회귀(Regression)는 성공적인 응답을 반환하면서도 계약(Contract)이 변경되는 경우였습니다.

이것이 바로 JSON 스키마 어설션 (JSON schema assertion) 기술이 매우 큰 가치를 제공하는 이유입니다.

복사-붙여넣기 템플릿: 스키마 어설션 (Schema Assertion)

expect(response.body)
  .toMatchSchema(schema);

또는:

expect(response.body.id)
  .toEqual(expect.any(Number));

2. 아이덴티티 어설션 (Identity Assertions) (실제로 당신이 신경 쓰는 가치)

이것은 사람들이 "API 테스트"라는 말을 들었을 때 가장 먼저 떠올리는 범주입니다.

아이덴티티 어설션은 다음 질문에 답합니다:

API가 올바른 비즈니스 가치를 반환했는가?

예시:

{
  "discount": 20
}

계약(Contract)은 유효할 수 있습니다.

엔드포인트(Endpoint)는 200을 반환할 수도 있습니다.

하지만 기대하는 할인율이 다음과 같다면:

{
  "discount": 50
}

API는 여전히 고장 난 상태입니다.

아이덴티티 어설션이 검증하는 것

• 비즈니스 계산 (Business calculations)
• 필드 값 (Field values)
• 정렬 (Sorting)
• 필터링 (Filtering)
• 권한 부여 결정 (Authorization decisions)
• 도메인 규칙 (Domain rules)

예시

expect(response.body.discount)
  .toBe(20);

또는:

expect(response.body.status)
  .toBe('ACTIVE');

아이덴티티 어설션이 중요한 이유

고객은 값(Value)에 관심이 있습니다.

그들은 다음과 같은 내용이 유효한지에는 관심이 없습니다:

{
  "discount": {
    "type": "integer"
...

그들은 할인율이 정확한지에 관심이 있습니다.

복사-붙여넣기 템플릿: 아이덴티티 어설션 (Identity Assertion)

expect(response.body.field)
  .toBe(expectedValue);

또는:

expect(response.body)
  .toEqual(expectedObject);

3. 사이드 이펙트 어설션 (Side-Effect Assertions) (작업이 수행되었음을 증명하는 것들)

이 범주는 놀라울 정도로 자주 간과되곤 합니다.

API는 다음과 같이 반환할 수 있습니다:

200 OK

그럼에도 불구하고 완전히 실패할 수 있습니다.

다음 상황을 고려해 보세요:

POST /orders

엔드포인트(Endpoint)는 성공을 반환합니다.

하지만:

• 데이터베이스(Database) 행(row)이 생성되지 않았습니다.
• 메시지(Message)가 발행(Published)되지 않았습니다.
• 이메일(Email)이 전송되지 않았습니다.

비즈니스 프로세스(Business process)가 실패한 것입니다.

부수 효과 어설션 (Side-Effect Assertions) 검증 대상

• 데이터베이스 쓰기 (Database writes)
• 큐 메시지 (Queue messages)
• 이벤트 발행 (Event publication)
• 이메일 (Emails)
• 감사 로그 (Audit logs)
• 제3자 통합 (Third-party integrations)

데이터베이스 어설션 예시

expect(orderRepository.find(orderId))
  .not.toBeNull();

큐 어설션 예시

expect(queue.contains(orderCreatedEvent))
  .toBe(true);

부수 효과가 중요한 이유

많은 API는 오로지 다른 무언가를 트리거(Trigger)하기 위해 존재합니다.

응답(Response) 자체는 종종 가장 덜 중요한 부분입니다.

예를 들어:

POST /payments

다음과 같은 결과는 아무도 신경 쓰지 않습니다:

{
  "success": true
}

중요한 것은 다음과 같습니다:

• 결제(Payment)가 완료되었는가?
• 인보이스(Invoice)가 생성되었는가?
• 영수증(Receipt)이 전송되었는가?

복사-붙여넣기 템플릿: 부수 효과 어설션 (Side-Effect Assertion)

expect(databaseRecord)
  .toExist();

또는:

expect(publishedEvent)
  .toBeDefined();

분류에 포함되지 않은 9%

어설션을 분류한 후, 약 9%가 남았습니다.

예시는 다음과 같습니다:

expect(response.body.items.length)
  .toBe(5);

expect(response.body.createdAt)
  .toBe('2026-07-01');

expect(response.body.version)
  .toBe('1.2.8');

이들 중 상당수는 다음과 같은 특징을 가집니다:

• 취약함 (Brittle)
• 과도하게 구체적임 (Overly specific)
• 구현 세부 사항에 결합됨 (Tied to implementation details)

왜 대부분 삭제되어야 하는가

스스로에게 물어보세요:

만약 이 어설션이 내일 실패한다면, 사용자들이 실제로 알아챌까?

만약 대답이:

아마 아닐 것이다.

라면, 삭제하세요.

의미 있는 신뢰를 제공하지 못하는 어설션들로부터 놀라울 정도로 많은 유지보수 비용이 발생합니다.

나쁜 어설션 (Bad Assertions)

expect(responseTime)
  .toBe(183);

expect(itemCount)
  .toBe(17);

expect(timestamp)
  .toEqual('2026-07-28T08:00:00Z');

이러한 것들은 끊임없이 깨지는 경향이 있습니다.

더 나은 어설션 (Better Assertions)

expect(responseTime)
  .toBeLessThan(500);

expect(itemCount)
  .toBeGreaterThan(0);

expect(timestamp)
  .toBeDefined();

이러한 방식이 더 탄력적(resilient)입니다.

내가 권장하는 어설션 피라미드 (The Assertion Pyramid I Recommend)

새로운 API 테스트를 작성할 때마다, 저는 세 가지 질문을 던집니다.

첫 번째

응답이 여전히 계약(contract)과 일치하는가?

→ 스키마 어설션 (Schema Assertion).

두 번째

API가 올바른 비즈니스 가치 (business value)를 반환했는가?

→ 아이덴티티 어설션 (Identity Assertion).

세 번째

시스템이 실제로 작업을 수행했는가?

→ 사이드 이펙트 어설션 (Side-Effect Assertion).

가장 유용한 테스트들은 이 카테고리 중 적어도 하나를 포함하고 있습니다.

많은 테스트가 세 가지 모두를 포함합니다.

예시:

expect(response.body)
  .toMatchSchema(userSchema);

...

세 가지 어설션.

세 가지 서로 다른 보장.

높은 신뢰도.

낮은 유지보수 비용.

마치며 (Final Thoughts)

수천 개의 어설션을 카테고리로 분류했을 때, 우리는 중요한 사실을 깨달았습니다.

대부분의 API 테스트는 우리가 생각하는 것보다 훨씬 단순합니다.

가치 있는 어설션의 대다수는 단 세 가지 질문에만 답합니다.

1. 계약 (contract)이 여전히 유효한가?
2. 비즈니스 가치 (business value)가 정확한가?
3. 사이드 이펙트 (side effect)가 발생했는가?

그 외의 모든 것은 그 존재 이유를 증명해야 합니다.

만약 어떤 어설션이 신뢰도를 높이지 못하거나 의미 있는 회귀 (regression)로부터 보호하지 못한다면, 테스트 스위트 (suite)에 포함될 필요가 없을지도 모릅니다.

그렇기 때문에 저는 이제 모든 API 테스트를 시작할 때, 이 세 가지 카테고리 중 실제로 검증하려는 것이 무엇인지 결정하는 것부터 시작합니다.

유지보수 가능한 API 스위트를 구축하는 것에 대해 더 깊이 알고 싶다면, **REST API 테스트 베스트 프랙티스 가이드 (the REST API testing best practices guide)**를 강력히 추천합니다:

https://totalshiftleft.ai/blog/rest-api-testing-best-practices

최고의 API 테스트는 어설션이 가장 많은 테스트가 아니기 때문입니다.

올바른 어설션을 가진 테스트가 최고의 테스트입니다.