From b7c2029e840915b8d4f80eae715cfdf594e61830 Mon Sep 17 00:00:00 2001
From: Erick Friis <erick@langchain.dev>
Date: Fri, 6 Dec 2024 15:14:52 -0800
Subject: [PATCH] standard-tests: root docstrings (#28595)

---
 .../integration_tests/retrievers.py           |  4 ++++
 .../integration_tests/tools.py                | 24 ++++++++++++++++++-
 .../integration_tests/vectorstores.py         |  2 +-
 .../langchain_tests/unit_tests/tools.py       |  9 ++++---
 4 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/libs/standard-tests/langchain_tests/integration_tests/retrievers.py b/libs/standard-tests/langchain_tests/integration_tests/retrievers.py
index cf55e62f468ae..fa23d26674256 100644
--- a/libs/standard-tests/langchain_tests/integration_tests/retrievers.py
+++ b/libs/standard-tests/langchain_tests/integration_tests/retrievers.py
@@ -9,6 +9,10 @@
 
 
 class RetrieversIntegrationTests(BaseStandardTests):
+    """
+    Base class for retrievers integration tests.
+    """
+
     @property
     @abstractmethod
     def retriever_constructor(self) -> Type[BaseRetriever]: ...
diff --git a/libs/standard-tests/langchain_tests/integration_tests/tools.py b/libs/standard-tests/langchain_tests/integration_tests/tools.py
index 4987626037863..2fcd610ccc052 100644
--- a/libs/standard-tests/langchain_tests/integration_tests/tools.py
+++ b/libs/standard-tests/langchain_tests/integration_tests/tools.py
@@ -5,9 +5,21 @@
 
 
 class ToolsIntegrationTests(ToolsTests):
+    """
+    Base class for tools integration tests.
+    """
+
     def test_invoke_matches_output_schema(self, tool: BaseTool) -> None:
         """
         If invoked with a ToolCall, the tool should return a valid ToolMessage content.
+
+        If you have followed the `custom tool guide <https://python.langchain.com/docs/how_to/custom_tools/>`_,
+        this test should always pass because ToolCall inputs are handled by the
+        :class:`langchain_core.tools.BaseTool` class.
+
+        If you have not followed this guide, you should ensure that your tool's
+        `invoke` method returns a valid ToolMessage content when it receives
+        a dict representing a ToolCall as input (as opposed to distinct args).
         """
         tool_call = ToolCall(
             name=tool.name,
@@ -36,6 +48,8 @@ def test_invoke_matches_output_schema(self, tool: BaseTool) -> None:
     async def test_async_invoke_matches_output_schema(self, tool: BaseTool) -> None:
         """
         If ainvoked with a ToolCall, the tool should return a valid ToolMessage content.
+
+        For debugging tips, see :meth:`test_invoke_matches_output_schema`.
         """
         tool_call = ToolCall(
             name=tool.name,
@@ -65,12 +79,20 @@ def test_invoke_no_tool_call(self, tool: BaseTool) -> None:
         """
         If invoked without a ToolCall, the tool can return anything
         but it shouldn't throw an error
+
+        If this test fails, your tool may not be handling the input you defined
+        in `tool_invoke_params_example` correctly, and it's throwing an error.
+
+        This test doesn't have any checks. It's just to ensure that the tool
+        doesn't throw an error when invoked with a dictionary of kwargs.
         """
         tool.invoke(self.tool_invoke_params_example)
 
     async def test_async_invoke_no_tool_call(self, tool: BaseTool) -> None:
         """
-        If invoked without a ToolCall, the tool can return anything
+        If ainvoked without a ToolCall, the tool can return anything
         but it shouldn't throw an error
+
+        For debugging tips, see :meth:`test_invoke_no_tool_call`.
         """
         await tool.ainvoke(self.tool_invoke_params_example)
diff --git a/libs/standard-tests/langchain_tests/integration_tests/vectorstores.py b/libs/standard-tests/langchain_tests/integration_tests/vectorstores.py
index 0ffab430939cc..71ec7d8bfbab1 100644
--- a/libs/standard-tests/langchain_tests/integration_tests/vectorstores.py
+++ b/libs/standard-tests/langchain_tests/integration_tests/vectorstores.py
@@ -15,7 +15,7 @@
 
 
 class VectorStoreIntegrationTests(BaseStandardTests):
-    """Test suite for checking the read-write API of a vector store.
+    """Base class for checking the read-write API of a vector store.
 
     Implementers should subclass this test suite and provide a fixture
     that returns an empty vector store for each test.
diff --git a/libs/standard-tests/langchain_tests/unit_tests/tools.py b/libs/standard-tests/langchain_tests/unit_tests/tools.py
index d674dfe4f48f0..bdc2df1c9fb62 100644
--- a/libs/standard-tests/langchain_tests/unit_tests/tools.py
+++ b/libs/standard-tests/langchain_tests/unit_tests/tools.py
@@ -1,8 +1,3 @@
-"""
-.. autosummary::
-    :exclude-members: ToolsTests
-"""
-
 import os
 from abc import abstractmethod
 from typing import Tuple, Type, Union
@@ -64,6 +59,10 @@ def tool(self) -> BaseTool:
 
 
 class ToolsUnitTests(ToolsTests):
+    """
+    Base class for tools unit tests.
+    """
+
     @property
     def init_from_env_params(self) -> Tuple[dict, dict, dict]:
         """Return env vars, init args, and expected instance attrs for initializing