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

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)
}

Modules

Run commands and assert on their behavior

harnessharness

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

Macros

debugdebug

Feature-flag controlled additional test debug information

Structs

Snapshot assertion against a file’s contents

Test fixture, actual output, or expected result

Match pattern expressions, see Assert

Enums

Test action, see Assert

Constants

Functions

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