# How to Run Tests for the microsandbox Project: A Complete Testing Guide > Learn how to run tests for the microsandbox project. Execute all Rust unit tests with `cargo test --workspace` or specific crates using `cargo test -p `. Discover SDK testing steps. - Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox) - Tags: how-to-guide - Published: 2026-08-20 --- **Run tests in microsandbox using `cargo test --workspace` for all Rust unit tests, or use `cargo test -p ` for single crates; SDK tests require separate commands in their respective directories after running `just setup`.** The **microsandbox** project is a Cargo workspace maintained by SuperRad Company that provides a secure, lightweight sandboxing runtime. Understanding how to run tests for this project is essential for contributors and users who want to verify functionality or debug issues across its multi-layered architecture. ## Prerequisites: Setting Up the Development Environment Before running any tests, you must complete the initial setup. The microsandbox repository includes a **`just setup`** command that handles this automatically. ```bash git clone https://github.com/superradcompany/microsandbox.git cd microsandbox just setup ``` This command performs several critical operations: - Installs system-level tools and dependencies - Initializes Git submodules - Builds the **`agentd`** guest binary - Compiles the **libkrunfw** runtime library - Builds the **`msb`** CLI tool These artifacts are required for both Rust unit tests and SDK integration tests. The setup process ensures environment variables like `MSB_AGENTD_PATH` point to the correct binaries. ## Running Rust Workspace Tests The core microsandbox functionality lives in the Cargo workspace defined in **[`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml)**. Tests are organized by crate under the `crates/` directory. ### Run All Workspace Tests Execute the complete unit test suite across every crate: ```bash cargo test --workspace ``` This is the fastest way to verify that core runtime, network, and CLI components work correctly. Cargo automatically discovers test targets based on the workspace manifest. ### Run Tests for a Single Crate Isolate testing to a specific component when debugging: ```bash cargo test -p microsandbox-runtime cargo test -p microsandbox-network cargo test -p microsandbox-cli ``` Replace `` with any workspace member listed in [`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml). ### Run a Single Test by Name Target a specific test function for rapid iteration: ```bash cargo test -p microsandbox-runtime my_specific_test ``` This pattern accepts partial matches, so `my_specific_test` will match `my_specific_test_case` if unique. ## Internal Testing Infrastructure The microsandbox project includes dedicated testing utilities that power its test suite: - **[`crates/testing/utils/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/testing/utils/lib.rs)** — Provides shared test helpers and the **`#[msb_test]`** attribute for asynchronous test execution - **[`crates/testing/macros/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/testing/macros/lib.rs)** — Defines procedural macros that implement the `#[msb_test]` attribute These internal crates are used by other workspace members to standardize test patterns across the codebase. ## Running Language SDK Tests The microsandbox project ships SDKs for Python, Node.js/TypeScript, and Go. Each SDK manages its own test harness because they compile native bindings and invoke the `msb` CLI against running sandboxes. ### Python SDK Tests The Python SDK uses `maturin` for building native bindings and **`uv`** for dependency management: ```bash cd sdk/python # Unit tests only uv run pytest # Integration tests (spins up actual sandboxes) uv run pytest integration/*.py ``` Integration tests require a functional virtualization backend: **KVM on Linux**, **Apple Silicon Virtualization on macOS**, or **Windows Hypervisor Platform**. ### Node.js/TypeScript SDK Tests The Node-TS SDK uses `node-gyp` for native compilation and **`npm`** for orchestration: ```bash cd sdk/node-ts npm test ``` This command runs both type checking and the JavaScript test suite. ### Go SDK Tests The Go SDK uses **`cgo`** for FFI bindings to the core runtime: ```bash cd sdk/go # Unit tests go test -count=1 ./... # Full integration tests with FFI path configuration go test -tags "smoke microsandbox_ffi_path" -count=1 . ``` The `microsandbox_ffi_path` build tag enables tests that locate and load the shared library at runtime. ## Test Requirements and Platform Support | Component | Requirements | |-----------|--------------| | Rust unit tests | Any platform with Rust toolchain | | SDK integration tests | KVM (Linux), Apple Silicon (macOS), or WHP (Windows) | | Full integration suite | Completed `just setup` with `agentd` and `libkrunfw` built | Virtualization backends are only required for integration tests that create actual microVMs. Pure unit tests run on any supported Rust target. ## Performance Testing and Benchmarks For performance validation, the microsandbox project maintains a separate repository: - [**microvm-benchmarks**](https://github.com/superradcompany/microvm-benchmarks) — Standalone benchmark suite for comparing virtualization overhead Benchmarks are intentionally excluded from the main repository to keep CI times reasonable and allow independent versioning of test workloads. ## Summary - **Use `just setup`** once to install tools and build required binaries - **Use `cargo test --workspace`** for comprehensive Rust unit testing - **Use `cargo test -p `** to isolate testing to specific components - **Navigate to SDK directories** and use their native test commands (`uv run pytest`, `npm test`, `go test`) - **Enable virtualization** for SDK integration tests that spawn sandboxes - **Reference [`DEVELOPMENT.md`](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md)** for the authoritative build and test documentation ## Frequently Asked Questions ### What is the fastest way to run tests after making a small change? Run `cargo test -p ` to test only the crate you changed. For example, if you modified network code, use `cargo test -p microsandbox-network`. This avoids the overhead of testing unaffected workspace members. ### Why do SDK tests fail with "agentd not found" errors? The `agentd` binary and `libkrunfw` library must be built and available in your environment. Run `just setup` to ensure these are compiled and that `MSB_AGENTD_PATH` is correctly set. SDK tests depend on these artifacts to spawn actual sandboxes. ### Can I run tests without virtualization enabled? Yes — Rust workspace unit tests do not require virtualization. However, SDK integration tests that create microVMs will fail without KVM (Linux), Apple Silicon Virtualization (macOS), or Windows Hypervisor Platform. Run SDK unit tests only (`uv run pytest` without integration patterns, or `go test` without smoke tags) to avoid virtualization requirements. ### How do I debug a failing test in the runtime crate? Use the single-test pattern with output capture disabled: `cargo test -p microsandbox-runtime -- --nocapture`. Add `RUST_LOG=debug` to see internal tracing. For interactive debugging, use `cargo test -- --test-threads=1` to prevent concurrent test execution.