This document describes the testing infrastructure for the Codex Rust codebase, including test organization, key testing tools, support utilities, and patterns for writing tests. For development environment setup, see 9.1 For code organization patterns and conventions, see 9.3
The Codex test infrastructure is built around cargo nextest as the primary test runner, with snapshot testing (via insta) for output validation and HTTP/WebSocket mocking (via wiremock and tokio-tungstenite) for integration tests. Tests are organized into unit tests (inline with source files), integration tests (in tests/ directories), and test support crates that provide reusable fixtures, mocks, and utilities.
The testing approach emphasizes:
tempfile::TempDir and mock servers to avoid external dependencies codex-rs/core/tests/common/test_codex.rs57-58core_test_support reduce boilerplate codex-rs/core/tests/common/lib.rs27-37Sources: codex-rs/core/tests/suite/mod.rs1-34 codex-rs/core/tests/common/test_codex.rs1-62 codex-rs/core/tests/common/lib.rs1-80
The following diagram maps high-level testing concepts to the specific Rust modules and structs that implement them.
Title: Test Infrastructure Mapping
Sources: codex-rs/core/tests/common/test_codex.rs121-128 codex-rs/core/tests/suite/mod.rs10-34 codex-rs/core/tests/common/lib.rs27-37
Integration tests are aggregated in codex-rs/core/tests/suite/mod.rs codex-rs/core/tests/suite/mod.rs1-163 These exercise full system flows, including model interaction and tool execution. The suite covers specialized behaviors such as:
apply_patch_cli: Validates the apply_patch tool, its safety checks, and behavior across local and remote environments using TestCodexHarness codex-rs/core/tests/suite/apply_patch_cli.rs70-81shell_serialization: Ensures that shell output and durations are correctly formatted and preserved in the event stream codex-rs/core/tests/suite/shell_serialization.rs61-109remote_env: Tests tool behavior in remote environments, including the WaitForEnvironment tool and environment-specific instructions codex-rs/core/tests/suite/remote_env.rs108-145tools: Verifies tool registry filtering, ensuring environment-backed tools (like exec_command) are only available when environments are selected codex-rs/core/tests/suite/tools.rs57-95The core_test_support library provides shared infrastructure:
TestEnv: Manages the lifecycle of local or remote execution environments. It handles Docker-based remote testing by tracking container names and cleaning up temporary paths on drop codex-rs/core/tests/common/test_codex.rs121-190TestCodex: A harness that bundles a Codex instance with its Config, ThreadManager, and a mock server for orchestrated testing codex-rs/core/tests/common/test_codex.rs17-21TestBinaryDispatchGuard: Configured via #[ctor], it allows the test binary to behave like the codex binary and dispatch to internal tools like apply_patch based on argv1 codex-rs/core/tests/suite/mod.rs14-34Sources: codex-rs/core/tests/common/test_codex.rs121-190 codex-rs/core/tests/suite/mod.rs14-34 codex-rs/core/tests/common/lib.rs33-37
The project uses cargo nextest for parallelized test execution. Configuration is managed via .config/nextest.toml.
The insta crate is used for snapshot testing. The workspace root for snapshots is configured at process startup via a #[ctor] function in the test support library to ensure deterministic paths across the Cargo workspace codex-rs/core/tests/common/lib.rs62-80
wiremock: Standard for mocking HTTP-based model provider APIs codex-rs/core/tests/common/test_codex.rs58WebSocketTestServer: A custom wrapper that allows for mocking the Responses API over WebSockets, supporting message sequencing and handshake verification codex-rs/core/tests/common/test_codex.rs64Sources: codex-rs/core/tests/common/lib.rs62-80 codex-rs/core/tests/common/test_codex.rs58-64
The responses module provides a suite of helpers to generate mock API events:
ev_response_created: Simulates the start of a response codex-rs/core/tests/suite/apply_patch_cli.rs45ev_assistant_message: Simulates assistant text output codex-rs/core/tests/suite/apply_patch_cli.rs42ev_function_call: Simulates a model tool call codex-rs/core/tests/suite/apply_patch_cli.rs44sse: Wraps a sequence of events into a valid Server-Sent Events stream body codex-rs/core/tests/suite/apply_patch_cli.rs48Codex uses an "arg0 trick" to dispatch different functionalities from a single binary. In tests, this is handled by codex-arg0:
arg0_dispatch: Intercepts argv0 and argv1 to route to apply_patch, codex-linux-sandbox, or exec-helper codex-rs/arg0/src/lib.rs60-113prepare_path_entry_for_codex_aliases: Creates temporary symlinks for these aliases so sub-processes can find them in the PATH codex-rs/arg0/src/lib.rs156-168The TestEnv struct abstracts whether a test is running on the local machine or inside a remote Docker container.
Title: Test Environment Initialization
Sources: codex-rs/core/tests/common/test_codex.rs131-158 codex-rs/core/tests/common/lib.rs196-202
The testing infrastructure includes specific checks for tool safety:
assess_patch_safety: Evaluates if a patch should be auto-approved, rejected, or requires user input based on the SandboxPolicy and PermissionProfile codex-rs/core/src/safety.rs32-39is_write_patch_constrained_to_writable_paths: A core safety utility that normalizes paths and checks them against the FileSystemSandboxPolicy codex-rs/core/src/safety.rs135-144Sources: codex-rs/core/src/safety.rs32-144
Tests in apply_patch_cli.rs verify sandbox enforcement:
PermissionProfile: Used to define restrictive policies (e.g., workspace_write_with_read_only_root) for tool execution codex-rs/core/tests/suite/apply_patch_cli.rs138-159FileSystemSandboxPolicy: Defines fine-grained access (Read/Write/Deny) to specific paths, which is then validated against tool operations codex-rs/core/tests/suite/apply_patch_cli.rs163-178Sources: codex-rs/core/tests/suite/apply_patch_cli.rs138-178
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.