eqtest

README

Eqtest - Equality test assertions with go-cmp

Eqtest provides equality test assertions API using go-cmp. It is not designed to compete or replace existing assertion frameworks such as testify, but rather to complement where it lacks such as proper equality comparison for complex types.

Quick Start

To start using eqtest, simply call eqtest.New from your Go test files:

package mypkg_test

import (
    "testing"

    "github.com/adzil/eqtest"
)

func TestSomething_Simple(t *testing.T) {
    eqtest.Equal(t, "hello", "world") // This should fail the test.
}

func TestSomething_WithNew(t *testing.T) {
    eqt := eqtest.New(t)

    eqt.Equal("hello", "world") // This should fail the test.
}

Using cmp.Option

There are three ways to add cmp.Option during the assertion:

1. During New initialization

This will be useful if all of the assertions require the options such as transformers.

eqtest.New(t, cmp.Transformer(...))

2. Chain the option using With

This will be useful if there are subset of the assertions that need to have the same options such as filters.

eqt := eqtest.New(t).With(cmpopts.IgnoreFields(MyStruct{}, "FieldOne"))

eqt.Equal(...)
eqt.Equal(...)

3. During the call to Equal or MustEqual

This will be useful if an assertion needs a specific filter that doesn't needed by the others.

eqtest.New(t).Equal(expected, actual,
    cmpopts.IgnoreFields(MyStruct{}, "FieldTwo"),
)

Reusing cmp.Options from existing Assertion

If there are subtests that sharing the same cmp.Option as the current test, the existing Assertion can be cloned easily using a different *testing.T by calling Assertion.Using:

func TestSomething(t *testing.T) {
    eqt := eqtest.New(t,
        cmpopts.SomeOption(...),
        cmpopts.SomeOption(...),
    )

    t.Run("subtest with identical cmp options", func(t *testing.T) {
        eqt := eqt.With(t)

        // Now the eqt will refer to the subtest t instead of the parent t.
        eqt.Equal(...)
    })
}

Documentation

Index

• func Equal(t T, expected, actual any, opts ...cmp.Option) bool
• func MustEqual(t T, expected, actual any, opts ...cmp.Option) bool
• type Assertion
  • func New(t T, opts ...cmp.Option) *Assertion
  • func (a *Assertion) Equal(expected, actual any, opts ...cmp.Option) bool
  • func (a *Assertion) MustEqual(expected, actual any, opts ...cmp.Option) bool
  • func (a *Assertion) Using(t T) *Assertion
  • func (a *Assertion) With(opts ...cmp.Option) *Assertion
• type T

Functions

func Equal

func Equal(t T, expected, actual any, opts ...cmp.Option) bool

Equal is a convenience function for New followed by an Assertion.Equal.

func MustEqual

func MustEqual(t T, expected, actual any, opts ...cmp.Option) bool

MustEqual is a convenience function for New followed by a Assertion.MustEqual.

Types

type Assertion

type Assertion struct {
	// contains filtered or unexported fields
}

Assertion implements equality test assertions using go-cmp.

func New

func New(t T, opts ...cmp.Option) *Assertion

New returns a new Assertion using an instance of *testing.T.

func (*Assertion) Equal

func (a *Assertion) Equal(expected, actual any, opts ...cmp.Option) bool

Equal asserts the equality of expected and actual.

func (*Assertion) MustEqual

func (a *Assertion) MustEqual(expected, actual any, opts ...cmp.Option) bool

MustEqual asserts the equality of expected and actual, and immediately stop the test execution on failure.

func (*Assertion) Using

func (a *Assertion) Using(t T) *Assertion

Using returns a copy of Assertion that uses a different *testing.T.

func (*Assertion) With

func (a *Assertion) With(opts ...cmp.Option) *Assertion

With adds new cmp.Option to the Assertion options.

type T

type T interface {
	Helper()
	Log(args ...any)
	Fail()
	FailNow()
}