go-cmp

go-cmp is a powerful and safer alternative to reflect.DeepEqual for comparing whether two values are semantically equal in Go. It is designed primarily for testing purposes and offers extensive customization through options.

Package Information

• Package Name: go-cmp
• Package Type: golang
• Language: Go
• Installation: go get github.com/google/go-cmp/cmp
• Import Path: github.com/google/go-cmp/cmp

Core Imports

import "github.com/google/go-cmp/cmp"

For common options:

import "github.com/google/go-cmp/cmp/cmpopts"

Basic Usage

import (
    "testing"
    "github.com/google/go-cmp/cmp"
)

func TestStructEquality(t *testing.T) {
    type Person struct {
        Name string
        Age  int
    }

    got := Person{Name: "Alice", Age: 30}
    want := Person{Name: "Alice", Age: 30}

    if !cmp.Equal(got, want) {
        t.Errorf("Person mismatch (-want +got):\n%s", cmp.Diff(want, got))
    }
}

Architecture

The go-cmp package provides two core packages:

1. cmp - Core comparison functionality with Equal and Diff functions, plus a rich option system
2. cmpopts - Common pre-built options for typical comparison scenarios

The package uses an Option-based configuration system that allows customizing comparison behavior through:

• Comparers - Custom equality functions for specific types
• Transformers - Value transformations before comparison
• Filters - Path and value-based filtering to control option application
• Ignore - Selective ignoring of fields or values

Capabilities

Core Comparison Functions

Compare values for equality and generate human-readable diffs.

func Equal(x, y interface{}, opts ...Option) bool

func Diff(x, y interface{}, opts ...Option) string

Core Comparison

Options and Customization

Configure comparison behavior with custom equality functions, transformers, and filters.

type Option interface {
    // Has unexported methods
}

func Comparer(f interface{}) Option

func Transformer(name string, f interface{}) Option

func Ignore() Option

func FilterPath(f func(Path) bool, opt Option) Option

func FilterValues(f interface{}, opt Option) Option

Options and Customization

Path Navigation and Reporting

Navigate the comparison tree and implement custom reporting.

type Path []PathStep

type PathStep interface {
    String() string
    Type() reflect.Type
    Values() (vx, vy reflect.Value)
}

func Reporter(r interface{
    PushStep(PathStep)
    Report(Result)
    PopStep()
}) Option

Path Navigation and Reporting

Common Options (cmpopts)

Pre-built options for common comparison scenarios including approximate equality, sorting, and ignoring fields.

func EquateEmpty() cmp.Option

func EquateApprox(fraction, margin float64) cmp.Option

func IgnoreFields(typ interface{}, names ...string) cmp.Option

func IgnoreUnexported(typs ...interface{}) cmp.Option

func SortSlices(lessOrCompareFunc interface{}) cmp.Option

Common Options (cmpopts)

Types

Option Types

type Options []Option

Options is a list of Option values that also satisfies the Option interface.

Methods:

• String() string - Returns string representation

Result Type

type Result struct {
    // Has unexported fields
}

Result represents the comparison result for a single node.

Methods:

• Equal() bool - Reports whether the node was determined to be equal
• ByIgnore() bool - Reports whether the node is equal because it was ignored
• ByFunc() bool - Reports whether a Comparer function determined equality
• ByMethod() bool - Reports whether the Equal method determined equality
• ByCycle() bool - Reports whether a reference cycle was detected