DOCSEARCHbyAlgolia
Submit Docs

insta Snapshot Testing for Rust

repository·master·Indexed 23 days ago

https://github.com/mitsuhiko/insta

A snapshot testing library for Rust that allows developers to assert complex values against reference snapshots. It includes the cargo-insta CLI tool for reviewing, accepting, and rejecting snapshot changes, as well as a VSCode extension for syntax highlighting and integrated diffing of .snap and RON files.

Tokens
8.3K
Snippets
16
Records
73
Agent score
84%

What's inside insta

  1. Introduction to insta snapshot testing

    master
    insta is a snapshot testing library for Rust. Snapshot tests (also known as approval tests) assert values against a reference value (the snapshot). Unlike standard string assertions, snapshot tests are designed for complex values and provide tools to review changes, making them ideal for large or frequently changing reference values.

  2. Use the VS Code extension for insta snapshots

    master
    The vscode-insta extension improves the workflow for Rust's insta snapshot testing by providing syntax highlighting, a dedicated view for pending snapshots, and integrated diffing tools. It supports .snap files (with YAML-like highlighting) and RON snapshots.

  3. Use cargo-insta commands

    master

    The cargo-insta CLI provides several commands to manage and review snapshots generated by the insta library:

    • test: Runs your tests.
    • review: Starts an interactive process to review all identified snapshot changes. This is the primary way to inspect and decide on snapshot updates.
    • accept: Directly accepts all identified snapshot changes without an interactive review.
    • reject: Directly rejects all identified snapshot changes without an interactive review.

    For a complete list of flags and advanced usage, refer to the official CLI documentation.

  5. Manage pending snapshots via the Sidebar

    master
    If insta is used in your project, all pending snapshots are displayed in a dedicated view in the VS Code sidebar. Clicking on a snapshot in this view opens a diff view where you can accept or reject the changes. This functionality also works for inline snapshots.

  6. Install cargo-insta

    master

    You can install cargo-insta using prebuilt binaries via shell scripts, manual binary downloads, or by compiling from source using cargo install.

    Using Installation Scripts

    Unix:

    curl -LsSf https://insta.rs/install.sh | sh

    Windows:

    powershell -c "irm https://insta.rs/install.ps1 | iex"

    Installing a Specific Version

    To install a specific version (e.g., 1.38.0), use the versioned installer scripts:

    Unix:

    curl -LsSf https://github.com/mitsuhiko/insta/releases/download/1.38.0/cargo-insta-installer.sh | sh

    Windows:

    powershell -c "irm https://github.com/mitsuhiko/insta/releases/download/1.38.0/cargo-insta-installer.ps1 | iex"

    Installing via Cargo

    You can manually build and install the tool using cargo install. When installing an older version, it is recommended to use the --locked flag to honor the Cargo.lock file.

    $ cargo install cargo-insta --version 1.15.0 --locked

  7. Install the VSCode extension for insta

    master
    You can enhance your workflow by installing the mitsuhiko.insta VSCode extension. This extension provides syntax highlighting for .snap files and allows you to review snapshots directly within the editor.

  9. Optimize insta performance in dev builds

    master

    Insta performs better when compiled in release mode. You can optimize the insta and similar crates specifically in your Cargo.toml to reduce memory usage and speed up diffing without slowing down your entire dev build.

    [profile.dev.package.insta]
opt-level = 3

[profile.dev.package.similar]
opt-level = 3

  10. Interactive Review Mode shortcuts

    master

    When running cargo insta review, you can interactively manage snapshots using the following keyboard shortcuts:

    • a or Enter: accept (keep the new snapshot)
    • A: accept all remaining snapshots
    • r or Escape: reject (retain the old snapshot)
    • R: reject all remaining snapshots
    • s or Space: skip (keep both for now)
    • S: skip all remaining snapshots
    • i: Toggle extended snapshot info
    • d: Toggle snapshot diff
    • o: open snapshot files in an external tool (available for binary snapshots)

  11. Configure test behavior with Settings

    master

    The insta::Settings struct allows you to customize how snapshot testing behaves on a per-thread basis. You can modify settings like map sorting, snapshot paths, and redactions. Because settings are thread-local, you should use clone_current() to modify existing settings or use bind methods to apply changes temporarily to a specific scope or future.

    use insta;

let mut settings = insta::Settings::clone_current();
settings.set_sort_maps(true);
settings.bind(|| {
    // runs the assertion with the changed settings enabled
    insta::assert_snapshot!(...);
});

  12. Accept or Reject snapshots

    master

    You can bulk accept or reject snapshots using the accept and reject commands.

    • cargo insta accept: Accepts all pending snapshots.
    • cargo insta reject: Rejects all pending snapshots.
    • cargo insta accept --snapshot '<key>': Accepts a specific snapshot.
    • cargo insta reject --snapshot '<key>': Rejects a specific snapshot.