standard-tests: retriever docstrings (#28596)

libs/standard-tests/langchain_tests/base.py

@@ -10,6 +10,8 @@ class BaseStandardTests(ABC):
     def test_no_overrides_DO_NOT_OVERRIDE(self) -> None:
         """
         Test that no standard tests are overridden.
+
+        :private:
         """
         # find path to standard test implementations
         comparison_class = None

libs/standard-tests/langchain_tests/integration_tests/retrievers.py

@@ -15,27 +15,52 @@ class RetrieversIntegrationTests(BaseStandardTests):
 
     @property
     @abstractmethod
-    def retriever_constructor(self) -> Type[BaseRetriever]: ...
+    def retriever_constructor(self) -> Type[BaseRetriever]:
+        """
+        A BaseRetriever subclass to be tested.
+        """
+        ...
 
     @property
     def retriever_constructor_params(self) -> dict:
+        """
+        Returns a dictionary of parameters to pass to the retriever constructor.
+        """
         return {}
 
     @property
     @abstractmethod
     def retriever_query_example(self) -> str:
         """
-        Returns a dictionary representing the "args" of an example retriever call.
+        Returns a str representing the "query" of an example retriever call.
         """
         ...
 
     @pytest.fixture
     def retriever(self) -> BaseRetriever:
+        """
+        :private:
+        """
         return self.retriever_constructor(**self.retriever_constructor_params)
 
     def test_k_constructor_param(self) -> None:
         """
-        Test that the retriever constructor accepts a k parameter.
+        Test that the retriever constructor accepts a k parameter, representing
+        the number of documents to return.
+
+        .. dropdown:: Troubleshooting
+
+            If this test fails, either the retriever constructor does not accept a k
+            parameter, or the retriever does not return the correct number of documents
+            (`k`) when it is set.
+
+            For example, a retriever like
+
+            .. code-block:: python
+
+                    MyRetriever(k=3).invoke("query")
+
+            should return 3 documents when invoked with a query.
         """
         params = {
             k: v for k, v in self.retriever_constructor_params.items() if k != "k"
@@ -53,6 +78,24 @@ class RetrieversIntegrationTests(BaseStandardTests):
         assert all(isinstance(doc, Document) for doc in result_1)
 
     def test_invoke_with_k_kwarg(self, retriever: BaseRetriever) -> None:
+        """
+        Test that the invoke method accepts a k parameter, representing the number of
+        documents to return.
+
+        .. dropdown:: Troubleshooting
+
+            If this test fails, the retriever's invoke method does not accept a k
+            parameter, or the retriever does not return the correct number of documents
+            (`k`) when it is set.
+
+            For example, a retriever like
+
+            .. code-block:: python
+
+                MyRetriever().invoke("query", k=3)
+
+            should return 3 documents when invoked with a query.
+        """
         result_1 = retriever.invoke(self.retriever_query_example, k=1)
         assert len(result_1) == 1
         assert all(isinstance(doc, Document) for doc in result_1)
@@ -65,6 +108,12 @@ class RetrieversIntegrationTests(BaseStandardTests):
         """
         If invoked with the example params, the retriever should return a list of
         Documents.
+
+        .. dropdown:: Troubleshooting
+
+            If this test fails, the retriever's invoke method does not return a list of
+            `langchain_core.document.Document` objects. Please confirm that your
+            `_get_relevant_documents` method returns a list of `Document` objects.
         """
         result = retriever.invoke(self.retriever_query_example)
 
@@ -75,6 +124,9 @@ class RetrieversIntegrationTests(BaseStandardTests):
         """
         If ainvoked with the example params, the retriever should return a list of
         Documents.
+
+        See :meth:`test_invoke_returns_documents` for more information on
+        troubleshooting.
         """
         result = await retriever.ainvoke(self.retriever_query_example)