Configuring Tests

Riot test configuration is less about a giant config file and more about respecting the shared contract between:

• Std.Test.Cli.main
• your suite binary
• riot test

If that contract stays stable, local runs, CI runs, editor integration, and future tooling can all agree on what a test suite is.

The test-binary contract

Within std, the shared contract is owned by Std.Test.Cli.

That contract includes support for:

• list-tests
• run-tests
• --json
• query filtering

The point is not that every contributor has to remember those subcommands by heart. The point is that every package should expose test binaries in the same way instead of inventing local CLIs.

Why Test.Cli.main matters

This call is the heart of configuration:

Test.Cli.main
  ~name:"my suite"
  ~tests
  ~args

From those three inputs, Riot gets:

• the suite name
• the test list
• the CLI arguments passed through by the test runner

That is enough to keep the suite usable both directly and through riot test.

Naming suites well

Your suite name should help with:

• terminal output
• query filtering
• snapshot path layout

It should describe the surface under test, not just repeat the package name.

Selecting suites and tests

At the workspace level, selection usually happens through:

• riot test
• riot test -p <package>
• riot test <query>

The help text explicitly calls out a package:suite shape when you want to target one suite.

That means suite naming is part of configuration. If names are sloppy, selective execution gets worse.

JSON mode

The shared test contract also matters because JSON mode needs consistent suite semantics.

Use:

riot test --json

when the caller is:

• CI
• an editor
• a dashboard
• another tool that wants events instead of terminal prose

The more stable the suite contract is, the less likely higher layers are to scrape or guess.

Verbose output

Verbose mode is a useful part of configuration too:

riot test -v

The default runner output should stay concise. Verbose mode is how you opt into suite stdout and stderr without forcing every test run to be noisy.

Fixture-heavy suites

Once a suite is fixture-heavy, configuration often means establishing:

• fixture root directory
• optional file filter
• optional custom snapshot-path mapping

That configuration should still live through Std.Test.FixtureRunner, not package-local discovery code. The point is to keep suite wiring standardized even when the inputs get more complex.

Snapshot-aware suites

Snapshot-bearing suites should be configured so the approved artifact location is obvious.

The defaults are already useful:

• non-fixture snapshots under .riot/snapshots/<package>/<suite>/<test>.expected
• fixture-backed snapshots next to the fixture input, using .expected

Only reach for custom snapshot path configuration when the fixture family genuinely needs a different approved-file naming convention.