teq

README

teq

teq is a Go library designed to enhance your testing experience by providing a flexible and customizable way to perform deep equality checks. It's especially useful when you need to compare complex objects or types that have specific equality conditions.

Features

• Customizability
  • Transforms: Register a "transform" function that can modify objects before comparison. This allows you to control how equality is determined. For example, by transforming time.Time objects to UTC, you can make your equality checks timezone-insensitive.
  • Equals: Register an "equals" function that defines equality. For example, you can allow specific absolute error for float64.
  • Formats: Register a "format" function that defines how objects are displayed when they are not equal. This is useful for types like time.Time and decimal.Decimal that may not be human-readable in their default format. By registering your own format, you can make the output of your tests more understandable.
• Human readable diff report
  • teq utilizes Akashi for readable diff report.

Installation

go get github.com/seiyab/teq@latest

Usage

To use teq, you first need to create a new instance:

tq := teq.New()

Then, you can add your transforms and formats:

// time.Time will be transformed into UTC time. So equality check with `tq` will be timezone-insensitive.
tq.AddTransform(func(d time.Time) time.Time {
    return d.In(d.UTC)
})

// time.Time will be shown in RFC3339 format when it appear in diff.
tq.AddFormat(func(d time.Time) string {
    return d.Format(time.RFC3339)
})

// Absolute error up to 1e-3 is allowed.
tq.AddEqual(func(a, b float64) bool {
    const epsilon = 1e-3
    return math.Abs(a-b) < epsilon
})

Finally, you can use teq to perform deep equality checks in your tests:

tq.Equal(t, expected, actual)

If you need "common" equality across your project, we recommend to define function that returns your customized teq.

func NewTeq() teq.Teq {
    tq := teq.New()
    tq.AddTransform(/* ... */)
    tq.AddTransform(/* ... */)
    // :
    return tq
}

// then you can easily use it everywhere
tq := NewTeq()

Prior works

• testify
• deepequal.go in "github.com/weaveworks/scope/test/reflect" package authored by Weaveworks Ltd
• go-cmp

Documentation

Overview

Package teq is a Go library designed to enhance your testing experience by providing a flexible and customizable way to perform deep equality checks. It's especially useful when you need to compare complex objects or types that have specific equality conditions.

Features

- Transforms: Register a "transform" function that can modify objects before comparison. This allows you to control how equality is determined. For example, by transforming time.Time objects to UTC, you can make your equality checks timezone-insensitive. - Formats: Register a "format" function that defines how objects are displayed when they are not equal. This is useful for types like time.Time and decimal.Decimal that may not be human-readable in their default format. By registering your own format, you can make the output of your tests more understandable.

Usage

To use teq, you first need to create a new instance:

tq := teq.New()

Then, you can add your transforms and formats:

// time.Time will be transformed into UTC time. So equality check with `tq` will be timezone-insensitive.
tq.AddTransform(func(d time.Time) time.Time {
    return d.In(d.UTC)
})

// time.Time will be shown in RFC3339 format when it appear in diff.
tq.AddFormat(func(d time.Time) string {
    return d.Format(time.RFC3339)
})

Finally, you can use teq to perform deep equality checks in your tests:

tq.Equal(t, expected, actual)

Index

• type Teq
  • func New() Teq
  • func (teq *Teq) AddEqual(equal any)
  • func (teq *Teq) AddFormat(format any)
  • func (teq *Teq) AddTransform(transform any)
  • func (teq Teq) Equal(t TestingT, expected, actual any) bool
  • func (teq Teq) NotEqual(t TestingT, expected, actual any) bool
• type TestingT

Types

type Teq

type Teq struct {
	// MaxDepth is the maximum depth of the comparison. Default is 1000.
	MaxDepth int
	// contains filtered or unexported fields
}

Teq is a object for deep equality comparison.

func New

func New() Teq

New returns new instance of Teq.

func (*Teq) AddEqual

func (teq *Teq) AddEqual(equal any)

AddEqual adds an equal function to Teq. The equal function must have two arguments with the same type and one return value of bool. If the passed equal function is not valid, it will panic. The equal function will be used for equality check instead of the default equality check.

func (*Teq) AddFormat

func (teq *Teq) AddFormat(format any)

AddFormat adds a format function to Teq. The format function must have only one argument and one return value. The argument type is the type to be formatted. If the passed format function is not valid, it will panic. The formatted string will be shown instead of the original value in the error report when the values are not equal.

func (*Teq) AddTransform

func (teq *Teq) AddTransform(transform any)

AddTransform adds a transform function to Teq. The transform function must have only one argument and one return value. The argument type is the type to be transformed. If the passed transform function is not valid, it will panic. The transformed value will be used for equality check instead of the original value. The transformed value and its internal values won't be transformed to prevent infinite recursion.

func (Teq) Equal

func (teq Teq) Equal(t TestingT, expected, actual any) bool

Equal perform deep equality check and report error if not equal.

func (Teq) NotEqual

func (teq Teq) NotEqual(t TestingT, expected, actual any) bool

NotEqual perform deep equality check and report error if equal.

type TestingT

type TestingT interface {
	Helper()
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Log(args ...interface{})
}