{"id":22301331,"url":"https://github.com/kasonbraley/snap","last_synced_at":"2025-10-03T16:48:34.721Z","repository":{"id":246803667,"uuid":"823341344","full_name":"KasonBraley/snap","owner":"KasonBraley","description":"Snapshot testing for Go","archived":false,"fork":false,"pushed_at":"2025-02-12T03:20:33.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T04:24:38.631Z","etag":null,"topics":["go","golang","snapshot","snapshot-testing","testing"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/KasonBraley/snap","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KasonBraley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-07-02T21:20:13.000Z","updated_at":"2025-02-12T03:19:42.000Z","dependencies_parsed_at":"2025-01-30T20:44:33.790Z","dependency_job_id":"6170af97-e9ff-48a5-8503-7209ec6b04d5","html_url":"https://github.com/KasonBraley/snap","commit_stats":null,"previous_names":["kasonbraley/snap"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KasonBraley%2Fsnap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KasonBraley%2Fsnap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KasonBraley%2Fsnap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KasonBraley%2Fsnap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KasonBraley","download_url":"https://codeload.github.com/KasonBraley/snap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245563032,"owners_count":20635907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["go","golang","snapshot","snapshot-testing","testing"],"created_at":"2024-12-03T18:19:52.595Z","updated_at":"2025-10-03T16:48:34.716Z","avatar_url":"https://github.com/KasonBraley.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snap\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/KasonBraley/snap.svg)](https://pkg.go.dev/github.com/KasonBraley/snap)\n\nMinimalistic snapshot testing for Go.\n\nSimilar to the concept of golden files, but instead of a separate file that contains the snapshot,\nthe snapshot is directly in the source code tests.\n\nHighlights:\n\n- Simple, minimal API.\n- Provides automatic updating of the shapshot in code. Can trigger via environment variable `SNAP_UPDATE=1`\n  to update all snapshots at once, or can update one test at a time using the `Update` method.\n- Leverages the powerful [go-cmp](https://github.com/google/go-cmp) package for displaying [rich diffs](#usage)\n  when the snapshot differs from what is expected.\n- Ability to ignore part of the input text by using a special `\u003csnap:ignore\u003e` marker.\n\nLimitations:\n\n- When updating a snapshot that uses the `\u003csnap:ignore\u003e` marker, the marker is overwritten. This can be\n  worked around by undoing that specific line back to the ignore marker(I do this easily with Git hunks),\n  but it is indeed a little annoying to deal with.\n- Updating the snapshot does not currently work if the `snap.Snap` function is assigned to a different variable.\n  Such as `check := snap.Snap`.\n\nInspired by:\n\n- https://tigerbeetle.com/blog/2024-05-14-snapshot-testing-for-the-masses\n- https://ianthehenry.com/posts/my-kind-of-repl/\n- https://speakerdeck.com/mitchellh/advanced-testing-with-go?slide=19\n- https://blog.janestreet.com/using-ascii-waveforms-to-test-hardware-designs/\n\n### Usage\n\n```go\nfunc TestExample(t *testing.T) {\n    checkAddition := func(x int, y int, want *snap.Snapshot) {\n        got := x + y\n        want.Diff(strconv.Itoa(got))\n    }\n\n    checkAddition(2, 2, snap.Snap(t, \"8\")) // should be 4\n}\n```\n\nRunning that test will fail, and prints the diff between the actual result (`4`) from the `checkAddtion`\nfunction, and what is specified in the snapshot:\n\n```bash\n=== RUN   TestExample\n    snap_test.go:149: snap: Snapshot differs: (-want +got):\n          string(\n        -       \"8\",\n        +       \"4\",\n          )\n    snap_test.go:149: snap: Rerun with SNAP_UPDATE=1 environmental variable to update the snapshot.\n--- FAIL: TestExample (0.00s)\n```\n\nTo update that snapshot automatically without manually editing the code, rerun the test with `SNAP_UPDATE=1`\nand it will change `snap.Snap(\"8\")` to `snap.Snap(\"4\")` for you.\n\nThis is a small example, this testing strategy really speeds things up when you have large outputs\nthat need changing, such as large JSON blobs or any substantial amount of text.\n\n### Ignoring data\n\nSometimes you have data in tests that change on each run. Such as timestamps, or random value.\nThese values can be ignored using the special marker `\u003csnap:ignore\u003e`.\n\nThis example shows how to ignore a JSON field. The `timestamp` field in the `person` struct will be ignored when diffing the\nexpected and got data.\n\n```go\nfunc TestSnapJSONWithIgnore(t *testing.T) {\n    checkJSON := func(want *snap.Snapshot) {\n        type person struct {\n            Name string    `json:\"name\"`\n            Age  uint      `json:\"age\"`\n            Time time.Time `json:\"timestamp\"`\n        }\n\n        p := person{\n            Name: \"Doug\",\n            Age:  20,\n            Time: time.Now(),\n        }\n\n        want.DiffJSON(\u0026p, \"  \")\n    }\n\n    checkJSON(\n        snap.Snap(t, `{\n  \"name\": \"Doug\",\n  \"age\": 20,\n  \"timestamp\": \"\u003csnap:ignore\u003e\"\n}`))\n}\n```\n\n### Subtests\n\n[Table-driven tests](https://blog.golang.org/subtests) are also supported.\n`SNAP_UPDATE=1` will work as expected and update the correct subtest:\n\n```go\nfunc TestExample(t *testing.T) {\n\ttype person struct {\n\t\tName string    `json:\"name\"`\n\t\tAge  uint      `json:\"age\"`\n\t\tTime time.Time `json:\"timestamp\"`\n\t}\n\n\ttests := []struct {\n\t\tname         string\n\t\tp            person\n\t\twantSnapshot *snap.Snapshot\n\t}{\n\t\t{\n\t\t\tname: \"basic\",\n\t\t\tp:    person{Name: \"Doug\", Age: 20, Time: time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)},\n\t\t\twantSnapshot: snap.Snap(t, `{\n \"name\": \"Doug\",\n \"age\": 20,\n \"timestamp\": \"2025-01-01T00:00:00Z\"\n}`),\n\t\t},\n\t\t{\n\t\t\tname: \"ignore timestamp\",\n\t\t\tp:    person{Name: \"Doug\", Age: 20, Time: time.Now()},\n\t\t\twantSnapshot: snap.Snap(t, `{\n \"name\": \"Doug\",\n \"age\": 20,\n \"timestamp\": \"\u003csnap:ignore\u003e\"\n}`),\n\t\t},\n\t}\n\n\tfor _, tt := range tests {\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\ttt.wantSnapshot.DiffJSON(tt.p, \" \")\n\t\t})\n\t}\n}\n```\n\n#### Import alias\n\nSnapshot updating still works if you decide to import this package under a different alias, such as:\n\n```go\nimport (\n    \"strconv\"\n    \"testing\"\n    foo \"github.com/KasonBraley/snap\"\n)\n\nfunc TestExample(t *testing.T) {\n    checkAddition := func(x int, y int, want *snap.Snapshot) {\n        got := x + y\n        want.Diff(strconv.Itoa(got))\n    }\n\n    checkAddition(2, 2, foo.Snap(t, \"8\")) // \"foo\" instead of \"snap\" still works when using SNAP_UPDATE=1\n}\n```\n\n### Examples\n\nThe [./examples](./examples) directory showcases some more elaborate use cases for this package, such\nas testing a CLI application.\n\nThe [tests](./snap_test.go) for this package might also serve as a good reference.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkasonbraley%2Fsnap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkasonbraley%2Fsnap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkasonbraley%2Fsnap/lists"}