Expand description

Snapshot testing toolbox

When you have to treat your tests like pets, instead of cattle

snapbox is a snapshot-testing toolbox that is ready to use for verifying output from

  • Function return values
  • CLI stdout/stderr
  • Filesystem changes

It is also flexible enough to build your own test harness like trycmd.

Which tool is right

  • cram: End-to-end CLI snapshotting agnostic of any programming language
  • trycmd: For running a lot of blunt tests (limited test predicates)
    • Particular attention is given to allow the test data to be pulled into documentation, like with mdbook
  • snapbox: When you want something like trycmd in one off cases or you need to customize trycmds behavior.
  • assert_cmd + assert_fs: Test cases follow a certain pattern but special attention is needed in how to verify the results.
  • Hand-written test cases: for peculiar circumstances

Getting Started

Testing Functions:

Testing Commands:

Testing Filesystem Interactions:

  • path::PathFixture: Working directory for tests
  • Assert: Diff a directory against files present in a pattern directory

You can also build your own version of these with the lower-level building blocks these are made of.

Feature Flags

  • harness — Simple input/output test harness

  • detect-encoding — Smarter binary file detection

  • path — Snapshotting of paths

  • cmd — Snapshotting of commands

  • debug — Extra debugging information

Default Feature Flags

  • diff (enabled by default) — Fancy diffs on failure

  • color — Colored output support

  • color-auto (enabled by default) — Auto-detect whether to use colors



snapbox::assert_matches("Hello [..] people!", "Hello many people!");


let actual = "...";
let expected_path = "tests/fixtures/help_output_is_clean.txt";
    .matches_path(expected_path, actual);



fn setup(input_path: std::path::PathBuf) -> snapbox::harness::Case {
   let name = input_path.file_name().unwrap().to_str().unwrap().to_owned();
   let expected = input_path.with_extension("out");
   snapbox::harness::Case {
       fixture: input_path,

fn test(input_path: &std::path::Path) -> Result<usize, Box<dyn std::error::Error>> {
   let raw = std::fs::read_to_string(input_path)?;
   let num = raw.parse::<usize>()?;

   let actual = num + 10;



Run commands and assert on their behavior


Harness for discovering test inputs and asserting against snapshot files

Initialize working directories and assert on how they’ve changed

Utilities to report test results to users



Feature-flag controlled additional test debug information


Snapshot assertion against a file’s contents

Test fixture, actual output, or expected result

Match pattern expressions, see Assert


Test action, see Assert



Check if a value is the same as an expected value

Check if a value matches the content of a file

Check if a value matches a pattern

Check if a value matches the pattern in a file

Check if a path matches the content of another path, recursively

Check if a path matches the pattern of another path, recursively

Type Definitions