How to Run Tests for the microsandbox Project: A Complete Testing Guide

Run tests in microsandbox using cargo test --workspace for all Rust unit tests, or use cargo test -p <crate-name> 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.

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. Tests are organized by crate under the crates/ directory.

Run All Workspace Tests

Execute the complete unit test suite across every crate:

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:

cargo test -p microsandbox-runtime
cargo test -p microsandbox-network
cargo test -p microsandbox-cli

Replace <crate-name> with any workspace member listed in Cargo.toml.

Run a Single Test by Name

Target a specific test function for rapid iteration:

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 — Provides shared test helpers and the #[msb_test] attribute for asynchronous test execution
• 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:

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:

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:

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 — 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 <crate> 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 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 <modified-crate> 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 <test-name> -- --nocapture. Add RUST_LOG=debug to see internal tracing. For interactive debugging, use cargo test -- --test-threads=1 to prevent concurrent test execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}