{"id":13562048,"url":"https://github.com/giacomocavalieri/birdie","last_synced_at":"2026-06-15T11:00:28.567Z","repository":{"id":219409290,"uuid":"748982300","full_name":"giacomocavalieri/birdie","owner":"giacomocavalieri","description":"🐦‍⬛ Snapshot testing in Gleam","archived":false,"fork":false,"pushed_at":"2026-05-03T12:17:22.000Z","size":442,"stargazers_count":194,"open_issues_count":1,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-03T12:26:56.544Z","etag":null,"topics":["snapshot-testing"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/birdie/","language":"Gleam","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giacomocavalieri.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["giacomocavalieri"]}},"created_at":"2024-01-27T08:22:07.000Z","updated_at":"2026-05-03T12:17:05.000Z","dependencies_parsed_at":"2024-04-11T09:42:22.220Z","dependency_job_id":"1fdd0b33-4efd-4b86-a7d0-79ac47b32fae","html_url":"https://github.com/giacomocavalieri/birdie","commit_stats":null,"previous_names":["giacomocavalieri/birdie"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/giacomocavalieri/birdie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomocavalieri%2Fbirdie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomocavalieri%2Fbirdie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomocavalieri%2Fbirdie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomocavalieri%2Fbirdie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giacomocavalieri","download_url":"https://codeload.github.com/giacomocavalieri/birdie/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomocavalieri%2Fbirdie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34357285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["snapshot-testing"],"created_at":"2024-08-01T13:01:03.978Z","updated_at":"2026-06-15T11:00:28.502Z","avatar_url":"https://github.com/giacomocavalieri.png","language":"Gleam","funding_links":["https://github.com/sponsors/giacomocavalieri"],"categories":["Gleam","Packages"],"sub_categories":["Testing"],"readme":"# 🐦‍⬛ Birdie - snapshot testing in Gleam\n\n[![Package Version](https://img.shields.io/hexpm/v/birdie)](https://hex.pm/packages/birdie)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/birdie/)\n\nSnapshot testing allows you to perform assertions without having to write the\nexpectation yourself. Birdie will store a snapshot of the expected value and\ncompare future runs of the same test against it. Imagine doing a\n`assert got == expected` where you don't have to take care of writing the\nexpected output.\n\n\u003e If you want a video introduction to snapshot testing, you can check out\n\u003e [my talk on the topic](https://youtu.be/DpakV96jeRk?si=ODqE_geVaMIR0Qoa)\n\u003e from Code BEAM Europe.\n\n## Writing snapshot tests with Birdie\n\nFirst you'll want to add the package to your dependencies:\n\n```sh\ngleam add --dev birdie\n```\n\nTo write snapshot tests you can import the `birdie` module and use the\n[`snap`](https://hexdocs.pm/birdie/birdie.html#snap) function:\n\n```gleam\nimport gleeunit\nimport birdie\n\npub fn main() {\n  gleeunit.main()\n}\n\npub fn hello_birdie_test() {\n  \"🐦‍⬛ Smile for the birdie!\"\n  |\u003e birdie.snap(title: \"my first snapshot\")\n  // All snapshots must have a unique title!\n}\n```\n\nThis will record a new snapshot with the given title and content. A snapshot\ntest will always fail on its first run until you review and accept it.\nOnce you've reviewed and accepted a snapshot, the test will fail only if the\nsnapshot's content changes; in that case you will be presented with a diff and\nasked to review it once again.\n\nA typical workflow will look like this:\n\n- Run your tests\n- If you have any new snapshots - or some of the snapshots have changed - some\n  tests will fail\n- Review all the new snapshots deciding if you want to keep the new version or\n  the previously accepted one\n- And don't forget to commit your snapshots! Those should be treated like\n  code and checked with the vcs you're using\n\n## Reviewing snapshots\n\nBirdie also provides a CLI tool to help you in the review process: run\n`gleam run -m birdie` in your project and birdie will help you interactively\nreview all your new snapshots.\n\n\u003e The CLI tool can also do more than just guide you through all your snapshots\n\u003e one by one. To check all the available options you can run\n\u003e `gleam run -m birdie help`\n\n![image](https://github.com/giacomocavalieri/birdie/blob/main/birdie.gif?raw=true)\n\n## FAQ\n\n### What should my snapshots be named like?\n\nA good idea is to give snapshots long descriptive titles that clearly state\nwhat you're expecting to see when reviewing those.\nAlso all snapshots _must_ have unique names so that birdie won't mix those up,\nso be careful when naming snapshots to not repeat the same title twice!\n\n\u003e During the review process, Birdie will try to be helpful and show you an\n\u003e error message if it can spot two tests that happen to share the same exact\n\u003e title. It will only work for snapshots that have a literal string as a title\n\u003e but it can be really helpful to spot some of those confusing bugs!\n\n### How big should the snapshot's content be?\n\nMy recommendation is strive to have small and cohesive snapshots. Each\nsnapshot test should test one thing and one thing only. Having small snapshots\nwill make your life way easier during the review process!\nIt's better to review 10 small snapshots than a single huge one and you'll\nsee better, more focused diffs.\n\n### Why is the snapshot content a `String`? I want to snapshot other things!\n\nBirdie will only ever accept `String` values and it's up to you to turn your\nown Gleam types into a `String` before snapping those. This way you have total\nfreedom and will be able to choose a format that makes sense to you and makes\nthings easier to review!\n\nThe time spent making snapshots nicer is well worth the effort and will pay\ndividends as your test suite grows! You absolutely want to be intentional about\nthe look of your snapshots, crafting one that makes it easy to review them.\n[I have an entire talk about this!](https://www.youtube.com/watch?v=DpakV96jeRk)\n\n## References\n\nThis package was heavily inspired by the excellent Rust library\n[`insta`](https://insta.rs), do check it out!\n\n## Contributing\n\nIf you think there's any way to improve this package, or if you spot a bug don't\nbe afraid to open PRs, issues, or requests of any kind!\nAny contribution is welcome 💜\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiacomocavalieri%2Fbirdie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiacomocavalieri%2Fbirdie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiacomocavalieri%2Fbirdie/lists"}