go-cmp: github.com/google/go-cmp/cmp Index | Examples | Files | Directories

package cmp

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

Package cmp determines equality of values.

This package is intended to be a more powerful and safer alternative to reflect.DeepEqual for comparing whether two values are semantically equal.

The primary features of cmp are:

• When the default behavior of equality does not suit the needs of the test, custom equality functions can override the equality operation. For example, an equality function may report floats as equal so long as they are within some tolerance of each other.

• Types that have an Equal method may use that method to determine equality. This allows package authors to determine the equality operation for the types that they define.

• If no custom equality functions are used and no Equal method is defined, equality is determined by recursively comparing the primitive kinds on both values, much like reflect.DeepEqual. Unlike reflect.DeepEqual, unexported fields are not compared by default; they result in panics unless suppressed by using an Ignore option (see cmpopts.IgnoreUnexported) or explicitly compared using the AllowUnexported option.

Index

Examples

Package Files

compare.go options.go path.go reporter.go unsafe_reflect.go

func Diff Uses

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

Diff returns a human-readable report of the differences between two values. It returns an empty string if and only if Equal returns true for the same input values and options. The output string will use the "-" symbol to indicate elements removed from x, and the "+" symbol to indicate elements added to y.

Do not depend on this output being stable.

Use Diff for printing out human-readable errors for test cases comparing nested or structured data.

Code:

// Code under test:
type ShipManifest struct {
    Name     string
    Crew     map[string]string
    Androids int
    Stolen   bool
}

// AddCrew tries to add the given crewmember to the manifest.
AddCrew := func(m *ShipManifest, name, title string) {
    if m.Crew == nil {
        m.Crew = make(map[string]string)
    }
    m.Crew[title] = name
}

// Test function:
tests := []struct {
    desc        string
    before      *ShipManifest
    name, title string
    after       *ShipManifest
}{
    {
        desc:   "add to empty",
        before: &ShipManifest{},
        name:   "Zaphod Beeblebrox",
        title:  "Galactic President",
        after: &ShipManifest{
            Crew: map[string]string{
                "Zaphod Beeblebrox": "Galactic President",
            },
        },
    },
    {
        desc: "add another",
        before: &ShipManifest{
            Crew: map[string]string{
                "Zaphod Beeblebrox": "Galactic President",
            },
        },
        name:  "Trillian",
        title: "Human",
        after: &ShipManifest{
            Crew: map[string]string{
                "Zaphod Beeblebrox": "Galactic President",
                "Trillian":          "Human",
            },
        },
    },
    {
        desc: "overwrite",
        before: &ShipManifest{
            Crew: map[string]string{
                "Zaphod Beeblebrox": "Galactic President",
            },
        },
        name:  "Zaphod Beeblebrox",
        title: "Just this guy, you know?",
        after: &ShipManifest{
            Crew: map[string]string{
                "Zaphod Beeblebrox": "Just this guy, you know?",
            },
        },
    },
}

var t fakeT
for _, test := range tests {
    AddCrew(test.before, test.name, test.title)
    if diff := cmp.Diff(test.before, test.after); diff != "" {
        t.Errorf("%s: after AddCrew, manifest differs: (-want +got)\n%s", test.desc, diff)
    }
}

Output:

add to empty: after AddCrew, manifest differs: (-want +got)
{*cmp_test.ShipManifest}.Crew["Galactic President"]:
	-: "Zaphod Beeblebrox"
	+: <non-existent>
{*cmp_test.ShipManifest}.Crew["Zaphod Beeblebrox"]:
	-: <non-existent>
	+: "Galactic President"

add another: after AddCrew, manifest differs: (-want +got)
{*cmp_test.ShipManifest}.Crew["Human"]:
	-: "Trillian"
	+: <non-existent>
{*cmp_test.ShipManifest}.Crew["Trillian"]:
	-: <non-existent>
	+: "Human"

overwrite: after AddCrew, manifest differs: (-want +got)
{*cmp_test.ShipManifest}.Crew["Just this guy, you know?"]:
	-: "Zaphod Beeblebrox"
	+: <non-existent>
{*cmp_test.ShipManifest}.Crew["Zaphod Beeblebrox"]:
	-: "Galactic President"
	+: "Just this guy, you know?"

func Equal Uses

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

Equal reports whether x and y are equal by recursively applying the following rules in the given order to x and y and all of their sub-values:

• If two values are not of the same type, then they are never equal and the overall result is false.

• Let S be the set of all Ignore, Transformer, and Comparer options that remain after applying all path filters, value filters, and type filters. If at least one Ignore exists in S, then the comparison is ignored. If the number of Transformer and Comparer options in S is greater than one, then Equal panics because it is ambiguous which option to use. If S contains a single Transformer, then use that to transform the current values and recursively call Equal on the output values. If S contains a single Comparer, then use that to compare the current values. Otherwise, evaluation proceeds to the next rule.

• If the values have an Equal method of the form "(T) Equal(T) bool" or "(T) Equal(I) bool" where T is assignable to I, then use the result of x.Equal(y) even if x or y is nil. Otherwise, no such method exists and evaluation proceeds to the next rule.

• Lastly, try to compare x and y based on their basic kinds. Simple kinds like booleans, integers, floats, complex numbers, strings, and channels are compared using the equivalent of the == operator in Go. Functions are only equal if they are both nil, otherwise they are unequal. Pointers are equal if the underlying values they point to are also equal. Interfaces are equal if their underlying concrete values are also equal.

Structs are equal if all of their fields are equal. If a struct contains unexported fields, Equal panics unless the AllowUnexported option is used or an Ignore option (e.g., cmpopts.IgnoreUnexported) ignores that field.

Arrays, slices, and maps are equal if they are both nil or both non-nil with the same length and the elements at each index or key are equal. Note that a non-nil empty slice and a nil slice are not equal. To equate empty slices and maps, consider using cmpopts.EquateEmpty. Map keys are equal according to the == operator. To use custom comparisons for map keys, consider using cmpopts.SortMaps.

type Indirect Uses

type Indirect interface {
    PathStep
    // contains filtered or unexported methods
}

Indirect represents pointer indirection on the parent type.

type MapIndex Uses

type MapIndex interface {
    PathStep
    Key() reflect.Value
    // contains filtered or unexported methods
}

MapIndex is an index operation on a map at some index Key.

type Option Uses

type Option interface {
    // contains filtered or unexported methods
}

Option configures for specific behavior of Equal and Diff. In particular, the fundamental Option functions (Ignore, Transformer, and Comparer), configure how equality is determined.

The fundamental options may be composed with filters (FilterPath and FilterValues) to control the scope over which they are applied.

The cmp/cmpopts package provides helper functions for creating options that may be used with Equal and Diff.

Approximate equality for floats can be handled by defining a custom comparer on floats that determines two values to be equal if they are within some range of each other.

This example is for demonstrative purposes; use cmpopts.EquateApprox instead.

Code:

// This Comparer only operates on float64.
// To handle float32s, either define a similar function for that type
// or use a Transformer to convert float32s into float64s.
opt := cmp.Comparer(func(x, y float64) bool {
    delta := math.Abs(x - y)
    mean := math.Abs(x+y) / 2.0
    return delta/mean < 0.00001
})

x := []float64{1.0, 1.1, 1.2, math.Pi}
y := []float64{1.0, 1.1, 1.2, 3.14159265359} // Accurate enough to Pi
z := []float64{1.0, 1.1, 1.2, 3.1415}        // Diverges too far from Pi

fmt.Println(cmp.Equal(x, y, opt))
fmt.Println(cmp.Equal(y, z, opt))
fmt.Println(cmp.Equal(z, x, opt))

Output:

true
false
false

If the Equal method defined on a type is not suitable, the type can be be dynamically transformed to be stripped of the Equal method (or any method for that matter).

Code:

// Suppose otherString.Equal performs a case-insensitive equality,
// which is too loose for our needs.
// We can avoid the methods of otherString by declaring a new type.
type myString otherString

// This transformer converts otherString to myString, allowing Equal to use
// other Options to determine equality.
trans := cmp.Transformer("", func(in otherString) myString {
    return myString(in)
})

x := []otherString{"foo", "bar", "baz"}
y := []otherString{"fOO", "bAr", "Baz"} // Same as before, but with different case

fmt.Println(cmp.Equal(x, y))        // Equal because of case-insensitivity
fmt.Println(cmp.Equal(x, y, trans)) // Not equal because of more exact equality

Output:

true
false

Sometimes, an empty map or slice is considered equal to an allocated one of zero length.

This example is for demonstrative purposes; use cmpopts.EquateEmpty instead.

Code:

alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })

// This option handles slices and maps of any type.
opt := cmp.FilterValues(func(x, y interface{}) bool {
    vx, vy := reflect.ValueOf(x), reflect.ValueOf(y)
    return (vx.IsValid() && vy.IsValid() && vx.Type() == vy.Type()) &&
        (vx.Kind() == reflect.Slice || vx.Kind() == reflect.Map) &&
        (vx.Len() == 0 && vy.Len() == 0)
}, alwaysEqual)

type S struct {
    A   []int
    B   map[string]bool
}
x := S{nil, make(map[string]bool, 100)}
y := S{make([]int, 0, 200), nil}
z := S{[]int{0}, nil} // []int has a single element (i.e., not empty)

fmt.Println(cmp.Equal(x, y, opt))
fmt.Println(cmp.Equal(y, z, opt))
fmt.Println(cmp.Equal(z, x, opt))

Output:

true
false
false

Normal floating-point arithmetic defines == to be false when comparing NaN with itself. In certain cases, this is not the desired property.

This example is for demonstrative purposes; use cmpopts.EquateNaNs instead.

Code:

// This Comparer only operates on float64.
// To handle float32s, either define a similar function for that type
// or use a Transformer to convert float32s into float64s.
opt := cmp.Comparer(func(x, y float64) bool {
    return (math.IsNaN(x) && math.IsNaN(y)) || x == y
})

x := []float64{1.0, math.NaN(), math.E, -0.0, +0.0}
y := []float64{1.0, math.NaN(), math.E, -0.0, +0.0}
z := []float64{1.0, math.NaN(), math.Pi, -0.0, +0.0} // Pi constant instead of E

fmt.Println(cmp.Equal(x, y, opt))
fmt.Println(cmp.Equal(y, z, opt))
fmt.Println(cmp.Equal(z, x, opt))

Output:

true
false
false

To have floating-point comparisons combine both properties of NaN being equal to itself and also approximate equality of values, filters are needed to restrict the scope of the comparison so that they are composable.

This example is for demonstrative purposes; use cmpopts.EquateNaNs and cmpopts.EquateApprox instead.

Code:

alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })

opts := cmp.Options{
    // This option declares that a float64 comparison is equal only if
    // both inputs are NaN.
    cmp.FilterValues(func(x, y float64) bool {
        return math.IsNaN(x) && math.IsNaN(y)
    }, alwaysEqual),

    // This option declares approximate equality on float64s only if
    // both inputs are not NaN.
    cmp.FilterValues(func(x, y float64) bool {
        return !math.IsNaN(x) && !math.IsNaN(y)
    }, cmp.Comparer(func(x, y float64) bool {
        delta := math.Abs(x - y)
        mean := math.Abs(x+y) / 2.0
        return delta/mean < 0.00001
    })),
}

x := []float64{math.NaN(), 1.0, 1.1, 1.2, math.Pi}
y := []float64{math.NaN(), 1.0, 1.1, 1.2, 3.14159265359} // Accurate enough to Pi
z := []float64{math.NaN(), 1.0, 1.1, 1.2, 3.1415}        // Diverges too far from Pi

fmt.Println(cmp.Equal(x, y, opts))
fmt.Println(cmp.Equal(y, z, opts))
fmt.Println(cmp.Equal(z, x, opts))

Output:

true
false
false

Two slices may be considered equal if they have the same elements, regardless of the order that they appear in. Transformations can be used to sort the slice.

This example is for demonstrative purposes; use cmpopts.SortSlices instead.

Code:

// This Transformer sorts a []int.
trans := cmp.Transformer("Sort", func(in []int) []int {
    out := append([]int(nil), in...) // Copy input to avoid mutating it
    sort.Ints(out)
    return out
})

x := struct{ Ints []int }{[]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}}
y := struct{ Ints []int }{[]int{2, 8, 0, 9, 6, 1, 4, 7, 3, 5}}
z := struct{ Ints []int }{[]int{0, 0, 1, 2, 3, 4, 5, 6, 7, 8}}

fmt.Println(cmp.Equal(x, y, trans))
fmt.Println(cmp.Equal(y, z, trans))
fmt.Println(cmp.Equal(z, x, trans))

Output:

true
false
false

The complex numbers complex64 and complex128 can really just be decomposed into a pair of float32 or float64 values. It would be convenient to be able define only a single comparator on float64 and have float32, complex64, and complex128 all be able to use that comparator. Transformations can be used to handle this.

Code:

opts := []cmp.Option{
    // This transformer decomposes complex128 into a pair of float64s.
    cmp.Transformer("T1", func(in complex128) (out struct{ Real, Imag float64 }) {
        out.Real, out.Imag = real(in), imag(in)
        return out
    }),
    // This transformer converts complex64 to complex128 to allow the
    // above transform to take effect.
    cmp.Transformer("T2", func(in complex64) complex128 {
        return complex128(in)
    }),
    // This transformer converts float32 to float64.
    cmp.Transformer("T3", func(in float32) float64 {
        return float64(in)
    }),
    // This equality function compares float64s as rounded integers.
    cmp.Comparer(func(x, y float64) bool {
        return roundF64(x) == roundF64(y)
    }),
}

x := []interface{}{
    complex128(3.0), complex64(5.1 + 2.9i), float32(-1.2), float64(12.3),
}
y := []interface{}{
    complex128(3.1), complex64(4.9 + 3.1i), float32(-1.3), float64(11.7),
}
z := []interface{}{
    complex128(3.8), complex64(4.9 + 3.1i), float32(-1.3), float64(11.7),
}

fmt.Println(cmp.Equal(x, y, opts...))
fmt.Println(cmp.Equal(y, z, opts...))
fmt.Println(cmp.Equal(z, x, opts...))

Output:

true
false
false

func AllowUnexported Uses

func AllowUnexported(types ...interface{}) Option

AllowUnexported returns an Option that forcibly allows operations on unexported fields in certain structs, which are specified by passing in a value of each struct type.

Users of this option must understand that comparing on unexported fields from external packages is not safe since changes in the internal implementation of some external package may cause the result of Equal to unexpectedly change. However, it may be valid to use this option on types defined in an internal package where the semantic meaning of an unexported field is in the control of the user.

For some cases, a custom Comparer should be used instead that defines equality as a function of the public API of a type rather than the underlying unexported implementation.

For example, the reflect.Type documentation defines equality to be determined by the == operator on the interface (essentially performing a shallow pointer comparison) and most attempts to compare *regexp.Regexp types are interested in only checking that the regular expression strings are equal. Both of these are accomplished using Comparers:

Comparer(func(x, y reflect.Type) bool { return x == y })
Comparer(func(x, y *regexp.Regexp) bool { return x.String() == y.String() })

In other cases, the cmpopts.IgnoreUnexported option can be used to ignore all unexported fields on specified struct types.

func Comparer Uses

func Comparer(f interface{}) Option

Comparer returns an Option that determines whether two values are equal to each other.

The comparer f must be a function "func(T, T) bool" and is implicitly filtered to input values assignable to T. If T is an interface, it is possible that f is called with two values of different concrete types that both implement T.

The equality function must be:

• Symmetric: equal(x, y) == equal(y, x)
• Deterministic: equal(x, y) == equal(x, y)
• Pure: equal(x, y) does not modify x or y

func FilterPath Uses

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

FilterPath returns a new Option where opt is only evaluated if filter f returns true for the current Path in the value tree.

The option passed in may be an Ignore, Transformer, Comparer, Options, or a previously filtered Option.

func FilterValues Uses

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

FilterValues returns a new Option where opt is only evaluated if filter f, which is a function of the form "func(T, T) bool", returns true for the current pair of values being compared. If the type of the values is not assignable to T, then this filter implicitly returns false.

The filter function must be symmetric (i.e., agnostic to the order of the inputs) and deterministic (i.e., produces the same result when given the same inputs). If T is an interface, it is possible that f is called with two values with different concrete types that both implement T.

The option passed in may be an Ignore, Transformer, Comparer, Options, or a previously filtered Option.

func Ignore Uses

func Ignore() Option

Ignore is an Option that causes all comparisons to be ignored. This value is intended to be combined with FilterPath or FilterValues. It is an error to pass an unfiltered Ignore option to Equal.

func Transformer Uses

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

Transformer returns an Option that applies a transformation function that converts values of a certain type into that of another.

The transformer f must be a function "func(T) R" that converts values of type T to those of type R and is implicitly filtered to input values assignable to T. The transformer must not mutate T in any way.

To help prevent some cases of infinite recursive cycles applying the same transform to the output of itself (e.g., in the case where the input and output types are the same), an implicit filter is added such that a transformer is applicable only if that exact transformer is not already in the tail of the Path since the last non-Transform step. For situations where the implicit filter is still insufficient, consider using cmpopts.AcyclicTransformer, which adds a filter to prevent the transformer from being recursively applied upon itself.

The name is a user provided label that is used as the Transform.Name in the transformation PathStep. If empty, an arbitrary name is used.

type Options Uses

type Options []Option

Options is a list of Option values that also satisfies the Option interface. Helper comparison packages may return an Options value when packing multiple Option values into a single Option. When this package processes an Options, it will be implicitly expanded into a flat list.

Applying a filter on an Options is equivalent to applying that same filter on all individual options held within.

func (Options) String Uses

func (opts Options) String() string

type Path Uses

type Path []PathStep

Path is a list of PathSteps describing the sequence of operations to get from some root type to the current position in the value tree. The first Path element is always an operation-less PathStep that exists simply to identify the initial type.

When traversing structs with embedded structs, the embedded struct will always be accessed as a field before traversing the fields of the embedded struct themselves. That is, an exported field from the embedded struct will never be accessed directly from the parent struct.

func (Path) GoString Uses

func (pa Path) GoString() string

GoString returns the path to a specific node using Go syntax.

For example:

(*root.MyMap["key"].(*mypkg.MyStruct).MySlices)[2][3].MyField

func (Path) Index Uses

func (pa Path) Index(i int) PathStep

Index returns the ith step in the Path and supports negative indexing. A negative index starts counting from the tail of the Path such that -1 refers to the last step, -2 refers to the second-to-last step, and so on. If index is invalid, this returns a non-nil PathStep that reports a nil Type.

func (Path) Last Uses

func (pa Path) Last() PathStep

Last returns the last PathStep in the Path. If the path is empty, this returns a non-nil PathStep that reports a nil Type.

func (Path) String Uses

func (pa Path) String() string

String returns the simplified path to a node. The simplified path only contains struct field accesses.

For example:

MyMap.MySlices.MyField

type PathStep Uses

type PathStep interface {
    String() string
    Type() reflect.Type // Resulting type after performing the path step
    // contains filtered or unexported methods
}

PathStep is a union-type for specific operations to traverse a value's tree structure. Users of this package never need to implement these types as values of this type will be returned by this package.

type SliceIndex Uses

type SliceIndex interface {
    PathStep
    Key() int // May return -1 if in a split state

    // SplitKeys returns the indexes for indexing into slices in the
    // x and y values, respectively. These indexes may differ due to the
    // insertion or removal of an element in one of the slices, causing
    // all of the indexes to be shifted. If an index is -1, then that
    // indicates that the element does not exist in the associated slice.
    //
    // Key is guaranteed to return -1 if and only if the indexes returned
    // by SplitKeys are not the same. SplitKeys will never return -1 for
    // both indexes.
    SplitKeys() (x int, y int)
    // contains filtered or unexported methods
}

SliceIndex is an index operation on a slice or array at some index Key.

type StructField Uses

type StructField interface {
    PathStep
    Name() string
    Index() int
    // contains filtered or unexported methods
}

StructField represents a struct field access on a field called Name.

type Transform Uses

type Transform interface {
    PathStep
    Name() string
    Func() reflect.Value

    // Option returns the originally constructed Transformer option.
    // The == operator can be used to detect the exact option used.
    Option() Option
    // contains filtered or unexported methods
}

Transform is a transformation from the parent type to the current type.

type TypeAssertion Uses

type TypeAssertion interface {
    PathStep
    // contains filtered or unexported methods
}

TypeAssertion represents a type assertion on an interface.

Bugs

Maps with keys containing NaN values cannot be properly compared due to the reflection package's inability to retrieve such entries. Equal will panic anytime it comes across a NaN key, but this behavior may change. See https://golang.org/issue/11104 for more details.

Directories

PathSynopsis
cmpoptsPackage cmpopts provides common options for the cmp package.
internal/diffPackage diff implements an algorithm for producing edit-scripts.
internal/functionPackage function identifies function types.
internal/testprotos
internal/teststructs
internal/valuePackage value provides functionality for reflect.Value types.

Package cmp imports 10 packages (graph) and is imported by 104 packages. Updated 2018-11-27. Refresh now. Tools for package owners.