Installing Pre-Built Binaries
To run your tests using Maelstrom, you need a test-runner binary.
The easiest way to get it is using cargo-binstall.
For Rust tests:
cargo binstall cargo-maelstrom
For Go tests:
cargo binstall maelstrom-go-test
For Python tests:
cargo binstall maelstrom-pytest
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 install 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 cargo-maelstrom.toml file. To do this, run:
cargo maelstrom --init
Then edit the created cargo-maelstrom.toml file as described in the
book
Running maelstrom-go-test
To run your Go tests, use maelstrom-go-test:
maelstrom-go-test
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-go-test.toml file. To do this, run:
maelstrom-go-test --init
Then edit the created maelstrom-go-test.toml file as described in the
book
Running maelstrom-pytest
Before running tests, we need to do a little setup.
Choosing a Python Image
First generate a `maelstrom-pytest.toml` file
maelstrom-pytest --init
Then update the file to include a python image
[[directives]]
image = "docker://python:3.11-slim"
This example installs an image from Docker
Including Your Project Python Files
So that your tests can be run from the container, your project's python must be included.
added_layers = [ { glob = "**.py" } ]
This example just adds all files with a .py extension. You may also need to include
.pyi files or other files.
Including pip Packages
If you have an image named "python", `maelstrom-pytest` will automatically include pip
packages for you as part of the container. It expects to read these packages from a
test-requirements.txt file in your project directory. This needs to at a minimum include the pytest
package
Running Tests
Once you have finished the configuration, you only need invoke `maelstrom-pytest` to run all
the tests in your project. It must be run from an environment where `pytest` is in the Python
path. If you are using virtualenv for your project make sure to source that first.
test-requirements.txt.
pytest==8.1.1
Now we are ready to try to run tests. Just invoke maelstrom-pytest:
maelstrom-pytest
This runs in “standalone” mode, meaning all tests are run locally. Each test is run in its own
container.
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
Then run cargo-maelstrom against the cluster:
cargo maelstrom --broker=broker-host:1234
See the book for more information:
