# 🐦‍⬛ Birdie - snapshot testing in Gleam

[![Package Version](](
[![Hex Docs](](
![Supported targets](

Snapshot testing allows you to perform assertions without having to write the
expectation yourself. Birdie will store a snapshot of the expected value and
compare future runs of the same test against it. Imagine doing a
`should.equal(expected, got)` where you don't have to take care of writing the
expected output.

## Writing snapshot tests with Birdie

First you'll want to add the package to your dependencies:

gleam add --dev birdie

To write snapshot tests you can import the `birdie` module and use the
[`snap`]( function:

import gleeunit
import birdie

pub fn main() {

pub fn hello_birdie_test() {
  "🐦‍⬛ Smile for the birdie!"
  |> birdie.snap(title: "my first snapshot")
  // All snapshots must have a unique title!

This will record a new snapshot with the given title and content. A snapshot
test will always fail on its first run until you review and accept it.
Once you've reviewed and accepted a snapshot, the test will fail only if the
snapshot's content changes; in that case you will be presented with a diff and
asked to review it once again.

A typical workflow will look like this:

- Run your tests
- If you have any new snapshots - or some of the snapshots have changed - some
  tests will fail
- Review all the new snapshots deciding if you want to keep the new version or
  the previously accepted one
- And don't forget to commit your snapshots! Those should be treated like
  code and checked with the vcs you're using

## Reviewing snapshots

Birdie also provides a CLI tool to help you in the review process: run
`gleam run -m birdie` in your project and birdie will help you interactively
review all your new snapshots.

> The CLI tool can also do more than just guide you through all your snapshots
> one by one. To check all the available options you can run
> `gleam run -m birdie help`


## References

This package was heavily inspired by the excellent Rust library
[`insta`](, do check it out!

## Contributing

If you think there's any way to improve this package, or if you spot a bug don't
be afraid to open PRs, issues or requests of any kind!
Any contribution is welcome 💜