Testing

LangChain's test discipline is layered: unit tests guard against regressions, standard tests enforce cross-provider behavior, and VCR/snapshot tests pin down model output and HTTP shape.

Test directories

Every package follows the same layout:

libs/<package>/tests/
├── unit_tests/         # No network. Must be fast and deterministic.
├── integration_tests/  # Hits real APIs. Gated by API keys in CI secrets.
└── (optional) benchmark/, test_pydantic/, ...

The directory tree mirrors the package's source tree — tests/unit_tests/messages/test_ai.py tests langchain_core/messages/ai.py.

Frameworks

• pytest — the testing framework, with --strict-markers --strict-config --durations=5 --snapshot-warn-unused -vv defaults configured in each pyproject.toml.
• pytest-asyncio — asyncio_mode = "auto" is set in every package; you can write async def test_* directly.
• pytest-socket — used in unit tests to enforce no-network behavior.
• pytest-mock, responses — for mocking external services.
• syrupy — snapshot testing, common in langchain-core for serialization checks.
• vcrpy — records and replays HTTP interactions in partner integration tests.
• pytest-benchmark / pytest-codspeed — benchmarks in langchain-core.
• blockbuster — detects accidental blocking I/O in async tests.

Standard tests

libs/standard-tests/langchain_tests/ exposes reusable test suites that every partner package inherits:

• ChatModelUnitTests, ChatModelIntegrationTests — verify the chat-model contract (streaming, tool calling, structured output, token counting, error handling)
• EmbeddingsUnitTests, EmbeddingsIntegrationTests
• ToolsUnitTests, ToolsIntegrationTests
• Vector store, document loader, retriever, and cache analogues

A partner integration test typically looks like:

from langchain_tests.integration_tests import ChatModelIntegrationTests
from langchain_openai import ChatOpenAI

class TestChatOpenAIStandard(ChatModelIntegrationTests):
    @property
    def chat_model_class(self): return ChatOpenAI
    @property
    def chat_model_params(self): return {"model": "gpt-5"}

This is how the project enforces uniform behavior across 15+ partners. When langchain-core adds a new capability (say, a new content-block type), the corresponding test case is added to the standard test suite, and every partner package immediately runs it on the next CI run.

Running tests

# All unit tests for a package
make test

# A specific file or pattern
uv run --group test pytest tests/unit_tests/test_tools.py
uv run --group test pytest tests/unit_tests -k tool_calling

# Integration tests (need API keys in env)
make integration_test

# Watch mode for TDD
make test_watch

# Benchmarks (only in packages that ship them)
make benchmark

Network discipline

Unit tests must not make real network calls. The convention is to:

1. Use pytest-socket to enforce it (already wired into pyproject.toml test deps).
2. For HTTP, use responses or httpx_mock to fake the client.
3. For LLM responses, use the fake chat model in libs/core/langchain_core/language_models/fake_chat_models.py (FakeListChatModel, FakeMessagesListChatModel, GenericFakeChatModel). It returns scripted outputs so tests don't depend on a provider.

VCR cassettes

Partner integration tests often record real HTTP interactions and replay them. Cassettes live next to the test file in YAML format. The _test_vcr.yml workflow re-runs them in CI. Re-recording requires the relevant API key set in your local environment plus VCR_RECORD_MODE=new_episodes.

Coverage requirements

The CLAUDE.md checklist for new code:

• Tests fail when your new logic is broken
• Happy path is covered
• Edge cases and error conditions are tested
• Use fixtures/mocks for external dependencies
• Tests are deterministic (no flaky tests)

PR reviewers will block on missing tests for non-trivial changes.

Continuous integration

CI runs are organized in .github/workflows/:

• check_diffs.yml — picks affected packages by inspecting git diff paths
• _test.yml — unit tests across Python 3.10, 3.11, 3.12, 3.13, 3.14
• _test_pydantic.yml — exercises both Pydantic v2 minor versions
• _test_vcr.yml — replays VCR cassettes
• integration_tests.yml — runs real-API integration tests on a schedule and on demand
• codspeed.yml — performance regression detection via pytest-codspeed

A PR that breaks a partner integration's standard tests is blocked from merging until either the partner is updated or the change in langchain-core / langchain is rolled back.