Crate snapbox

source ·

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:

assert_eq and assert_matches for reusing diffing / pattern matching for non-snapshot testing
assert_eq_path and assert_matches_path for one-off assertions with the snapshot stored in a file
harness::Harness for discovering test inputs and asserting against snapshot files:

Testing Commands:

cmd::Command: Process spawning for testing of non-interactive commands
cmd::OutputAssert: Assert the state of a Command’s Output.

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
json — Snapshotting of json
structured-data — Snapshotting of structured data
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

Examples

assert_matches

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

Assert

let actual = "...";
let expected_path = "tests/fixtures/help_output_is_clean.txt";
snapbox::Assert::new()
    .action_env("SNAPSHOTS")
    .matches_path(expected_path, actual);

harness::Harness

snapbox::harness::Harness::new(
   "tests/fixtures/invalid",
   setup,
   test,
)
.select(["tests/cases/*.in"])
.action_env("SNAPSHOTS")
.test();

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 {
       name,
       fixture: input_path,
       expected,
   }
}

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;

   Ok(actual)
}