Command-Line Options
In addition the command-line options for used to specify configuration
values described in the previous chapter,
cargo-maelstrom supports these command-line options:
| Option | Short Alias | Argument | Description |
|---|---|---|---|
--help | -h | print help and exit | |
--version | print version and exit | ||
--print-config | -P | print all configuration values and exit | |
--config-file | -c | path or - | file to read configuration values from |
--include | -i | pattern | include tests that match pattern |
--exclude | -x | pattern | exclude tests that match pattern |
--init | initialize test metadata file | ||
--list | alias for --list-tests | ||
--list-tests | only list matching tests instead of running them | ||
--list-binaries | only list matching test binaries instead of running tests | ||
--list-packages | only list matching test packages instead of running tests |
--include and --exclude
The --include (-i) and --exclude (-x) command-line options control which tests
cargo-maelstrom runs or lists.
These options take a test filter pattern. The --include option
includes any test that matches the pattern. Similarly, --exclude pattern
excludes any test that matches the pattern. Both options are allowed to be
repeated arbitrarily.
The tests that are selected are the set which match any --include pattern but
don't match any --exclude pattern. In other words, --excludes have precedence
over --includes, regardless of the order they are specified.
If no --include option is provided, cargo-maelstrom acts as if an
--include all option was provided.
--init
The --init command-line option is used to create a starter
cargo-maelstrom.toml file. See here for more
information.
--list-tests or --list
The --list-tests (or --list) command-line option causes cargo-maelstrom
to build all required test binaries, then print the tests that would normally
be run, without actually running them.
This option can be combined with --include and --exclude.
--list-binaries
The --list-binaries command-line option causes cargo-maelstrom to print the
names and types of the crates that it would run tests from, without actually
building any binaries or running any tests.
This option can be combined with --include and --exclude.
--list-packages
The --list-packages command-line option causes cargo-maelstrom to print the
packages from which it would run tests, without actually building any binaries
or running any tests.
This option can be combined with --include and --exclude.
Working with Workspaces
When you specify a filter with a package, cargo-maelstrom will only build the
matching packages. This can be a useful tip to remember when trying to run a
single test.
If we were to run something like:
cargo maelstrom --include "name.equals(foobar)"
cargo-maelstrom would run any test which has the name "foobar". A test with
this name could be found in any of the packages in the workspace, so it is
forced to build all of them. But if we happened to know that only one package has
this test — the baz package — it would be faster to instead run:
cargo maelstrom --include "package.equals(baz) && name.equals(foobar)"
Since we specified that we only care about the baz package, cargo-maelstrom
will only bother to build that package.
Abbreviations
As discussed here, unambiguous prefixes can be used in patterns. This can come in handy when doing one-offs on the command line. For example, the example above could be written like this instead:
cargo maelstrom -i 'p.eq(baz) & n.eq(foobar)'