testcmp

README

testcmp

A thin Go library that bridges testify and go-cmp. It provides assertion helpers that use cmp.Diff under the hood, giving you structured, readable diffs on failure while keeping the testify style you already use.

Install

go get github.com/rnaveiras/testcmp

Requires Go 1.24 or later.

Quick start

import "github.com/rnaveiras/testcmp"

func TestGetSupplier(t *testing.T) {
    want := Supplier{Name: "Acme Corp", Status: StatusActive}
    got  := store.GetSupplier(ctx, "acme")

    testcmp.Equal(t, want, got)
}

On failure you get a clear diff:

Error:    mismatch (-want +got):
          - Name: "Alice"
          + Name: "Bob"

Option helpers

All helpers return a cmp.Option and live in the same package, so a single import covers both assertions and options.

IgnoreTimestamps

Ignores all time.Time fields during comparison.

testcmp.Equal(t, want, got, testcmp.IgnoreTimestamps())

IgnoreAuditFields

Ignores CreatedAt, UpdatedAt, CreatedBy, and UpdatedBy.

testcmp.Equal(t, want, got, testcmp.IgnoreAuditFields())

IgnoreIDs

Ignores struct fields named exactly "ID" or ending with a lowercase letter followed by "ID", matching the standard Go naming convention (e.g. ID, SupplierID, UserID). Fields like VALID or SQUID are not matched.

testcmp.Equal(t, want, got, testcmp.IgnoreIDs())

Proto (sub-package)

The testcmp/proto sub-package provides protobuf support via protocmp.Transform(), keeping google.golang.org/protobuf out of the core module's dependency tree.

import "github.com/rnaveiras/testcmp/proto"

testcmp.Equal(t, want, got, proto.Transform())

Combining options

Options compose naturally:

testcmp.Equal(t, want, got,
    testcmp.IgnoreAuditFields(),
    testcmp.IgnoreIDs(),
    proto.Transform(),
)

API

Assertions

func Equal[T any](t testcmp.TestingT, want, got T, opts ...cmp.Option) bool
func NotEqual[T any](t testcmp.TestingT, want, got T, opts ...cmp.Option) bool

TestingT requires Errorf and Helper, satisfied by *testing.T, *testing.B, and testify suite types.

Both return bool matching testify's convention, so you can gate further assertions:

if testcmp.Equal(t, want, got) {
    // safe to assert on got.Field
}

Dependencies

Dependency	Reason
github.com/google/go-cmp	Diff and comparison engine
google.golang.org/protobuf	protocmp.Transform() (only in testcmp/proto sub-module)

License

MIT

Documentation

Overview

Package testcmp bridges testify and go-cmp, providing assertion helpers that use cmp.Diff under the hood for structured, readable diffs on failure while keeping the testify style.

It also ships pre-built cmp.Option helpers covering the most common cases: timestamps, IDs, and audit fields.

Example:

testcmp.Equal(t, want, got, testcmp.IgnoreTimestamps())

Index

• func Equal[T any](t TestingT, want, got T, opts ...cmp.Option) bool
• func IgnoreAuditFields() cmp.Option
• func IgnoreIDs() cmp.Option
• func IgnoreTimestamps() cmp.Option
• func NotEqual[T any](t TestingT, want, got T, opts ...cmp.Option) bool
• type TestingT

Functions

func Equal

func Equal[T any](t TestingT, want, got T, opts ...cmp.Option) bool

Equal asserts that want and got are equal using cmp.Diff. opts are passed directly to cmp.Diff.

Example:

testcmp.Equal(t, want, got, testcmp.IgnoreTimestamps())

func IgnoreAuditFields

func IgnoreAuditFields() cmp.Option

IgnoreAuditFields returns an option that ignores common audit fields by name: CreatedAt, UpdatedAt, CreatedBy, UpdatedBy.

Unlike IgnoreTimestamps, this targets fields by name, so other time.Time fields (e.g. ScheduledAt, BirthDate) are still compared.

Example:

testcmp.Equal(t, want, got, testcmp.IgnoreAuditFields())

func IgnoreIDs

func IgnoreIDs() cmp.Option

IgnoreIDs returns an option that ignores any struct field named exactly "ID" or ending with a lowercase letter followed by "ID", matching the standard Go naming convention (e.g. SupplierID, UserID, AssessmentID).

Fields like VALID or SQUID are not matched because the character before "ID" is uppercase.

If you need to ignore fields that don't follow this convention, use cmpopts.IgnoreFields directly.

Example:

testcmp.Equal(t, want, got, testcmp.IgnoreIDs())

func IgnoreTimestamps

func IgnoreTimestamps() cmp.Option

IgnoreTimestamps returns an option that ignores all time.Time values during comparison. Useful when structs contain CreatedAt, UpdatedAt, or similar fields set by the database.

This ignores time.Time by type, so it applies to all time.Time fields and values, not just those with specific names. Use IgnoreAuditFields if you only want to ignore CreatedAt and UpdatedAt.

Example:

testcmp.Equal(t, want, got, testcmp.IgnoreTimestamps())

func NotEqual

func NotEqual[T any](t TestingT, want, got T, opts ...cmp.Option) bool

NotEqual asserts that want and got are not equal using cmp.Diff.

Example:

testcmp.NotEqual(t, original, updated, testcmp.IgnoreTimestamps())

Types

type TestingT

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

TestingT is the interface accepted by Equal and NotEqual. It is compatible with *testing.T, *testing.B, and testify suite types.