Skip to main content

Go-Snaps

Go-Snaps

Snapshot testing library for Go applications

Go-Snaps is a snapshot testing library for Go used in the Control Plane to verify that complex outputs match expected values.

Snapshot testing

Snapshot testing captures a component's output and compares it to a previously saved reference output (the "snapshot"). This approach is particularly useful for testing complex structures that are difficult to verify with traditional assertions.

Overview​

Go-Snaps provides a simple, effective way to implement snapshot testing in Go applications. It's particularly valuable for testing complex data structures, API responses, and generated code.

Go-Snaps Logo

Why Go-Snaps?​

📸 Snapshot Capture

Automatically save output snapshots for future comparisons.

🔄 Snapshot Updates

Update snapshots when expected behavior changes.

📊 Diff Generation

Clear visualization of differences between current output and snapshot.

🧩 Custom Serializers

Support for custom serialization of complex types.

⏱️ Inline Snapshots

Store small snapshots directly in test files.

🔧 CLI Integration

Command-line tools for managing snapshots.

Integration in the Control Plane​

Complex output testing

In the Control Plane, Go-Snaps is used to test components that produce complex outputs such as CRD generators, API responses, and resource templates.

The Control Plane uses Go-Snaps for testing various components:

API Responses

Testing the structure and content of API responses:

  • JSON response bodies
  • Error response formats
  • Pagination structures
  • Content negotiation results

Resource Templates

Verifying generated Kubernetes resources:

  • Deployment manifests
  • Service configurations
  • ConfigMap content
  • CRD definitions

Code Generation

Testing output of code generators:

  • Controller boilerplate
  • Client code
  • Schema validation
  • Documentation generation

Configuration Processing

Testing configuration transformation logic:

  • Config file parsing
  • Environment variable processing
  • Default value application
  • Validation error messages

Configuration​

Snapshot configuration and formats

Go-Snaps provides various configuration options and supports multiple data formats commonly used in the Control Plane.

Snapshot Storage​

By default, Go-Snaps stores snapshots in a __snapshots__ directory next to your test files:

pkg/controller/
  ├── controller_test.go
  ├── __snapshots__/
  │   └── controller_test.snap
  └── controller.go

Snapshots are stored in a readable format that's version control friendly.

Supported Formats​

MatchJSON

Match JSON data with normalized formatting.

MatchYAML

Match YAML data with normalized formatting.

MatchInline

Store small snapshots directly in test files.

Match

Match any serializable data structure.

MatchText

Match text content without normalization.

MatchSnapshot

Low-level API for custom matching.

Advanced Features​

Custom Serializers

Define custom serialization for complex types

Update Mode

Update snapshots when behavior changes

Exclusion Paths

Exclude dynamic fields from comparison

Inline Snapshots

Store small snapshots directly in test files

CLI Usage​

Go-Snaps provides a command-line tool for managing snapshots:

# Install the CLI
go install github.com/gkampitakis/go-snaps/cmd/go-snaps@latest

# Show differences in snapshots
go-snaps diff

# Clean up unused snapshots
go-snaps cleanup

# Update all snapshots
go-snaps update

# Update specific snapshots
go-snaps update --test TestDeploymentController

Best Practices in the Control Plane​

Effective snapshot testing

The Control Plane follows these best practices for effective snapshot testing.

🎯 Test Focused Cases

Create separate snapshots for specific behaviors rather than large, catch-all snapshots.

💾 Version Control Snapshots

Always commit snapshot files to version control alongside code changes.

🧹 Regular Cleanup

Use 'go-snaps cleanup' periodically to remove orphaned snapshots.

🔍 Code Review Snapshots

Review snapshot changes carefully during code reviews to catch unintended changes.

⏱️ Normalize Timestamps

Use custom serializers or exclusion paths to handle dynamic values like timestamps.

📝 Descriptive Test Names

Use clear, descriptive test names that explain what the snapshot represents.

Ginkgo

BDD-style testing framework for Go applications.

View Ginkgo

Gomega

Matcher/assertion library that works well with Go-Snaps.

View Gomega

Testify

Another testing toolkit used in the Control Plane.

View Testify