go-snaps

Matchers are functions used as the third argument in MatchJSON or MatchYAML to act as property matchers. They allow you to replace specific paths with placeholders or custom validation logic.

Path Syntax:

• JSON: Uses gjson syntax.
• YAML: Uses github.com/goccy/go-yaml path syntax.

Built-in Matchers:

• match.Any(paths...): Replaces targeted paths with a placeholder (default <Any Value>).
  • .Placeholder(value): Sets a custom placeholder.
  • .ErrOnMissingPath(bool): If true (default), errors if the path is missing.
• match.Type[T](paths...): Replaces targeted paths with <Type:T>.
  • .ErrOnMissingPath(bool): If true (default), errors if the path is missing.
• match.Custom(path, func): Allows custom validation. The callback receives the value and should return (any, error). If it returns an error, the test fails.
  • .Placeholder(value): Sets a custom placeholder.
  • .ErrOnMissingPath(bool): If true (default), errors if the path is missing.

// Example match.Any
match.Any("user.name", "user.email")

// Example match.Type
match.Type[string]("user.info")

// Example match.Custom
match.Custom("user.age", func(val any) (any, error) {
    age, ok := val.(float64)
    if !ok {
        return nil, fmt.Errorf("expected number but got %T", val)
    }
    return "some number", nil
})

To identify and manage obsolete (unused) snapshots, you must use TestMain(m *testing.M) to call snaps.Clean(m) after all tests have finished. This ensures go-snaps can accurately track which snapshots were not called during the test suite execution.

• To identify obsolete snapshots: Call snaps.Clean(m). If running with the verbose flag (-v), a Snapshot Summary will be printed.
• To automatically remove obsolete snapshot files: Set the UPDATE_SNAPS environment variable to clean.

Note: snaps.Clean(m) returns a dirty boolean and an err. If dirty is true, it indicates some snapshots were outdated.

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

  // After all tests have run `go-snaps` can check for unused snapshots
  snaps.Clean(m)
  // dirty, err := snaps.Clean(m)
  // _ = err
  // if dirty {
  //   fmt.Println("Some snapshots were outdated.")
  //   os.Exit(1)
  // }

  os.Exit(v)
}

You can customize snapshot behavior using snaps.WithConfig(...). This can be applied to a specific test or used to create a configured instance for multiple calls.

Available Configuration Options:

• snaps.Dir(path): Sets the snapshot directory (relative or absolute).
• snaps.Filename(name): Sets the snapshot filename.
• snaps.Ext(ext): Sets the file extension (e.g., .json).
• snaps.Update(bool): Programmatically controls whether to update snapshots.
• snaps.Label(label): Adds a label to the end of snapshot IDs.
• snaps.Serializer(func(any) string): Custom serializer for non-structured snapshots.
• snaps.Raw(): Helper serializer that uses fmt.Sprint without formatting.
• snaps.JSON(snaps.JSONConfig{...}): Configures JSON formatting:
  • Width: Max width before wrapping (default: 80).
  • Indent: Indentation string (default: 1 space).
  • SortKeys: Whether to sort keys alphabetically (default: true).

s := snaps.WithConfig(
  snaps.Dir("my_dir"),
  snaps.Filename("json_file"),
  snaps.Ext(".json"),
  snaps.Label("JSON"),
  snaps.Update(false),
  snaps.JSON(snaps.JSONConfig{
    Width:    80,
    Indent:   "    ",
    SortKeys: false,
  }),
)

s.MatchJSON(t, `{"hello":"world"}`)