offload/
lib.rs

1//! # offload-rs
2//!
3//! A flexible, high-performance parallel test runner that executes tests across
4//! multiple isolated sandboxes with pluggable execution providers.
5//!
6//! ## Overview
7//!
8//! Offload enables distributed test execution across local processes, or custom
9//! cloud providers (like Modal). It provides:
10//!
11//! - **Parallel execution** across multiple isolated sandbox environments
12//! - **Automatic test discovery** for pytest, cargo test, and custom frameworks
13//! - **Flaky test detection** with configurable retry logic
14//! - **JUnit XML reporting** for CI/CD integration
15//! - **Streaming output** for real-time test progress
16//!
17//! ## Architecture
18//!
19//! The crate is organized into four main subsystems:
20//!
21//! ### Providers ([`provider`])
22//!
23//! Providers create and manage sandbox execution environments. Each provider
24//! implements the [`SandboxProvider`] trait:
25//!
26//! - [`provider::local::LocalProvider`] - Run tests as local processes
27//! - [`provider::default::DefaultProvider`] - Run tests using custom shell commands
28//! - [`provider::modal::ModalProvider`] - Run tests on Modal cloud sandboxes
29//!
30//! ### Framework ([`framework`])
31//!
32//! Frameworks find tests and generate commands to run them. Each framework
33//! implements the [`TestFramework`] trait:
34//!
35//! - [`framework::pytest::PytestFramework`] - Discover and run pytest tests
36//! - [`framework::cargo::CargoFramework`] - Discover and run Rust tests
37//! - [`framework::default::DefaultFramework`] - Custom framework via shell commands
38//!
39//! ### Orchestrator ([`orchestrator`])
40//!
41//! The orchestrator module coordinates test distribution and execution:
42//!
43//! - [`Orchestrator`] - Main entry point that coordinates the entire test run
44//! - [`orchestrator::Scheduler`] - Distributes tests across available sandboxes
45//! - [`orchestrator::TestRunner`] - Executes tests within a single sandbox
46//!
47//! ### Reporting ([`report`])
48//!
49//! Utilities for test result reporting:
50//!
51//! - [`report::print_summary`] - Print test results to console
52//! - [`report::MasterJunitReport`] - JUnit XML report generation
53//!
54//! ## Quick Start
55//!
56//! ```no_run
57//! use offload::config::{load_config, SandboxConfig};
58//! use offload::orchestrator::{Orchestrator, SandboxPool};
59//! use offload::provider::local::LocalProvider;
60//! use offload::framework::{TestFramework, pytest::PytestFramework};
61//!
62//! #[tokio::main]
63//! async fn main() -> anyhow::Result<()> {
64//!     // Load configuration from TOML file
65//!     let config = load_config(std::path::Path::new("offload.toml"))?;
66//!
67//!     // Create provider (runs tests as local processes)
68//!     let provider = LocalProvider::new(Default::default());
69//!
70//!     // Create framework (finds pytest tests)
71//!     let framework = PytestFramework::new(Default::default());
72//!
73//!     // Discover tests using the framework
74//!     let tests = framework.discover(&[], "").await?;
75//!
76//!     // Pre-populate sandbox pool
77//!     let sandbox_config = SandboxConfig {
78//!         id: "sandbox".to_string(),
79//!         working_dir: None,
80//!         env: vec![],
81//!         copy_dirs: vec![],
82//!     };
83//!     let mut sandbox_pool = SandboxPool::new();
84//!     sandbox_pool.populate(config.offload.max_parallel, &provider, &sandbox_config).await?;
85//!
86//!     // Run tests using the orchestrator
87//!     let orchestrator = Orchestrator::new(config, framework, false);
88//!     let result = orchestrator.run_with_tests(&tests, sandbox_pool).await?;
89//!
90//!     std::process::exit(result.exit_code());
91//! }
92//! ```
93//!
94//! ## Configuration
95//!
96//! Offload is configured via TOML files. See [`config`] module for schema details.
97//!
98//! ## Custom Providers
99//!
100//! You can implement custom providers for cloud platforms like Modal, AWS Lambda,
101//! or Kubernetes by implementing the [`SandboxProvider`] and [`Sandbox`] traits,
102//! or by using the [`provider::default::DefaultProvider`] with custom shell commands.
103//!
104//! [`SandboxProvider`]: provider::SandboxProvider
105//! [`Sandbox`]: provider::Sandbox
106//! [`TestFramework`]: framework::TestFramework
107//! [`Orchestrator`]: orchestrator::Orchestrator
108
109pub mod bundled;
110pub mod cache;
111pub mod config;
112pub mod connector;
113pub mod framework;
114pub mod orchestrator;
115pub mod provider;
116pub mod report;
117
118// Re-export commonly used types for convenience.
119// These are the types most users will need when setting up offload.
120
121pub use config::{Config, load_config};
122pub use framework::{TestFramework, TestInstance, TestOutcome, TestRecord, TestResult};
123pub use orchestrator::{Orchestrator, RunResult, SandboxPool};
124pub use provider::{Sandbox, SandboxProvider};
125pub use report::print_summary;
offload/lib.rs

offload/
lib.rs
