표준 테스트 사용하기

표준 테스트 사용하기 (Using standard tests)

표준 테스트는 내 integration이 예상대로 동작하는지를 보장해 주는 도구예요. LangChain integration을 만들거나 외부에 공개할 때, 각 integration 유형마다 통과해야 할 테스트를 직접 일일이 짜는 대신 LangChain이 제공하는 테스트 묶음을 그대로 쓰면 됩니다. 이 글에서는 integration 유형별로 표준 테스트 스위트를 어떻게 붙이는지 안내할게요.

출처: 공식문서

설정 (Setup)

먼저 필요한 의존성을 설치해요.

  • langchain-core — 커스텀 컴포넌트를 정의할 때 필요한 인터페이스
  • langchain-tests — 표준 테스트와 이를 실행하기 위한 pytest 플러그인
pip install -U langchain-core
pip install -U langchain-tests

uv를 쓴다면 이렇게요.

uv add langchain-core
uv add langchain-tests

⚠️ 새 버전의 langchain-tests에 추가된 테스트가 CI/CD 파이프라인을 깰 수 있으니, 예상치 못한 변경을 피하려면 최신 버전으로 고정(pinning)하길 권장해요.

langchain-tests 패키지에는 두 가지 네임스페이스가 있어요.

종류 위치 설명
단위 테스트 (Unit tests) langchain_tests.unit_tests 외부 서비스 접근 없이 컴포넌트만 격리해 테스트
통합 테스트 (Integration tests) langchain_tests.integration_tests 컴포넌트가 연동할 외부 서비스까지 포함해 테스트

두 종류 모두 pytest 기반의 클래스형 테스트 스위트로 구현돼 있어요.

표준 테스트 구현하기

integration 유형에 따라 단위·통합 테스트 중 필요한 것을 상속해서 구현하면 됩니다. 표준 테스트 스위트를 상속하면 해당 유형의 테스트 컬렉션을 통째로 얻게 돼요. 테스트가 성공하려면 모델이 해당 기능을 지원해야 하고, 지원하지 않으면 skip되어야 해요.

integration마다 지원하는 기능이 다르기 때문에, LangChain의 표준 테스트 대부분은 기본적으로 opt-in(선택)이에요. 즉 내 integration이 지원하는 기능을 property로 명시해 줘야 오탐(false positive)을 피할 수 있어요. 아래는 이미지 입력을 지원하는 채팅 모델을 표시하는 예시입니다.

# Indicate that a chat model supports image inputs

class TestChatParrotLinkStandard(ChatModelIntegrationTests):
    # ... other required properties

    @property
    def supports_image_inputs(self) -> bool:
        return True  # (The default is False)

테스트는 패키지 루트 기준으로 tests/unit_tests(단위), tests/integration_tests(통합) 하위 디렉토리에 정리하세요. 설정 가능한 캐퍼빌리티 전체 목록과 기본값은 API reference에서 확인할 수 있어요.

대표 integration들의 표준 테스트 구현 예시:

Sandbox 통합 (Sandbox integrations)

Deep Agents의 sandbox 통합은 langchain_tests.integration_tests의 SandboxIntegrationTests를 사용해요. 이를 상속하고 SandboxBackendProtocol 인스턴스를 yield하는 sandbox fixture를 제공하면 됩니다. 참고 구현은 Daytona integration tests를 봐 주세요. 공개 규칙은 Sandbox integration 기여를 참고하세요.

테스트 실행하기

템플릿에서 integration을 부트스트랩했다면 Makefile에 유닛·통합 테스트용 target이 포함돼 있어요.

make test
make integration_test

권장 디렉토리 구조를 따랐다면 아래처럼 직접 실행할 수도 있어요.

# Run all tests
uv run --group test pytest tests/unit_tests/
uv run --group test --group test_integration pytest -n auto tests/integration_tests/

# For certain unit tests, you may need to set certain flags and environment variables:
TIKTOKEN_CACHE_DIR=tiktoken_cache uv run --group test pytest --disable-socket --allow-unix-socket tests/unit_tests/

# Run a specific test file
uv run --group test pytest tests/integration_tests/test_chat_models.py

# Run a specific test function in a file
uv run --group test pytest tests/integration_tests/test_chat_models.py::test_chat_completions

# Run a specific test function within a class
uv run --group test pytest tests/integration_tests/test_chat_models.py::TestChatParrotLinkIntegration::test_chat_completions

문제 해결 (Troubleshooting)

사용 가능한 표준 테스트 스위트 전체 목록, 포함된 테스트, 공통 이슈 해결 방법은 Standard Tests API Reference에서 확인하세요.

더 알아보기 (Learn more)