go-snaps

Go Snaps

Jest-like snapshot testing in Golang

Highlights

• Installation
• MatchSnapshot
• MatchJSON
• Update Snapshots
  • Clean obsolete Snapshots
  • Skipping Tests
• No Color
• Snapshots Structure
• Acknowledgments
• Contributing
• Notes

Installation

To install go-snaps, use go get:

go get github.com/gkampitakis/go-snaps

Import the go-snaps/snaps package into your code:

package example

import (
  "testing"

  "github.com/gkampitakis/go-snaps/snaps"
)

func TestExample(t *testing.T) {

  snaps.MatchSnapshot(t ,"Hello World")

}

MatchSnapshot

MatchSnapshot can be used to capture any type of data structured or unstructured.

You can pass multiple parameters to MatchSnapshot or call MatchSnapshot multiple times inside the same test. The difference is in the latter, it will create multiple entries in the snapshot file.

// test_simple.go

func TestSimple(t *testing.T) {
  t.Run("should make multiple entries in snapshot", func(t *testing.T) {
    snaps.MatchSnapshot(t, 5, 10, 20, 25)
    snaps.MatchSnapshot(t, "some value")
  })
}

go-snaps saves the snapshots in __snapshots__ directory and the file name is the test file name with extension .snap.

So for example if your test is called test_simple.go when you run your tests, a snapshot file will be created at ./__snapshots__/test_simple.snaps.

MatchJSON

MatchJSON can be used to capture data that can represent a valid json.

You can pass a valid json in form of string or []byte or whatever value can be passed successfully on json.Marshal.

func TestJSON(t *testing.T) {
  type User struct {
    Age int
    Email string
  }

  snaps.MatchJSON(t, `{"user":"mock-user","age":10,"email":"mock@email.com"}`)
  snaps.MatchJSON(t, []byte(`{"user":"mock-user","age":10,"email":"mock@email.com"}`))
  snaps.MatchJSON(t, User{10, "mock-email"})
}

JSON will be saved in snapshot in pretty format for more readability.

Update Snapshots

You can update your failing snapshots by setting UPDATE_SNAPS env variable to true.

UPDATE_SNAPS=true go test ./...

If you don't want to update all failing snapshots, or you want to update one of them you can you use the -run flag to target the test/s you want.

For more information for go test flags you can run

go help testflag

Clean obsolete snapshots

go-snaps can identify obsolete snapshots.

In order to enable this functionality you need to use the TestMain(t*testing.M) and call snaps.Clean(t). This will also print a Snapshot Summary. (if running tests with verbose flag -v)

If you want to remove the obsolete snap files and snapshots you can run tests with UPDATE_SNAPS=true env variable.

The reason for using TestMain, is because go-snaps needs to be sure that all tests are finished so it can keep track which snapshots were not called.

Example:

func TestMain(t *testing.M) {
  v := t.Run()

  // After all tests have run `go-snaps` can check for not used snapshots
  snaps.Clean(t)

  os.Exit(v)
}

For more information around TestMain.

Skipping Tests

If you want to skip one test using t.Skip, go-snaps can't keep track if the test was skipped or if it was removed. For that reason go-snaps exposes a wrapper for t.Skip, t.Skipf and t.SkipNow, which keep tracks of skipped files.

You can skip, or only run specific tests by using the -run flag. go-snaps can identify which tests are being skipped and parse only the relevant tests for obsolete snapshots.

No Color

go-snaps supports disabling color outputs by running your tests with the env variable NO_COLOR set to any value.

NO_COLOR=true go test ./...

For more information around NO_COLOR.

Snapshots Structure

Snapshots have the form

[ TestName - Number ]
<data>
---

TestID is the test name plus an increasing number ( allowing to do multiple calls of MatchSnapshot inside a test ).

[TestSimple/should_make_a_map_snapshot - 1]
map[string]interface {}{
    "mock-0": "value",
    "mock-1": int(2),
    "mock-2": func() {...},
    "mock-3": float32(10.399999618530273),
}
---

*.snap files are not meant to be edited manually, this might cause unexpected results.

Acknowledgments

This library used Jest Snapshoting and Cupaloy as inspiration.

• Jest is a full-fledged Javascript testing framework and has robust snapshoting features.
• Cupaloy is a great and simple Golang snapshoting solution.
• The logo was made by MariaLetta.

Notes

1. ⚠️ When running a specific test file by specifying a path go test ./my_test.go, go-snaps can't track the path so it will mistakenly mark snapshots as obsolete.

2. The order in which tests are written might not be the same order that snapshots are saved in the file.

3. If your snapshot data contain the termination characters --- at the start of a line and after a new line, go-snaps will "escape" them and save them as /-/-/-/. This should not cause any diff issues (false-positives).

4. Snapshots should be treated as code. The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process