Flask 테스트, responses httpretty 모킹과 계약 테스트 완벽 가이드

🔗 Flask 테스트 전략 개요와 용어 정리

Flask로 애플리케이션을 개발할 때 테스트 전략은 단순히 동작 여부를 확인하는 수준을 넘어, 서비스의 품질과 안정성을 유지하는 핵심 요소로 작동합니다.
특히 외부 API나 데이터베이스처럼 환경에 따라 결과가 달라질 수 있는 부분은 신뢰성 있는 테스트를 만들기 위해 반드시 별도의 접근이 필요합니다.
이 지점에서 등장하는 개념이 모킹(Mock)과 계약 테스트(Contract Test)입니다.

먼저 모킹은 실제 API를 호출하지 않고 가짜 응답을 반환하도록 흉내 내는 기법을 의미합니다.
이 과정에서 네트워크 지연이나 서드파티 장애 같은 외부 요인에 영향을 받지 않고 일관된 테스트 환경을 보장할 수 있습니다.
반대로 계약 테스트는 소비자(Consumer, 예: Flask 백엔드)와 제공자(Provider, 예: 외부 API) 사이에 약속된 요청과 응답 구조가 잘 지켜지고 있는지를 검증합니다.
즉, 단순히 ‘동작한다’는 사실이 아니라, ‘합의된 인터페이스에 맞게 동작한다’는 사실을 보장하는 것이죠.

📌 단위 테스트, 통합 테스트, 계약 테스트 차이

테스트는 범위와 목적에 따라 여러 종류로 나뉩니다.
Flask 애플리케이션에서도 다음 구분을 명확히 이해하는 것이 중요합니다.

• 🧩단위 테스트 → 특정 함수나 메서드 같은 작은 단위를 검증
• 🔗통합 테스트 → 여러 모듈을 연결해 실제 요청-응답 흐름을 검증
• 📜계약 테스트 → 소비자와 제공자 간의 데이터 교환 규약이 지켜지는지 확인

즉, 단위 테스트와 통합 테스트가 내부 로직과 플로우를 검증한다면, 계약 테스트는 외부와의 연결 규칙이 유지되는지를 담보하는 역할을 합니다.
Flask 프로젝트에서는 세 가지를 모두 적절히 조합해 신뢰할 수 있는 테스트 환경을 마련하는 것이 이상적입니다.

🛠️ 외부 서비스 모킹 responses와 httpretty 비교

외부 API를 호출하는 코드를 테스트할 때는 실제 네트워크 요청을 보내지 않고 모킹(Mock)을 활용하는 것이 일반적입니다.
파이썬 생태계에서는 대표적으로 responses와 httpretty라는 두 가지 라이브러리가 널리 쓰입니다.
둘 다 HTTP 요청을 가로채고 미리 정의된 응답을 반환하는 기능을 제공하지만, 동작 방식과 장단점에는 차이가 있습니다.

📌 responses의 특징

responses는 requests 라이브러리에 특화된 모킹 도구입니다.
데코레이터나 컨텍스트 매니저로 간단히 HTTP 요청을 가로챌 수 있으며, 요청 메서드, URL, 응답 코드, 헤더, JSON 데이터를 직관적으로 지정할 수 있습니다.
테스트 코드가 깔끔하고 유지보수하기 좋다는 장점이 있습니다.

import requests
import responses

@responses.activate
def test_get_user():
    responses.add(
        responses.GET,
        "https://api.example.com/user/1",
        json={"id": 1, "name": "Alice"},
        status=200
    )

    resp = requests.get("https://api.example.com/user/1")
    assert resp.json()["name"] == "Alice"

📌 httpretty의 특징

httpretty는 requests뿐 아니라 urllib 계열 라이브러리까지 폭넓게 지원하는 범용 HTTP 모킹 도구입니다.
소켓 레벨에서 요청을 가로채므로 더 강력하지만, 이로 인해 디버깅이 다소 까다롭고 특정 환경에서는 충돌이 발생할 수도 있습니다.
레거시 코드나 다양한 HTTP 클라이언트를 테스트할 때 특히 유용합니다.

⚙️ Flask에서 responses 사용 예제와 주의점

Flask 프로젝트에서 responses 라이브러리를 활용하면, 외부 API 요청을 깔끔하게 모킹할 수 있습니다.
특히 requests 모듈과 결합해 사용하는 경우 코드 가독성이 뛰어나며, 실제 요청-응답 로직을 그대로 유지하면서 테스트 안정성을 확보할 수 있습니다.

📌 Flask 라우트 테스트 예제

아래 예시는 Flask 앱에서 외부 API를 호출하는 라우트를 responses로 테스트하는 코드입니다.
실제 API를 호출하지 않고도 JSON 응답을 받아 기능을 검증할 수 있습니다.

from flask import Flask, jsonify
import requests
import responses

app = Flask(__name__)

@app.route("/weather")
def get_weather():
    resp = requests.get("https://api.weather.com/today")
    return jsonify(resp.json())

@responses.activate
def test_get_weather(client):
    responses.add(
        responses.GET,
        "https://api.weather.com/today",
        json={"temp": 22, "condition": "sunny"},
        status=200
    )

    response = client.get("/weather")
    assert response.status_code == 200
    assert response.get_json()["temp"] == 22

📌 responses 사용 시 주의할 점

responses는 강력하지만, 몇 가지 주의할 점이 있습니다.

• ⏱️요청 순서 → responses는 등록된 순서대로 요청을 매칭하므로 순서가 중요합니다.
• 🔐외부 네트워크 차단 → 기본적으로 등록되지 않은 요청은 에러를 발생시켜 예상치 못한 외부 호출을 막아줍니다.
• 🧹테스트 간 독립성 → responses 활성화 범위를 컨텍스트 매니저나 데코레이터로 한정해 테스트 간 영향을 줄여야 합니다.

🔌 httpretty로 레거시 코드 테스트하기

레거시 Flask 프로젝트에서는 urllib이나 http.client 같은 오래된 HTTP 클라이언트를 사용하는 경우가 많습니다.
이럴 때는 httpretty가 유용합니다.
httpretty는 소켓 레벨에서 HTTP 요청을 가로채므로 requests뿐 아니라 다양한 클라이언트 라이브러리를 지원합니다.
덕분에 기존 코드를 수정하지 않고도 테스트를 작성할 수 있습니다.

📌 httpretty 기본 사용법

httpretty는 @httpretty.activate 데코레이터를 사용하거나 enable(), disable() 메서드로 직접 활성화/비활성화할 수 있습니다.
테스트 대상 URL과 응답을 사전에 등록하면, 실제 네트워크 호출 대신 등록된 응답을 반환합니다.

import httpretty
import urllib.request

@httpretty.activate
def test_old_client():
    httpretty.register_uri(
        httpretty.GET,
        "https://api.legacy.com/data",
        body='{"status": "ok"}',
        content_type="application/json"
    )

    resp = urllib.request.urlopen("https://api.legacy.com/data")
    content = resp.read().decode("utf-8")
    assert "ok" in content

📌 httpretty 활용 시 유용한 포인트

httpretty를 사용할 때는 단순 모킹뿐 아니라 다양한 상황을 재현할 수 있습니다.
예를 들어, 지연 시간 추가, 예외 응답 반환, 다중 URL 패턴 매칭 등이 가능합니다.
이런 기능은 외부 서비스가 불안정할 때 애플리케이션의 복원력을 검증하는 데 유용합니다.

• ⏳지연 시뮬레이션 → 특정 요청에 의도적으로 응답 지연을 추가해 타임아웃 처리 검증
• ❌에러 응답 처리 → 500, 404 등 다양한 상태 코드를 테스트해 예외 핸들링 확인
• 🌐여러 URL 패턴 → 동일한 도메인에 여러 엔드포인트를 등록해 다양한 케이스를 재현

💡 계약 테스트 소개와 Flask 백엔드 적용 패턴

외부 API와 연동되는 Flask 애플리케이션에서 단순 모킹만으로는 모든 문제를 예방하기 어렵습니다.
API 제공자가 필드명을 바꾸거나 응답 스키마를 수정하면 테스트는 통과하지만 실제 배포 환경에서 에러가 발생할 수 있습니다.
이런 상황을 막기 위한 방법이 바로 계약 테스트(Contract Test)입니다.

📌 계약 테스트란 무엇인가?

계약 테스트는 서비스 소비자(Consumer)와 제공자(Provider) 간의 약속된 인터페이스가 올바르게 지켜지는지를 검증하는 테스트 방식입니다.
예를 들어, Flask 백엔드가 외부 결제 API를 호출한다고 할 때, 요청 포맷과 응답 JSON 구조를 명시적으로 문서화하고 이를 테스트로 보장합니다.
이 과정을 통해 API가 변경되더라도 미리 깨짐을 감지하고 협업 과정에서 오류를 줄일 수 있습니다.

📌 Flask에 계약 테스트 적용 패턴

Flask에서 계약 테스트를 적용할 때는 보통 PACT 같은 툴을 활용합니다.
PACT는 소비자와 제공자 간의 계약을 JSON 파일로 관리하며, 이 파일을 기반으로 실제 API와의 호환성을 자동으로 검증합니다.
테스트 파이프라인에 통합하면 코드 변경이나 외부 API 버전 업그레이드 시 빠르게 문제를 탐지할 수 있습니다.

from pact import Consumer, Provider

pact = Consumer("FlaskApp").has_pact_with(Provider("PaymentAPI"))

def test_create_payment():
    expected = {
        "amount": 100,
        "currency": "USD",
        "status": "success"
    }

    (pact
     .given("payment service is available")
     .upon_receiving("a request to create a payment")
     .with_request("post", "/payments", body={"amount": 100, "currency": "USD"})
     .will_respond_with(200, body=expected))

    with pact:
        result = create_payment(100, "USD")
        assert result["status"] == "success"

❓ 자주 묻는 질문 (FAQ)