giacomocavalieri.me
馃惁鈥嶁瑳 Snapshot testing in Gleam
4.4 kB
113 lines
1# 馃惁鈥嶁瑳 Birdie - snapshot testing in Gleam
2
3[](https://hex.pm/packages/birdie)
4[](https://hexdocs.pm/birdie/)
5
6Snapshot testing allows you to perform assertions without having to write the
7expectation yourself. Birdie will store a snapshot of the expected value and
8compare future runs of the same test against it. Imagine doing a
9`assert got == expected` where you don't have to take care of writing the
10expected output.
11
12> If you want a video introduction to snapshot testing, you can check out
13> [my talk on the topic](https://youtu.be/DpakV96jeRk?si=ODqE_geVaMIR0Qoa)
14> from Code BEAM Europe.
15
16## Writing snapshot tests with Birdie
17
18First you'll want to add the package to your dependencies:
19
20```sh
21gleam add --dev birdie
22```
23
24To write snapshot tests you can import the `birdie` module and use the
25[`snap`](https://hexdocs.pm/birdie/birdie.html#snap) function:
26
27```gleam
28import gleeunit
29import birdie
30
31pub fn main() {
32 gleeunit.main()
33}
34
35pub fn hello_birdie_test() {
36 "馃惁鈥嶁瑳 Smile for the birdie!"
37 |> birdie.snap(title: "my first snapshot")
38 // All snapshots must have a unique title!
39}
40```
41
42This will record a new snapshot with the given title and content. A snapshot
43test will always fail on its first run until you review and accept it.
44Once you've reviewed and accepted a snapshot, the test will fail only if the
45snapshot's content changes; in that case you will be presented with a diff and
46asked to review it once again.
47
48A typical workflow will look like this:
49
50- Run your tests
51- If you have any new snapshots - or some of the snapshots have changed - some
52 tests will fail
53- Review all the new snapshots deciding if you want to keep the new version or
54 the previously accepted one
55- And don't forget to commit your snapshots! Those should be treated like
56 code and checked with the vcs you're using
57
58## Reviewing snapshots
59
60Birdie also provides a CLI tool to help you in the review process: run
61`gleam run -m birdie` in your project and birdie will help you interactively
62review all your new snapshots.
63
64> The CLI tool can also do more than just guide you through all your snapshots
65> one by one. To check all the available options you can run
66> `gleam run -m birdie help`
67
68
69
70## FAQ
71
72### What should my snapshots be named like?
73
74A good idea is to give snapshots long descriptive titles that clearly state
75what you're expecting to see when reviewing those.
76Also all snapshots _must_ have unique names so that birdie won't mix those up,
77so be careful when naming snapshots to not repeat the same title twice!
78
79> During the review process, Birdie will try to be helpful and show you an
80> error message if it can spot two tests that happen to share the same exact
81> title. It will only work for snapshots that have a literal string as a title
82> but it can be really helpful to spot some of those confusing bugs!
83
84### How big should the snapshot's content be?
85
86My recommendation is strive to have small and cohesive snapshots. Each
87snapshot test should test one thing and one thing only. Having small snapshots
88will make your life way easier during the review process!
89It's better to review 10 small snapshots than a single huge one and you'll
90see better, more focused diffs.
91
92### Why is the snapshot content a `String`? I want to snapshot other things!
93
94Birdie will only ever accept `String` values and it's up to you to turn your
95own Gleam types into a `String` before snapping those. This way you have total
96freedom and will be able to choose a format that makes sense to you and makes
97things easier to review!
98
99The time spent making snapshots nicer is well worth the effort and will pay
100dividends as your test suite grows! You absolutely want to be intentional about
101the look of your snapshots, crafting one that makes it easy to review them.
102[I have an entire talk about this!](https://www.youtube.com/watch?v=DpakV96jeRk)
103
104## References
105
106This package was heavily inspired by the excellent Rust library
107[`insta`](https://insta.rs), do check it out!
108
109## Contributing
110
111If you think there's any way to improve this package, or if you spot a bug don't
112be afraid to open PRs, issues, or requests of any kind!
113Any contribution is welcome 馃挏