Implementation:Langchain ai Langchain SandboxTests

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

Overview

Standard integration test suite for validating implementations of the deepagents SandboxBackendProtocol, covering file operations, command execution, and file transfer.

Description

SandboxIntegrationTests is an abstract test suite class in the langchain-tests (standard-tests) package that verifies implementations of the SandboxBackendProtocol from the deepagents library. The suite tests file write/read/edit operations, directory listing, glob pattern matching, grep functionality, file upload/download with binary roundtrip verification, and error handling for missing files, permission issues, and invalid paths. Implementers subclass this suite and provide a pytest fixture that yields a clean sandbox backend instance.

Usage

Import SandboxIntegrationTests when writing integration tests for a custom sandbox backend implementation (e.g., Docker-based, VM-based, or cloud sandbox) to ensure it conforms to the standard SandboxBackendProtocol contract.

Code Reference

Source Location

• Repository: Langchain_ai_Langchain
• File: libs/standard-tests/langchain_tests/integration_tests/sandboxes.py
• Lines: 1-403

Signature

class SandboxIntegrationTests(BaseStandardTests):
    @abstractmethod
    @pytest.fixture(scope="class")
    def sandbox(self) -> Iterator[SandboxBackendProtocol]: ...

    @property
    def has_sync(self) -> bool: ...

    @property
    def has_async(self) -> bool: ...

Import

from langchain_tests.integration_tests.sandboxes import SandboxIntegrationTests

I/O Contract

Inputs (Fixtures)

Name	Type	Required	Description
sandbox	SandboxBackendProtocol	Yes	A clean sandbox backend instance. Yielded from the abstract fixture and torn down afterward.

Configuration Properties

Name	Type	Default	Description
has_sync	bool	True	Whether the sandbox supports synchronous methods.
has_async	bool	True	Whether the sandbox supports asynchronous methods.

Outputs

Name	Type	Description
Test results	pytest outcomes	Pass/fail results for each standard test method.

Test Methods

File Operations

Test Method	Description
test_write_new_file	Writes a new file and verifies it can be read back via command execution.
test_read_basic_file	Writes a file and verifies read() returns expected contents.
test_edit_single_occurrence	Edits a file and asserts exactly one occurrence was replaced.
test_ls_info_lists_files	Creates files and verifies ls_info() lists them.
test_glob_info	Creates files and verifies glob_info() returns expected pattern matches.
test_grep_raw_literal	Verifies grep_raw() performs literal matching on special characters.

File Upload/Download

Test Method	Description
test_upload_single_file	Uploads one file and verifies its contents on the sandbox.
test_download_single_file	Uploads then downloads a file and verifies bytes match.
test_upload_download_roundtrip	Verifies bytes survive a complete upload-download roundtrip including special characters.
test_upload_multiple_files_order_preserved	Verifies that uploading multiple files preserves input order in responses.
test_download_multiple_files_order_preserved	Verifies that downloading multiple files preserves input order in responses.
test_upload_binary_content_roundtrip	Uploads and downloads binary bytes (0..255) without corruption.

Error Handling

Test Method	Description
test_download_error_file_not_found	Downloading a missing file returns error="file_not_found".
test_download_error_is_directory	Downloading a directory fails with a reasonable error code.
test_download_error_permission_denied	Downloading a chmod 000 file fails with a reasonable error code.
test_download_error_invalid_path_relative	Downloading a relative path fails with error="invalid_path".
test_upload_missing_parent_dir_or_roundtrip	Uploading into a missing parent directory either errors or creates the directory.
test_upload_relative_path_returns_invalid_path	Uploading to a relative path fails with error="invalid_path".

Usage Examples

Basic Usage

from __future__ import annotations
from collections.abc import Iterator

import pytest
from deepagents.backends.protocol import SandboxBackendProtocol
from langchain_tests.integration_tests.sandboxes import SandboxIntegrationTests

from my_pkg import make_sandbox


class TestMySandboxStandard(SandboxIntegrationTests):
    @pytest.fixture(scope="class")
    def sandbox(self) -> Iterator[SandboxBackendProtocol]:
        backend = make_sandbox()
        try:
            yield backend
        finally:
            backend.delete()