snap

README

Snap: Source-based snapshot tests for Go

Snap is a package for automatically updating source-based snapshots tests. A common pattern for Go tests is to store expected outputs in a "golden" file in a testdata/ directory. That is quite convenient for storing and tracking complicated values. But wouldn't it be nice if the expected value was right there in the source code? That is what snap supports.

If you have a test like the following which computes and compares a sha256 hash, it can be annoying to write the correct expected value in the source:

package example_test

import (
    "crypto/sha256"
    "encoding/hex"
    "testing"

    "github.com/jellevandenhooff/snap"
)

func complicated(s string) string {
    b := sha256.Sum256([]byte(s))
    return hex.EncodeToString(b[:16])
}

func TestSnapshot(t *testing.T) {
    actual := complicated("complicated value")
    expected := snap.Source("")
    snap.CheckString(t, actual, expected)
}

func TestMain(m *testing.M) {
    snap.Run(m)
}

If you test this with "go test" you get an error saying the expected value is wrong:

> go test
=== RUN   TestSnapshot
    example_test.go:19: snapshot different; expected "", got "2d5a34155bd3feb0728c3198c41250db"
--- FAIL: TestSnapshot (0.00s)
...

To fix the test we can either copy and paste this expected string... or we can update the snapshots using snap:

> go test -update-snapshots
PASS

Now the test has been updated to include:

expected := snap.Source(`2d5a34155bd3feb0728c3198c41250db`)

And tests pass:

> go test
PASS

In other languages

This package was inspired by source-based snapshot tests in other languages. In Rust there is expect-test and in Ocaml there is "%expect".

Documentation

Overview

Package snap supports source-based snapshot testing. Package snap maintains expected or "golden" values in _test.go files and can update the expected value by rewriting the source.

To make a snapshot test, create a snapshot with Source and test the snapshot with a Check function such as CheckString. Then, call Run in a TestMain function and run tests with "go test -update-snapshots" to update snapshots.

As an example, this is a complete test file with Source, CheckString, and Run. The snapshot is out of date: It should mention "complicated value" but instead it is "old".

package example_test

import (
   "testing"
   "github.com/jellevandenhooff/snap"
)

func TestSnapshot(t *testing.T) {
	magic := "complicated value"
	snap.CheckString(t, magic, snap.Source("old"))
}

func TestMain(m *testing.M) {
	snap.Run(m)
}

Running "go test" will fail because the snapshot is out of date. Running "go test -update-snapshots" will update the snapshot in the file to "snap.Source(`complicated value`)" and afterwards tests will pass.

Index

• func CheckJSON(t *testing.T, actual any, expected *Snapshot)
• func CheckString(t *testing.T, actual string, expected *Snapshot)
• func Run(m *testing.M)
• type Snapshot
  • func Source(input string) *Snapshot

Functions

func CheckJSON

func CheckJSON(t *testing.T, actual any, expected *Snapshot)

CompareString compares a JSON-marshaled with a snapshot.

func CheckString

func CheckString(t *testing.T, actual string, expected *Snapshot)

CheckString compares a string with a snapshot.

func Run

func Run(m *testing.M)

Run should be called from TestMain (see testing.M) to run tests and optionally update snapshots with the "go test -update-snapshots" flag.

Any snapshots in skipped tests will be kept as-is.

Types

type Snapshot

type Snapshot struct {
	// contains filtered or unexported fields
}

A Snapshot is an expected value in a test created by calling Source. See Source on how to use Snapshots.

func Source

func Source(input string) *Snapshot

Source creates a automatically-updated Snapshot.

A Snapshot must be passed to a Check function like CheckJSON to be tested. Each Snapshot can be used only once.

The argument to Source can be automatically updated against actual values using the "go test -update-snapshots" flag; see Run.

Only one call to Source per line is supported.