Markmason

Write tests in Markdown. Run them with mm.

Install

Download from Releases, verify the archive against SHA256SUMS, and put mm (mm.exe on Windows) on PATH.

Platform	Target
Linux x64, glibc 2.35+	x86_64-unknown-linux-gnu
Linux x64, static musl	x86_64-unknown-linux-musl
Windows x64	x86_64-pc-windows-msvc
macOS Intel	x86_64-apple-darwin
macOS Apple Silicon	aarch64-apple-darwin

Or install from source with Rust 1.99+:

cargo install --git https://github.com/jsturtevant/markmason --tag v0.6.0 --locked

Write a test

This README is testable.* Run mm README.md.

Show the installed version

```markmason
mm --version
```

```expected
mm 0.6.0
```

Say hello with Bash

```markmason
bash -c "echo Hello, world!"
```

```expected
Hello, world!
```

* These examples use the optional markdown markmason wrapper so GitHub shows their inner fence syntax. Use direct markmason fences for normal executable docs.

Run Markmason:

mm                         # Defaults to tests/cli
mm path/to/specs            # Another directory
mm path/to/walkthrough.md   # One Markdown file
mm --list                  # Discover without executing
mm --fail-fast             # Stop after the first failed document cleans up
mm --parallel              # Use available logical CPUs for independent files
mm --parallel 8            # Bound file execution to eight workers
mm path/to/specs --sandbox mxc  # Contain commands with MXC
mm --file-pattern greet    # Select files by regex
mm --step                  # Pick a file and walk through it
mm --step --file-pattern '^greet\.md$'  # Skip the picker
mm path/to/walkthrough.md --step       # Walk through one file directly

Live examples

Learn more with real examples from mm:

• Getting started
• Command blocks
• Step-by-step walkthrough
• Walkthroughs tested in a real terminal
• Running tests
• Filtering
• Stdin and pipes
• Terminal prompts
• Output matching
• Error cases
• Matching failures
• Runtime failures and timeouts
• Setup and state
• Required inputs
• Sandboxed execution
• Repository fixtures
• Persistent Bash sessions
• Deferred cleanup
• Path variables
• Environment filters

Run the markmason on these examples from this checkout (see development prerequisites):

just test-markdown

This builds mm and mm-test-cli, a small app that prints text, shows prompts, and writes test state for demonstrating Markmason features.

Use mm --help for CLI options.

Develop and self-test

Requires Rust with rustfmt and clippy, Bash, and Just (cargo install --locked just).

just check            # Formatting, lint, Rust tests, Markdown self-tests
just test-markdown    # Only the Markdown self-tests
just fmt              # Format Rust source

The Markdown self-tests run mm against small fixture specs and the test CLI.

Write tests with an agent

Use the markmason-tests skill to write tests that read like docs. It covers normal examples, separate error cases, assertions, fixtures, and safe self-testing.

Copy .github/skills/markmason-tests/ into the same location in another repo to reuse it. Keep the folder's reference file and license with it.

Releases

PRs run CI only. The separate release workflow reuses those checks before publishing.

• Successful main builds update the mutable preview-release prerelease.
• Use a minor version bump for executable Markdown format changes.
• For stable releases, update Cargo.toml, Cargo.lock, and the version assertion in tests/cli/cli.md, then push a matching vMAJOR.MINOR.PATCH tag. Versioned releases are never overwritten.
• All four platforms must pass before publishing. Archives include the binary, README, MIT license, and SHA-256 checksums.

Package locally with just package TARGET preview-release (7-Zip needed on Windows).

License

MIT. Extracted from Rally.