Implementation:Langchain ai Langchain RetrieversIntegrationTests

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

Overview

Standard integration test suite for validating BaseRetriever implementations, verifying constructor parameters, invocation behavior, and async support.

Description

RetrieversIntegrationTests is a test suite class in the langchain-tests (standard-tests) package that extends BaseStandardTests. It provides a set of integration tests for any BaseRetriever subclass, covering: constructor-level result count configuration, invoke-level result count configuration via kwargs, synchronous document retrieval, and asynchronous document retrieval. Implementers must define retriever_constructor and retriever_query_example as abstract properties and can optionally override retriever_constructor_params and num_results_arg_name.

Usage

Import this test suite when developing a custom retriever integration and you need to verify that it correctly implements the BaseRetriever interface, supports configurable result counts, and returns proper Document objects.

Code Reference

Source Location

Repository: Langchain_ai_Langchain
File: libs/standard-tests/langchain_tests/integration_tests/retrievers.py
Lines: 1-182

Signature

class RetrieversIntegrationTests(BaseStandardTests):
    """Base class for retrievers integration tests."""

    @property
    @abstractmethod
    def retriever_constructor(self) -> type[BaseRetriever]:
        """A BaseRetriever subclass to be tested."""
        ...

    @property
    def retriever_constructor_params(self) -> dict[str, Any]:
        """Returns a dictionary of parameters to pass to the retriever constructor."""
        ...

    @property
    @abstractmethod
    def retriever_query_example(self) -> str:
        """Returns a str representing the query of an example retriever call."""
        ...

    @property
    def num_results_arg_name(self) -> str:
        """Returns the name of the parameter for the number of results returned."""
        ...

    @pytest.fixture
    def retriever(self) -> BaseRetriever:
        ...

    def test_k_constructor_param(self) -> None: ...
    def test_invoke_with_k_kwarg(self, retriever: BaseRetriever) -> None: ...
    def test_invoke_returns_documents(self, retriever: BaseRetriever) -> None: ...
    async def test_ainvoke_returns_documents(self, retriever: BaseRetriever) -> None: ...

Import

from langchain_tests.integration_tests.retrievers import RetrieversIntegrationTests

I/O Contract

Abstract Properties (Must Override)

Name	Type	Required	Description
retriever_constructor	`type[BaseRetriever]`	Yes	The `BaseRetriever` subclass to test.
retriever_query_example	`str`	Yes	An example query string for testing retrieval.

Optional Properties

Name	Type	Required	Description
retriever_constructor_params	`dict[str, Any]`	No	Constructor parameters for the retriever. Defaults to empty dict.
num_results_arg_name	`str`	No	Name of the parameter controlling result count. Defaults to `"k"`.

Test Methods

Test	Description
test_k_constructor_param	Verifies the retriever accepts a result count parameter in the constructor and returns the correct number of `Document` objects (tests with k=3 and k=1).
test_invoke_with_k_kwarg	Verifies that `invoke` accepts a result count as a keyword argument and returns the correct number of documents.
test_invoke_returns_documents	Verifies that `invoke` returns a list of `Document` objects.
test_ainvoke_returns_documents	Verifies that `ainvoke` returns a list of `Document` objects.

Usage Examples

Basic Usage

from typing import Any

import pytest
from langchain_core.retrievers import BaseRetriever
from langchain_tests.integration_tests.retrievers import RetrieversIntegrationTests


class TestMyRetriever(RetrieversIntegrationTests):
    @property
    def retriever_constructor(self) -> type[BaseRetriever]:
        return MyCustomRetriever

    @property
    def retriever_constructor_params(self) -> dict[str, Any]:
        return {"api_key": "test-key", "k": 5}

    @property
    def retriever_query_example(self) -> str:
        return "What is the capital of France?"

Skipping Unsupported Tests

import pytest
from langchain_tests.integration_tests.retrievers import RetrieversIntegrationTests


class TestMyRetriever(RetrieversIntegrationTests):
    @property
    def retriever_constructor(self):
        return MyRetriever

    @property
    def retriever_query_example(self) -> str:
        return "example query"

    @pytest.mark.xfail(
        reason="This retriever doesn't support setting "
        "the number of results via the constructor."
    )
    def test_k_constructor_param(self) -> None:
        raise NotImplementedError

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment