namaka

Snapshot testing for Nix based on haumea

Quick Start

nix flake init -t github:nix-community/namaka
nix develop # add namaka to the environment
namaka check # run checks
namaka review # review pending snapshots

Versioning

Namaka follows semantic versioning. Breaking changes can happen in main branch at any time, so it is recommended to pin namaka to a specific tag. A list of available versions can be found on the releases page.

Usage

Usage: namaka [OPTIONS] [DIR] <COMMAND>

Commands:
  check   Wrapper around `nix flake check` to prepare snapshots for failed tests [aliases: c]
  clean   Remove unused and pending snapshots [aliases: cl]
  review  Review pending snapshots and selectively accept or reject them [aliases: r]
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [DIR]  Change to this working directory

Options:
  -c, --cmd <CMD>...  Command to run instead of `nix flake check`
  -h, --help          Print help (see more with '--help')
  -V, --version       Print version

load

Type: { ... } -> { }

Wrapper around haumea.load to load snapshot tests from a directory.

It throws an error if any of the tests fail, otherwise it always returns { }. load { src = ./tests; } will load tests from the tests directory, which should be structured like this:

tests
├─ foo/
│  ├─ expr.nix
└─ bar/
   ├─ expr.nix
   └─ format.nix (optional)

expr.nix contains the Nix expression you want to test.

format.nix contains a Nix string specifying how the expression should be serialized. Here are the possible values:

• "json" serializes the expression using builtins.toJSON (default)
• "pretty" serializes the expression using lib.generators.toPretty { }
• "string" serializes the string as is

See the tests directory or one of the templates for an example. Ignore the _snapshots directory, as it is automatically generated by namaka.

The rest of the available options are documented in haumea.load, as they will function exactly the same.

Configuration

namaka will try to read namaka.toml in the working directory. Here is an example configuration file (all fields are optional):

# namaka.toml

# change the working directory
# this stacks with the command line option
#`namaka check bar` will read `bar/namaka.toml` and change the working directory to `bar/foo`
dir = "foo"

[check]
# the command to run with `namaka check`
# defaults to `nix flake check --extra-experimental-features "flakes nix-command"`
cmd = ["nix", "eval", "./dev#checks"]

[eval]
# the command to run with `namaka review` and `namaka clean`
# defaults to `nix eval ./checks --extra-experimental-features "flakes nix-command"`
cmd = ["nix", "flake", "check"]

Snapshot Testing

Snapshot testing is a strategy that allows you to write tests without manually writing reference values. Instead of assert foo == bar;, you only need to have foo, and namaka will store bar in a snapshot file and ask you to update it with namaka review.

To start, you can follow the Quick Start guide, or refer to load for more detailed documentation.

Related Tools

• Namaka is largely inspired by insta, a snapshot testing library for Rust.
• Namaka is based on haumea, which also has some testing functionalities.