Approval-based snapshot testing library for Go (mirror)
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Shutter is a snapshot testing library for Go, inspired by Rust's [insta](https://github.com/mitsuhiko/insta) and Gleam's [birdie](https://github.com/giacomocavalieri/birdie). It provides functions for capturing test output as snapshots and tools for reviewing snapshot changes.
8
9## Build Commands
10
11```bash
12# Build the TUI binary
13just build
14
15# Run tests with coverage
16just test
17
18# Clean snapshots and run tests
19just clean-test
20
21# Run the TUI review tool (after building)
22just review
23
24# Run CLI review tool
25just cli
26```
27
28Direct Go commands:
29```bash
30go test ./... # Run all tests
31go test ./... -run TestName # Run specific test
32go test -v ./internal/transform/... # Run tests in specific package
33cd ./cmd/shutter && go build -o shutter ./main.go # Build TUI
34```
35
36## Architecture
37
38```
39┌─────────────────────────────────────────────────────────────────┐
40│ Public API (shutter.go) │
41│ Snap() | SnapMany() | SnapString() | SnapJSON() │
42├─────────────────────────────────────────────────────────────────┤
43│ Options (scrubbers.go, ignore.go) │
44│ Scrubbers: text transformation before snapshot │
45│ IgnorePatterns: field removal (SnapJSON only) │
46├─────────────────────────────────────────────────────────────────┤
47│ Internal Modules │
48│ ├─ internal/snapshots/ - Core comparison logic │
49│ ├─ internal/files/ - Snapshot file I/O (YAML headers) │
50│ ├─ internal/transform/ - JSON ignore pattern application │
51│ ├─ internal/diff/ - Histogram diff algorithm │
52│ ├─ internal/pretty/ - Formatting and display boxes │
53│ └─ internal/review/ - Review workflow logic │
54├─────────────────────────────────────────────────────────────────┤
55│ Review Tools │
56│ ├─ cmd/shutter/ - TUI (Bubbletea) - separate go.mod │
57│ └─ cmd/cli/ - CLI review tool │
58└─────────────────────────────────────────────────────────────────┘
59```
60
61**Data flow:** Test Value → Pretty format (utter) → Ignore Patterns → Scrubbers → Snapshot file
62
63**Snapshot storage:** `__snapshots__/` directories contain YAML-header files with metadata (title, test_name, file_name, version) followed by `---` delimiter and content.
64
65## Key Design Decisions
66
67- **Option interface pattern**: `Scrubber` and `IgnorePattern` both implement `Option` for type-safe compile-time separation
68- **IgnorePatterns only work with SnapJSON()** - using them with Snap/SnapMany/SnapString returns an error
69- **TUI is a separate Go module** (cmd/shutter/) to keep Bubbletea dependencies optional
70- **Execution order**: Ignore patterns run first, then scrubbers
71
72## Module Structure
73
74- Root module (`go.mod`): Main library - Go 1.23.12+
75- TUI module (`cmd/shutter/go.mod`): Separate module with Bubbletea dependencies - Go 1.25.2
76- `/editor/tree-sitter-snapshot/`: Tree-sitter grammar for snapshot format (Node.js/Rust/Python/Swift bindings)