deep

README

Deep Variable Equality for Humans

This package provides a single function: deep.Equal. It's like reflect.DeepEqual but much friendlier to humans (or any sentient being) for two reason:

• deep.Equal returns a list of differences
• deep.Equal does not compare unexported fields (by default)

reflect.DeepEqual is good (like all things Golang!), but it's a game of Hunt the Wumpus. For large maps, slices, and structs, finding the difference is difficult.

deep.Equal doesn't play games with you, it lists the differences:

package main_test

import (
	"testing"
	"github.com/go-test/deep"
)

type T struct {
	Name    string
	Numbers []float64
}

func TestDeepEqual(t *testing.T) {
	// Can you spot the difference?
	t1 := T{
		Name:    "Isabella",
		Numbers: []float64{1.13459, 2.29343, 3.010100010},
	}
	t2 := T{
		Name:    "Isabella",
		Numbers: []float64{1.13459, 2.29843, 3.010100010},
	}

	if diff := deep.Equal(t1, t2); diff != nil {
		t.Error(diff)
	}
}

$ go test
--- FAIL: TestDeepEqual (0.00s)
        main_test.go:25: [Numbers.slice[1]: 2.29343 != 2.29843]

The difference is in Numbers.slice[1]: the two values aren't equal using Go ==.

Documentation

Overview

Package deep provides function deep.Equal which is like reflect.DeepEqual but returns a list of differences. This is helpful when comparing complex types like structures and maps.

Index

• Constants
• Variables
• func Equal(a, b interface{}, flags ...interface{}) []string

Constants

const (
	// FLAG_NONE is a placeholder for default Equal behavior. You don't have to
	// pass it to Equal; if you do, it does nothing.
	FLAG_NONE byte = iota

	// FLAG_IGNORE_SLICE_ORDER causes Equal to ignore slice order so that
	// []int{1, 2} and []int{2, 1} are equal. Only slices of primitive scalars
	// like numbers and strings are supported. Slices of complex types,
	// like []T where T is a struct, are undefined because Equal does not
	// recurse into the slice value when this flag is enabled.
	FLAG_IGNORE_SLICE_ORDER
)

Variables

var (
	// FloatPrecision is the number of decimal places to round float values
	// to when comparing.
	FloatPrecision = 10

	// MaxDiff specifies the maximum number of differences to return.
	MaxDiff = 10

	// MaxDepth specifies the maximum levels of a struct to recurse into,
	// if greater than zero. If zero, there is no limit.
	MaxDepth = 0

	// LogErrors causes errors to be logged to STDERR when true.
	LogErrors = false

	// CompareUnexportedFields causes unexported struct fields, like s in
	// T{s int}, to be compared when true. This does not work for comparing
	// error or Time types on unexported fields because methods on unexported
	// fields cannot be called.
	CompareUnexportedFields = false

	// CompareFunctions compares functions the same as reflect.DeepEqual:
	// only two nil functions are equal. Every other combination is not equal.
	// This is disabled by default because previous versions of this package
	// ignored functions. Enabling it can possibly report new diffs.
	CompareFunctions = false

	// NilSlicesAreEmpty causes a nil slice to be equal to an empty slice.
	NilSlicesAreEmpty = false

	// NilMapsAreEmpty causes a nil map to be equal to an empty map.
	NilMapsAreEmpty = false

	// NilPointersAreZero causes a nil pointer to be equal to a zero value.
	NilPointersAreZero = false
)

var (
	// ErrMaxRecursion is logged when MaxDepth is reached.
	ErrMaxRecursion = errors.New("recursed to MaxDepth")

	// ErrTypeMismatch is logged when Equal passed two different types of values.
	ErrTypeMismatch = errors.New("variables are different reflect.Type")

	// ErrNotHandled is logged when a primitive Go kind is not handled.
	ErrNotHandled = errors.New("cannot compare the reflect.Kind")
)

Functions

func Equal

func Equal(a, b interface{}, flags ...interface{}) []string

Equal compares variables a and b, recursing into their structure up to MaxDepth levels deep (if greater than zero), and returns a list of differences, or nil if there are none. Some differences may not be found if an error is also returned.

If a type has an Equal method, like time.Equal, it is called to check for equality.

When comparing a struct, if a field has the tag `deep:"-"` then it will be ignored.