datadiff

README

datadiff

A Go test assertion library for comparing lists of structs with rich tabular diff output.

Install

go get github.com/dashmug/datadiff

Usage

package yourpkg

import (
	"testing"

	"github.com/dashmug/datadiff"
)

type Person struct {
	Name string
	Age  int
	City string
}

func TestPeople(t *testing.T) {
	expected := []Person{
		{Name: "Alice", Age: 30, City: "New York"},
		{Name: "Bob", Age: 25, City: "Boston"},
	}

	actual := []Person{
		{Name: "Alice", Age: 30, City: "New York"},
		{Name: "Bob", Age: 26, City: "Boston"},
	}

	if !datadiff.Assert(t, expected, actual) {
		return
	}
}

When the assertion fails, output is tabular and highlights mismatched rows and columns:

datadiff: []Person are not equal

   #  Name   Age  City
-  -  -      -    -
✓  0  Alice  30   New York
✗  1  Bob    25   Boston  ← expected
      Bob    26   Boston  ← actual

Flags

Assert is strict by default: order and length must match.

IgnoreOrder

Use IgnoreOrder to compare rows regardless of position.

ok := datadiff.Assert(t, expected, actual, datadiff.IgnoreOrder)

IgnoreLengths

Use IgnoreLengths to allow extras while still comparing overlapping rows.

ok := datadiff.Assert(t, expected, actual, datadiff.IgnoreLengths)

You can combine both flags:

ok := datadiff.Assert(t, expected, actual, datadiff.IgnoreOrder, datadiff.IgnoreLengths)

Inspiration

This project is inspired by chispa, a Python DataFrame assertion helper.

License

MIT

Documentation

Overview

Package datadiff provides test assertions for comparing slices of structs, with rich tabular diff output that highlights row and column mismatches.

Inspired by github.com/MrPowers/chispa for Python DataFrames.

Index

• Constants
• func Assert(t *testing.T, listA, listB any, flags ...any) bool
• type Flag

Constants

const Version = "0.1.0-dev"

Version is the current module version.

Functions

func Assert

func Assert(t *testing.T, listA, listB any, flags ...any) bool

Assert compares listA and listB and reports differences through t. Both arguments must be slices of the same struct type.

By default, comparison is strict: rows must appear in the same order and both lists must have equal length. Pass IgnoreOrder and/or IgnoreLengths to relax those constraints.

Assert calls t.Fatalf for programmer errors (invalid flags or invalid inputs) and t.Errorf for data mismatches.

Returns true if the lists are equal under the given flags, false otherwise.

Types

type Flag

type Flag int

Flag controls comparison behavior in Assert.

const (
	// IgnoreOrder compares lists without regard to element position.
	// Rows are matched by finding the closest counterpart in the other list.
	IgnoreOrder Flag = iota + 1

	// IgnoreLengths allows lists of different lengths.
	// Extra rows are reported in the diff output but do not cause the
	// assertion to fail. Without this flag, differing lengths are a failure.
	IgnoreLengths
)