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//!
29//! ### Framework ([`framework`])
30//!
31//! Frameworks find tests and generate commands to run them. Each framework
32//! implements the [`TestFramework`] trait:
33//!
34//! - [`framework::pytest::PytestFramework`] - Discover and run pytest tests
35//! - [`framework::cargo::CargoFramework`] - Discover and run Rust tests
36//! - [`framework::default::DefaultFramework`] - Custom framework via shell commands
37//!
38//! ### Orchestrator ([`orchestrator`])
39//!
40//! The orchestrator module coordinates test distribution and execution:
41//!
42//! - [`Orchestrator`] - Main entry point that coordinates the entire test run
43//! - [`orchestrator::Scheduler`] - Distributes tests across available sandboxes
44//! - [`orchestrator::TestRunner`] - Executes tests within a single sandbox
45//!
46//! ### Reporting ([`report`])
47//!
48//! Utilities for test result reporting:
49//!
50//! - [`report::print_summary`] - Print test results to console
51//! - [`report::MasterJunitReport`] - JUnit XML report generation
52//!
53//! ## Quick Start
54//!
55//! ```no_run
56//! use offload::config::{load_config, SandboxConfig};
57//! use offload::orchestrator::{Orchestrator, SandboxPool};
58//! use offload::provider::local::LocalProvider;
59//! use offload::framework::{TestFramework, pytest::PytestFramework};
60//!
61//! #[tokio::main]
62//! async fn main() -> anyhow::Result<()> {
63//! // Load configuration from TOML file
64//! let config = load_config(std::path::Path::new("offload.toml"))?;
65//!
66//! // Create provider (runs tests as local processes)
67//! let provider = LocalProvider::new(Default::default());
68//!
69//! // Create framework (finds pytest tests)
70//! let framework = PytestFramework::new(Default::default());
71//!
72//! // Discover tests using the framework
73//! let tests = framework.discover(&[]).await?;
74//!
75//! // Pre-populate sandbox pool
76//! let sandbox_config = SandboxConfig {
77//! id: "sandbox".to_string(),
78//! working_dir: None,
79//! env: vec![],
80//! copy_dirs: vec![],
81//! };
82//! let mut sandbox_pool = SandboxPool::new();
83//! sandbox_pool.populate(config.offload.max_parallel, &provider, &sandbox_config).await?;
84//!
85//! // Run tests using the orchestrator
86//! let orchestrator = Orchestrator::new(config, framework, false);
87//! let result = orchestrator.run_with_tests(&tests, sandbox_pool).await?;
88//!
89//! std::process::exit(result.exit_code());
90//! }
91//! ```
92//!
93//! ## Configuration
94//!
95//! Offload is configured via TOML files. See [`config`] module for schema details.
96//!
97//! ## Custom Providers
98//!
99//! You can implement custom providers for cloud platforms like Modal, AWS Lambda,
100//! or Kubernetes by implementing the [`SandboxProvider`] and [`Sandbox`] traits,
101//! or by using the [`provider::default::DefaultProvider`] with custom shell commands.
102//!
103//! [`SandboxProvider`]: provider::SandboxProvider
104//! [`Sandbox`]: provider::Sandbox
105//! [`TestFramework`]: framework::TestFramework
106//! [`Orchestrator`]: orchestrator::Orchestrator
107
108pub mod bundled;
109pub mod cache;
110pub mod config;
111pub mod connector;
112pub mod framework;
113pub mod orchestrator;
114pub mod provider;
115pub mod report;
116
117// Re-export commonly used types for convenience.
118// These are the types most users will need when setting up offload.
119
120pub use config::{Config, load_config};
121pub use framework::{TestFramework, TestInstance, TestOutcome, TestRecord, TestResult};
122pub use orchestrator::{Orchestrator, RunResult, SandboxPool};
123pub use provider::{Sandbox, SandboxProvider};
124pub use report::print_summary;