Snapshots

A snapshot saves the screen to a file the first time, and compares it from then on. It catches changes you weren't testing for: a border that moved, a column that disappeared, a color that changed.

h.Wait("Sencha").AssertSnapshot()

Which kindCopy Anchor Link

Start with text snapshots. Add a JSON snapshot only if a style is what you're testing.

Without a harnessCopy Anchor Link

The snapshot package works on any string, so you can use it without running a program:

snapshot.AssertEqual(t, renderMenu(menu))
snapshot.RequireEqual(t, renderMenu(menu), snapshot.WithSuffix("empty"))

It also has AssertJSONEqual for a JSON string, and AssertScreenEqual for a reel.Screen.

Text snapshotsCopy Anchor Link

AssertSnapshot compares the screen's text with a .snap file. RequireSnapshot does the same, and stops the test if they differ. They're plain text, so they're easy to read and review:

h.Wait("Sencha").
	KeyDown().
	Key("enter").
	Wait("Matcha is ready").
	AssertSnapshot()

That test's snapshot file holds this:

╭──────────────────────────────────────────────────────────────────────╮
│ The Tea Shop                                                         │
│                                                                      │
│  Sencha                                                 green    1m  │
│  Matcha                                                 green    0m  │
│  Gyokuro                                                green    2m  │
│  Oolong                                                 oolong   3m  │
│  Assam                                                  black    4m  │
│  Darjeeling                                             black    3m  │
│  Pu-erh                                                 dark     5m  │
│                                                                      │
│ Matcha is ready                                                      │
│ license tea-8f3a91c2d7                                               │
╰──────────────────────────────────────────────────────────────────────╯
 ↑/↓ choose  / filter  enter brew  q quit                               
                                                                        

ColorCopy Anchor Link

A harness compares the screen's text, which has no color. So AssertSnapshot fails when the text or layout changes, and not when only a color does. To catch that, use a JSON snapshot.

With ANSI, and withoutCopy Anchor Link

The snapshot package also compares any string you give it, such as what a component's View returns. That string can hold ANSI sequences, which are kept by default, so a color change fails the test. Each ESC byte is escaped as the text \x1b, so the file stays printable:

view := (&counter{n: 2}).View()

snapshot.AssertEqual(t, view)
snapshot.AssertEqual(t, view, snapshot.WithANSI(false), snapshot.WithSuffix("plain"))

\x1b[1;38;2;166;216;111mCups\x1b[m \x1b[38;2;214;230;203m++\x1b[m

Keeping ANSI catches more and is harder to review. Strip it when the test is about layout.

What gets normalizedCopy Anchor Link

So that a snapshot is stable, these are applied before comparing:

Your own normalizationCopy Anchor Link

To hide what changes between runs, like a time, add a transform. It runs on the bytes before comparing:

stamp := regexp.MustCompile(`\d{2}:\d{2}:\d{2}`)

h.AssertSnapshot(snapshot.WithTransform(func(b []byte) []byte {
	return stamp.ReplaceAll(b, []byte("00:00:00"))
}))

Better still, give the program a fixed clock in the test.

When it failsCopy Anchor Link

A mismatch prints a unified diff from the file to the screen. An AssertSnapshot that fails lets the test carry on, and a RequireSnapshot doesn't, as with other checks.

JSON snapshotsCopy Anchor Link

AssertJSON and RequireJSON save the screen as JSON: each cell with its content, colors, and attributes, plus the cursor, title, and colors of the terminal.

steep.NewComponentHarness(t, &counter{n: 2}, steep.WithWindowSize(24, 4)).
	Wait("++").
	AssertJSON(snapshot.WithIndent(true))

Move over the cells to see what the snapshot holds for each. This is that test's real file:

{
  "content": "C",
  "style": {
    "fg": "#a6d86f",
    "underline": 0,
    "attrs": 1
  },
  "width": 1
}

What it holdsCopy Anchor Link

Each cell has its content and width, and a style of fg, bg, underline, and attrs. A wide character's second column is an empty cell.

It's the JSON of a reel.Screen, the same as the .json output of an export and of reel still and reel session screen -f json.

FormatCopy Anchor Link

AssertJSON writes compact JSON, one long line. snapshot.WithIndent(true) indents it with tabs, which makes a much larger file, but with diffs that show the cell that changed. Use that if people will read the diffs.

When to use itCopy Anchor Link

JSON snapshots are large, and they change whenever anything on the screen does. They're worth it when you need to check something a text snapshot can't see, such as that an error is red or a selected row is reversed. For a small region, a component harness with a small terminal keeps the file manageable.

Failures don't print a readable diff, since the output is too large. To see what changed, update the snapshot and use git diff, preferably with WithIndent(true), or open a recording in the inspector to look at the cells.

Managing snapshotsCopy Anchor Link

Creating and updatingCopy Anchor Link

A snapshot that doesn't exist fails the test, so a forgotten file can't pass in CI.

Set UPDATE_SNAPSHOTS=true to write the files rather than compare them. Run the tests normally afterward, and read the diff before you commit:

UPDATE_SNAPSHOTS=true go test ./...
git diff testdata/

UPDATE_SNAPS works the same way, for those coming from go-snaps. In code, snapshot.WithUpdate(true) does the same, though it's easy to commit by accident.

Where files goCopy Anchor Link

Snapshots go under testdata, relative to the test's package directory, named after the test:

A .json snapshot follows the same rules with its own count, so a test's first text snapshot and first JSON snapshot don't affect each other.

To use another directory:

Several in one testCopy Anchor Link

Each snapshot in a test takes the next number, so adding one in the middle renumbers the rest. Name them with a suffix to avoid that:

h.Wait("Sencha").AssertSnapshot(snapshot.WithSuffix("menu"))
h.Key("/").Wait("Filter").AssertSnapshot(snapshot.WithSuffix("filter"))

Subtests get a directory of their own, which is a good fit for testing several sizes:

for _, size := range [][2]int{{80, 24}, {40, 12}} {
	t.Run(fmt.Sprintf("%dx%d", size[0], size[1]), func(t *testing.T) {
		steep.NewHarness(t, newModel(), steep.WithWindowSize(size[0], size[1])).
			Wait("Sencha").
			AssertSnapshot()
	})
}

Keeping them usefulCopy Anchor Link

• Commit them, and review their diffs as you would code. An update that nobody reads tests nothing.
• Snapshot fewer screens at smaller sizes. A small snapshot is one someone will read.
• Fix the program's inputs. Fixed times, names, and sizes mean there's nothing to normalize.
• Mark them as generated if the diffs are noisy on GitHub: **/testdata linguist-generated=true in .gitattributes collapses them by default.