Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nix-community/namaka
Snapshot testing for Nix based on haumea [maintainer=@figsoda]
https://github.com/nix-community/namaka
flake flakes golden nix snapshot-testing test testing
Last synced: 7 days ago
JSON representation
Snapshot testing for Nix based on haumea [maintainer=@figsoda]
- Host: GitHub
- URL: https://github.com/nix-community/namaka
- Owner: nix-community
- License: mpl-2.0
- Created: 2023-04-09T02:24:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-13T09:43:34.000Z (3 months ago)
- Last Synced: 2024-10-29T14:54:51.648Z (9 days ago)
- Topics: flake, flakes, golden, nix, snapshot-testing, test, testing
- Language: Rust
- Homepage: https://discourse.nixos.org/t/27125
- Size: 361 KB
- Stars: 108
- Watchers: 5
- Forks: 3
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-nix - namaka - Snapshot testing for Nix based on haumea. (Development / Discovery)
README
# 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]
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`](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