# namaka

[![release](https://img.shields.io/github/v/release/nix-community/namaka?logo=github&style=flat-square)](https://github.com/nix-community/namaka/releases)
[![version](https://img.shields.io/crates/v/namaka?logo=rust&style=flat-square)](https://crates.io/crates/namaka)
[![deps](https://deps.rs/repo/github/nix-community/namaka/status.svg?style=flat-square&compact=true)](https://deps.rs/repo/github/nix-community/namaka)
[![license](https://img.shields.io/badge/license-MPL--2.0-blue?style=flat-square)](https://www.mozilla.org/en-US/MPL/2.0)
[![ci](https://img.shields.io/github/actions/workflow/status/nix-community/namaka/ci.yml?label=ci&logo=github-actions&style=flat-square)](https://github.com/nix-community/namaka/actions/workflows/ci.yml)

[Snapshot testing](#snapshot-testing) for Nix based on [haumea]

![](https://user-images.githubusercontent.com/40620903/230751675-b1eb1076-bcd8-4c21-a420-f4c914716bb9.gif)

## 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