Skip to main content

Module sandbox

Module sandbox 

Source
Expand description

Temporary copies of a project where Forge builds and runs generated tests.

Re-exportsΒ§

use crate::result::TestResult; πŸ”’
use crate::workspace; πŸ”’
use eyre::Context; πŸ”’
use eyre::Result; πŸ”’
use eyre::eyre; πŸ”’
use foundry_common::fs::canonicalize_path; πŸ”’
use foundry_compilers::cache::SOLIDITY_FILES_CACHE_FILENAME; πŸ”’
use foundry_compilers::solc::Solc; πŸ”’
use foundry_config::Config; πŸ”’
use foundry_config::DenyLevel; πŸ”’
use serde::Deserialize; πŸ”’
use serde::Deserialize; πŸ”’
use std::fs; πŸ”’
use std::path::Path; πŸ”’
use std::path::PathBuf; πŸ”’
use std::process::Command; πŸ”’
use std::process::ExitStatus; πŸ”’
use std::process::Output; πŸ”’
use std::process::Stdio; πŸ”’
use std::thread; πŸ”’
use std::time::Duration; πŸ”’
use std::time::Instant; πŸ”’
use tempfile::TempDir; πŸ”’
use toml_edit::DocumentMut; πŸ”’
use rustix::process::Pid; πŸ”’ Unix
use rustix::process::Signal; πŸ”’ Unix
use rustix::process::kill_process_group; πŸ”’ Unix
use std::os::unix::process::CommandExt; πŸ”’ Unix
use std::sync::Mutex; πŸ”’ Unix

StructsΒ§

Sandbox πŸ”’
Builds and runs generated code in temporary copies of the project. Generated code runs outside the sandbox of whatever wrote it, so a copy leaves out hidden root entries such as .env and agent settings, and Forge runs in it with only a few environment variables.
TestFile πŸ”’
A Solidity file that an agent wrote, by its path relative to the project root.

ConstantsΒ§

AGENT_CONFIG πŸ”’
Agent settings and instruction files that a workspace leaves out at every level. Settings can hold hooks that run commands on the host. CLAUDE.md and AGENTS.md are project docs, but they steer the agents that work in the copy, so a user who wants them passes them with --context. Entries of dependency directories are links, so they keep their own files.
PASSED_ENV πŸ”’
The environment variables that builds and test runs of generated code see, besides HOME, FOUNDRY_PROFILE, and the seed settings. Generated tests run outside the agent’s sandbox, so they must not read the secrets of Forge’s environment with the env cheatcodes.
RUN_TIMEOUT πŸ”’
How long one Forge build or test run in a workspace can take.
SELECT_ALL_TESTS πŸ”’
Overrides configured test filters, so they cannot hide generated tests. $^ matches no contract or test name, and no project file is under /forge-properties-none.
SESSION_POLL πŸ”’
How often Forge checks whether an agent session with a timeout has exited. Sessions take minutes, so this adds no noticeable delay.

StaticsΒ§

SESSIONS πŸ”’ Unix
The process groups of the running agent sessions, which Forge ends if it is interrupted.

FunctionsΒ§

copy_build_output πŸ”’
Copies the build output and the compiler cache of a built workspace into another workspace. The copy clones files where the file system can (APFS, Btrfs, XFS).
copy_project_tree πŸ”’
Copies a project directory into a workspace, without Git data, the skipped paths, agent settings and instructions (AGENT_CONFIG), and, at the project root, hidden entries such as .env.
ensure_inside πŸ”’
Fails if the nearest existing ancestor of path resolves outside root, for example through a linked directory.
restrict_config πŸ”’
Turns off ffi unless allow_ffi, and removes the RPC and Etherscan settings unless allow_network. Every workspace of a Sandbox writes its config through this, so no generated test can call vm.ffi or reach an endpoint that the config names. Config ignores FFI environment variables.
run_session πŸ”’
Runs a session command in its own process group until it exits or reaches the timeout in seconds, then ends the process group, so no process that the session started keeps running. Returns None if the session reached the timeout.
shorten πŸ”’
Keeps both ends of a long tool output. Many tools print the decisive error last.
stderr πŸ”’
Returns stderr without compiler warning blocks and keeps both ends when it is still long. Warnings can fill the limit before the decisive error, and many tools print the error last. Without a compiler error, as with deny = "warnings", the warnings are the errors and stay.
suite_results πŸ”’
Returns every test result in Forge’s JSON output with its contract and test name.