Implementation:Langchain ai Langchain CacheIntegrationTests

Knowledge Sources	Langchain_ai_Langchain
Domains	Testing, Caching, Standard Tests
Last Updated	2026-02-11 00:00 GMT

Overview

Standard integration test suites for validating BaseCache implementations, providing both synchronous and asynchronous test classes.

Description

This module in the langchain-tests (standard-tests) package defines two test suite classes: SyncCacheTestSuite and AsyncCacheTestSuite. Both extend BaseStandardTests and provide a comprehensive set of tests for verifying the BaseCache API contract. Tests cover cache emptiness validation, update operations, cache clearing, cache hit/miss scenarios, and multi-generation storage. Implementers of custom cache backends subclass these suites and provide a cache fixture that returns an empty cache instance.

Usage

Import these test suites when developing a custom LLM caching backend and you need to verify compliance with the BaseCache interface. Subclass SyncCacheTestSuite for synchronous caches or AsyncCacheTestSuite for async-capable caches.

Code Reference

Source Location

Repository: Langchain_ai_Langchain
File: libs/standard-tests/langchain_tests/integration_tests/cache.py
Lines: 1-207

Signature

class SyncCacheTestSuite(BaseStandardTests):
    """Test suite for checking the BaseCache API of a caching layer for LLMs."""

    @abstractmethod
    @pytest.fixture
    def cache(self) -> BaseCache:
        """Get the cache class to test. The returned cache should be EMPTY."""

    def get_sample_prompt(self) -> str: ...
    def get_sample_llm_string(self) -> str: ...
    def get_sample_generation(self) -> Generation: ...
    def test_cache_is_empty(self, cache: BaseCache) -> None: ...
    def test_update_cache(self, cache: BaseCache) -> None: ...
    def test_cache_still_empty(self, cache: BaseCache) -> None: ...
    def test_clear_cache(self, cache: BaseCache) -> None: ...
    def test_cache_miss(self, cache: BaseCache) -> None: ...
    def test_cache_hit(self, cache: BaseCache) -> None: ...
    def test_update_cache_with_multiple_generations(self, cache: BaseCache) -> None: ...


class AsyncCacheTestSuite(BaseStandardTests):
    """Test suite for checking the BaseCache API (async) of a caching layer for LLMs."""

    @abstractmethod
    @pytest.fixture
    async def cache(self) -> BaseCache:
        """Get the cache class to test. The returned cache should be EMPTY."""

    def get_sample_prompt(self) -> str: ...
    def get_sample_llm_string(self) -> str: ...
    def get_sample_generation(self) -> Generation: ...
    async def test_cache_is_empty(self, cache: BaseCache) -> None: ...
    async def test_update_cache(self, cache: BaseCache) -> None: ...
    async def test_cache_still_empty(self, cache: BaseCache) -> None: ...
    async def test_clear_cache(self, cache: BaseCache) -> None: ...
    async def test_cache_miss(self, cache: BaseCache) -> None: ...
    async def test_cache_hit(self, cache: BaseCache) -> None: ...
    async def test_update_cache_with_multiple_generations(self, cache: BaseCache) -> None: ...

Import

from langchain_tests.integration_tests.cache import SyncCacheTestSuite, AsyncCacheTestSuite

I/O Contract

Abstract Fixture: cache

Name	Type	Required	Description
cache	`BaseCache`	Yes	A pytest fixture that returns an empty `BaseCache` instance for each test.

Helper Methods

Method	Return Type	Description
get_sample_prompt()	`str`	Returns `"Sample prompt for testing."`
get_sample_llm_string()	`str`	Returns `"Sample LLM string configuration."`
get_sample_generation()	`Generation`	Returns a `Generation` with text `"Sample generated text."` and generation_info.

Test Methods (SyncCacheTestSuite)

Test	Description
test_cache_is_empty	Verifies that `lookup` returns `None` on an empty cache.
test_update_cache	Verifies that `update` stores a generation and `lookup` retrieves it.
test_cache_still_empty	Verifies that the fixture provides a fresh empty cache between tests.
test_clear_cache	Verifies that `clear` removes all cached entries.
test_cache_miss	Verifies that a non-existent prompt returns `None`.
test_cache_hit	Verifies that an existing prompt returns the cached generation.
test_update_cache_with_multiple_generations	Verifies storage and retrieval of multiple `Generation` objects.

Test Methods (AsyncCacheTestSuite)

Test	Description
test_cache_is_empty	Async version: verifies `alookup` returns `None` on empty cache.
test_update_cache	Async version: verifies `aupdate` and `alookup` round-trip.
test_cache_still_empty	Async version: verifies fresh empty cache between tests.
test_clear_cache	Async version: verifies `aclear` removes cached entries.
test_cache_miss	Async version: verifies non-existent prompt returns `None`.
test_cache_hit	Async version: verifies cached generation is returned.
test_update_cache_with_multiple_generations	Async version: verifies multiple generation storage.

Usage Examples

Basic Usage

import pytest
from langchain_core.caches import BaseCache
from langchain_tests.integration_tests.cache import SyncCacheTestSuite


class TestMyCache(SyncCacheTestSuite):
    @pytest.fixture
    def cache(self) -> BaseCache:
        # Return an empty instance of your cache implementation
        return MyCustomCache()

Async Cache Testing

import pytest
from langchain_core.caches import BaseCache
from langchain_tests.integration_tests.cache import AsyncCacheTestSuite


class TestMyAsyncCache(AsyncCacheTestSuite):
    @pytest.fixture
    async def cache(self) -> BaseCache:
        cache = MyAsyncCache()
        await cache.aclear()
        return cache

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment