# namaka
[](https://github.com/nix-community/namaka/releases)
[](https://crates.io/crates/namaka)
[](https://deps.rs/repo/github/nix-community/namaka)
[](https://www.mozilla.org/en-US/MPL/2.0)
[](https://github.com/nix-community/namaka/actions/workflows/ci.yml)
[Snapshot testing](#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](https://semver.org).
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](https://github.com/nix-community/namaka/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`](nix/load.nix)
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](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](#quick-start) guide,
or refer to [load](#load) for more detailed documentation.
## Related Tools
- Namaka is largely inspired by [insta](https://github.com/mitsuhiko/insta),
a snapshot testing library for Rust.
- Namaka is based on [haumea], which also has some testing functionalities.
[haumea]: https://github.com/nix-community/haumea
[`haumea.load`]: https://github.com/nix-community/haumea#load