maelstrom
maelstrom copied to clipboard
Maelstrom is a fast Rust test runner that runs every test in its own container. Tests are either run locally or distributed to a clustered job runner.
Maelstrom is a Rust test runner, built on top of a general-purpose clustered job runner. 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, eliminating confusing errors caused by inter-test or implicit test-environment dependencies.
- It's scalable. Maelstrom can be run as a cluster. You can add more worker machines to linearly increase test throughput.
- It's fast. In most cases, Maelstrom is faster than
cargo test
, even without using 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 written in Rust.
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 in the near future. 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.
Getting Started
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:
cargo binstall cargo-maelstrom
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
:
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:
cargo maelstrom --init
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
:
cargo binstall maelstrom-worker maelstrom-broker
Then you can start the broker:
maelstrom-broker --port=1234
Then a few workers:
maelstrom-worker --broker=broker-host:1234
And then run cargo-maelstrom
against the cluster:
cargo maelstrom --broker=broker-host:1234
Learn More
Find our complete documentation in the book.
Licensing
This project is available under the terms of either the Apache 2.0 license or the MIT license.