namaka

Snapshot testing for Nix based on [haumea]

Quick Start

bash 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]

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 ... 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):

```toml

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.