Maelstrom packages your Rust tests into hermetic micro-containers, then distributes them to be run on an arbitrarily large cluster of test-runners, or locally on your machine. You might use Maelstrom to run your tests because:

• It's easy. Maelstrom functions as a drop-in replacement for cargo-test, so in most cases, it just works.
• It's reliable. Maelstrom runs every test hermetically in its own lightweight container and runs each test independently, eliminating confusing errors caused by inter-test or implicit test-environment dependencies.
• It's scalable. You can run Maelstrom as a cluster. Add more worker machines to linearly improve test throughput.
• It's fast. In most cases, Maelstrom is faster than cargo test, even without adding clustering.
• It's clean. Maelstrom has a from-scratch, rootless container implementation (not relying on docker or RunC), optimized to be low-overhead and start quickly.
• It's Rusty. The whole project is built in Rust.

Maelstrom is currently available for Rust on Linux. C++, Typescript, Python, and Java are coming soon.

We started with a Rust test runner, but Maelstrom's underlying job execution system is general-purpose. We will add support for other languages' test frameworks throughout 2024. We have also provided tools for adventurous users to run arbitrary jobs, either using a command-line tool or a gRPC-based SDK.

The project is currently Linux-only (x86 and ARM), as it relies on namespaces to implement containers.

See the book for more information:

• Maelstrom Book

Installing cargo-maelstrom

To run your tests using Maelstrom, you need the cargo-maelstrom binary. The easiest way to get it is using cargo-binstall.

This will install a pre-built binary from the github releases page. If you don't have cargo-binstall, you can download the binary manually. Check out the book for more ways to get cargo-maelstrom.

Running cargo-maelstrom

To run your Rust tests, use cargo-maelstrom:

This runs in "standalone" mode, meaning all tests are run locally. Each test is run in its own container, configured with a few common dependencies. It may work for your project without any further configuration.

If some tests fail, however, it likely means those tests have dependencies on their execution environment that aren't packaged in their containers. You can remedy this by adding directives to the `maelstrom-test.toml` file. To do this, run:

Then edit the created `maelstrom-test.toml` file as described in the book.

Setting Up a Cluster

To get even more out of Maelstrom, you can set up a cluster to run your tests on. You will need to run one copy of the broker (maelstrom-broker) somewhere, and one copy of the worker (maelstrom-worker) on each node of the cluster.

You can install these using multiple methods, including cargo-binstall:

Then you can start the broker:

Then a few workers:

Then run 'cargo-maelstrom' against the cluster:

See the book for more information:

• Maelstrom Book