🐦‍⬛ Birdie - snapshot testing in Gleam

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() {
 gleeunit.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 💜