testdeep

README

go-testdeep

Extremely flexible golang deep comparison, extends the go testing package.

Currently supports go 1.16 → 1.21.

• Latest news
• Synopsis
• Description
• Installation
• Functions
• Available operators
• Helpers
  • tdhttp or HTTP API testing helper
  • tdsuite or testing suite helper
  • tdutil aka the helper of helpers
• See also
• License
• FAQ

Latest news

• 2023/03/18: v1.13.0 release;
• 2022/08/07: v1.12.0 release;
• 2022/01/05: v1.11.0 release;
• see commits history for other/older changes.

Synopsis

Make golang tests easy, from simplest usage:

import (
  "testing"

  "github.com/maxatome/go-testdeep/td"
)

func TestMyFunc(t *testing.T) {
  td.Cmp(t, MyFunc(), &Info{Name: "Alice", Age: 42})
}

To a bit more complex one, allowing flexible comparisons using TestDeep operators:

import (
  "testing"

  "github.com/maxatome/go-testdeep/td"
)

func TestMyFunc(t *testing.T) {
  td.Cmp(t, MyFunc(), td.Struct(
    &Info{Name: "Alice"},
    td.StructFields{
      "Age": td.Between(40, 45),
    },
  ))
}

Or anchoring operators directly in literals, as in:

import (
  "testing"

  "github.com/maxatome/go-testdeep/td"
)

func TestMyFunc(tt *testing.T) {
  t := td.NewT(tt)

  t.Cmp(MyFunc(), &Info{
    Name: "Alice",
    Age:  t.Anchor(td.Between(40, 45)).(int),
  })
}

To most complex one, allowing to easily test HTTP API routes, using flexible operators:

import (
  "testing"
  "time"

  "github.com/maxatome/go-testdeep/helpers/tdhttp"
  "github.com/maxatome/go-testdeep/td"
)

type Person struct {
  ID        uint64    `json:"id"`
  Name      string    `json:"name"`
  Age       int       `json:"age"`
  CreatedAt time.Time `json:"created_at"`
}

func TestMyApi(t *testing.T) {
  var id uint64
  var createdAt time.Time

  testAPI := tdhttp.NewTestAPI(t, myAPI) // ← ①

  testAPI.PostJSON("/person", Person{Name: "Bob", Age: 42}). // ← ②
    Name("Create a new Person").
    CmpStatus(http.StatusCreated). // ← ③
    CmpJSONBody(td.JSON(`
// Note that comments are allowed
{
  "id":         $id,             // set by the API/DB
  "name":       "Alice",
  "age":        Between(40, 45), // ← ④
  "created_at": "$createdAt",    // set by the API/DB
}`,
      td.Tag("id", td.Catch(&id, td.NotZero())),        // ← ⑤
      td.Tag("createdAt", td.All(                       // ← ⑥
        td.HasSuffix("Z"),                              // ← ⑦
        td.Smuggle(func(s string) (time.Time, error) {  // ← ⑧
          return time.Parse(time.RFC3339Nano, s)
        }, td.Catch(&createdAt, td.Between(testAPI.SentAt(), time.Now()))), // ← ⑨
      )),
    ))
  if !testAPI.Failed() {
    t.Logf("The new Person ID is %d and was created at %s", id, createdAt)
  }
}

1. the API handler ready to be tested;
2. the POST request with automatic JSON marshalling;
3. the expected response HTTP status should be http.StatusCreated and the line just below, the body should match the JSON operator;
4. some operators can be embedded, like Between here;
5. for the $id placeholder, Catch its value: put it in id variable and check it is NotZero;
6. for the $createdAt placeholder, use the All operator. It combines several operators like a AND;
7. check that $createdAt date ends with "Z" using HasSuffix. As we expect a RFC3339 date, we require it in UTC time zone;
8. convert $createdAt date into a time.Time using a custom function thanks to the Smuggle operator;
9. then Catch the resulting value: put it in createdAt variable and check it is greater or equal than testAPI.SentAt() (the time just before the request is handled) and lesser or equal than time.Now().

See tdhttp helper or the FAQ for details about HTTP API testing.

Example of produced error in case of mismatch:

Description

go-testdeep is historically a go rewrite and adaptation of wonderful Test::Deep perl.

In golang, comparing data structure is usually done using reflect.DeepEqual or using a package that uses this function behind the scene.

This function works very well, but it is not flexible. Both compared structures must match exactly and when a difference is returned, it is up to the caller to display it. Not easy when comparing big data structures.

The purpose of go-testdeep, via the td package and its helpers, is to do its best to introduce this missing flexibility using "operators", when the expected value (or one of its component) cannot be matched exactly, mixed with some useful comparison functions.

See go-testdeep.zetta.rocks for details.

Installation

$ go get github.com/maxatome/go-testdeep

Helpers

The goal of helpers is to make use of go-testdeep even more powerful by providing common features using TestDeep operators behind the scene.

tdhttp or HTTP API testing helper

The package github.com/maxatome/go-testdeep/helpers/tdhttp provides some functions to easily test HTTP handlers.

See tdhttp documentation for details or FAQ for an example of use.

tdsuite or testing suite helper

The package github.com/maxatome/go-testdeep/helpers/tdsuite adds tests suite feature to go-testdeep in a non-intrusive way, but easily and powerfully.

A tests suite is a set of tests run sequentially that share some data.

Some hooks can be set to be automatically called before the suite is run, before, after and/or between each test, and at the end of the suite.

See tdsuite documentation for details.

tdutil aka the helper of helpers

The package github.com/maxatome/go-testdeep/helpers/tdutil allows to write unit tests for go-testdeep helpers and so provides some helpful functions.

See tdutil for details.

See also

• testify: a toolkit with common assertions and mocks that plays nicely with the standard library
• go-cmp: package for comparing Go values in tests

License

go-testdeep is released under the BSD-style license found in the LICENSE file in the root directory of this source tree.

Internal function deepValueEqual is based on deepValueEqual from reflect golang package licensed under the BSD-style license found in the LICENSE file in the golang repository.

Uses two files (bypass.go & bypasssafe.go) from Go-spew which is licensed under the copyfree ISC License.

Public Domain Gopher provided by Egon Elbre. The Go gopher was designed by Renee French.

FAQ

See FAQ.

Documentation

Overview

Package testdeep allows extremely flexible deep comparison. It is built for testing.

It is a go rewrite and adaptation of wonderful Test::Deep perl module.

In golang, comparing data structure is usually done using reflect.DeepEqual or using a package that uses this function behind the scene.

This function works very well, but it is not flexible. Both compared structures must match exactly.

The purpose of go-testdeep is to do its best to introduce this missing flexibility using "operators" when the expected value (or one of its component) cannot be matched exactly.

testdeep package should not be used in new code, even if it can for backward compatibility reasons, but td package.

All variables and types of testdeep package are aliases to respectively functions and types of td package. They are only here for compatibility purpose as

import "github.com/maxatome/go-testdeep/td"

should now be used, in preference of older, but still supported:

import td "github.com/maxatome/go-testdeep"

For easy HTTP API testing, see tdhttp package.

For tests suites also just as easy, see tdsuite package.

Index

• Constants
• Variables
• type ArrayEntries
• type BoundsKind
• type ContextConfig
• type MapEntries
• type SmuggledGot
• type StructFields
• type T
• type TestDeep
• type TestingFT
• type TestingT

Constants

const BoundsInIn = td.BoundsInIn

BoundsInIn is a deprecated alias of td.BoundsInIn.

const BoundsInOut = td.BoundsInOut

BoundsInOut is a deprecated alias of td.BoundsInOut.

const BoundsOutIn = td.BoundsOutIn

BoundsOutIn is a deprecated alias of td.BoundsOutIn.

const BoundsOutOut = td.BoundsOutOut

BoundsOutOut is a deprecated alias of td.BoundsOutOut.

Variables

var AddAnchorableStructType = td.AddAnchorableStructType

AddAnchorableStructType is a deprecated alias of td.AddAnchorableStructType.

var All = td.All

All is a deprecated alias of td.All.

var Any = td.Any

Any is a deprecated alias of td.Any.

var Array = td.Array

Array is a deprecated alias of td.Array.

var ArrayEach = td.ArrayEach

ArrayEach is a deprecated alias of td.ArrayEach.

var Assert = td.Assert

Assert is a deprecated alias of td.Assert.

var AssertRequire = td.AssertRequire

AssertRequire is a deprecated alias of td.AssertRequire.

var Bag = td.Bag

Bag is a deprecated alias of td.Bag.

var Between = td.Between

Between is a deprecated alias of td.Between.

var Cap = td.Cap

Cap is a deprecated alias of td.Cap.

var Catch = td.Catch

Catch is a deprecated alias of td.Catch.

var Cmp = td.Cmp

Cmp is a deprecated alias of td.Cmp.

var CmpAll = td.CmpAll

CmpAll is a deprecated alias of td.CmpAll.

var CmpAny = td.CmpAny

CmpAny is a deprecated alias of td.CmpAny.

var CmpArray = td.CmpArray

CmpArray is a deprecated alias of td.CmpArray.

var CmpArrayEach = td.CmpArrayEach

CmpArrayEach is a deprecated alias of td.CmpArrayEach.

var CmpBag = td.CmpBag

CmpBag is a deprecated alias of td.CmpBag.

var CmpBetween = td.CmpBetween

CmpBetween is a deprecated alias of td.CmpBetween.

var CmpCap = td.CmpCap

CmpCap is a deprecated alias of td.CmpCap.

var CmpCode = td.CmpCode

CmpCode is a deprecated alias of td.CmpCode.

var CmpContains = td.CmpContains

CmpContains is a deprecated alias of td.CmpContains.

var CmpContainsKey = td.CmpContainsKey

CmpContainsKey is a deprecated alias of td.CmpContainsKey.

var CmpDeeply = td.CmpDeeply

CmpDeeply is a deprecated alias of td.CmpDeeply.

var CmpEmpty = td.CmpEmpty

CmpEmpty is a deprecated alias of td.CmpEmpty.

var CmpError = td.CmpError

CmpError is a deprecated alias of td.CmpError.

var CmpFalse = td.CmpFalse

CmpFalse is a deprecated alias of td.CmpFalse.

var CmpGt = td.CmpGt

CmpGt is a deprecated alias of td.CmpGt.

var CmpGte = td.CmpGte

CmpGte is a deprecated alias of td.CmpGte.

var CmpHasPrefix = td.CmpHasPrefix

CmpHasPrefix is a deprecated alias of td.CmpHasPrefix.

var CmpHasSuffix = td.CmpHasSuffix

CmpHasSuffix is a deprecated alias of td.CmpHasSuffix.

var CmpIsa = td.CmpIsa

CmpIsa is a deprecated alias of td.CmpIsa.

var CmpJSON = td.CmpJSON

CmpJSON is a deprecated alias of td.CmpJSON.

var CmpKeys = td.CmpKeys

CmpKeys is a deprecated alias of td.CmpKeys.

var CmpLax = td.CmpLax

CmpLax is a deprecated alias of td.CmpLax.

var CmpLen = td.CmpLen

CmpLen is a deprecated alias of td.CmpLen.

var CmpLt = td.CmpLt

CmpLt is a deprecated alias of td.CmpLt.

var CmpLte = td.CmpLte

CmpLte is a deprecated alias of td.CmpLte.

var CmpMap = td.CmpMap

CmpMap is a deprecated alias of td.CmpMap.

var CmpMapEach = td.CmpMapEach

CmpMapEach is a deprecated alias of td.CmpMapEach.

var CmpN = td.CmpN

CmpN is a deprecated alias of td.CmpN.

var CmpNaN = td.CmpNaN

CmpNaN is a deprecated alias of td.CmpNaN.

var CmpNil = td.CmpNil

CmpNil is a deprecated alias of td.CmpNil.

var CmpNoError = td.CmpNoError

CmpNoError is a deprecated alias of td.CmpNoError.

var CmpNone = td.CmpNone

CmpNone is a deprecated alias of td.CmpNone.

var CmpNot = td.CmpNot

CmpNot is a deprecated alias of td.CmpNot.

var CmpNotAny = td.CmpNotAny

CmpNotAny is a deprecated alias of td.CmpNotAny.

var CmpNotEmpty = td.CmpNotEmpty

CmpNotEmpty is a deprecated alias of td.CmpNotEmpty.

var CmpNotNaN = td.CmpNotNaN

CmpNotNaN is a deprecated alias of td.CmpNotNaN.

var CmpNotNil = td.CmpNotNil

CmpNotNil is a deprecated alias of td.CmpNotNil.

var CmpNotPanic = td.CmpNotPanic

CmpNotPanic is a deprecated alias of td.CmpNotPanic.

var CmpNotZero = td.CmpNotZero

CmpNotZero is a deprecated alias of td.CmpNotZero.

var CmpPPtr = td.CmpPPtr

CmpPPtr is a deprecated alias of td.CmpPPtr.

var CmpPanic = td.CmpPanic

CmpPanic is a deprecated alias of td.CmpPanic.

var CmpPtr = td.CmpPtr

CmpPtr is a deprecated alias of td.CmpPtr.

var CmpRe = td.CmpRe

CmpRe is a deprecated alias of td.CmpRe.

var CmpReAll = td.CmpReAll

CmpReAll is a deprecated alias of td.CmpReAll.

var CmpSStruct = td.CmpSStruct

CmpSStruct is a deprecated alias of td.CmpSStruct.

var CmpSet = td.CmpSet

CmpSet is a deprecated alias of td.CmpSet.

var CmpShallow = td.CmpShallow

CmpShallow is a deprecated alias of td.CmpShallow.

var CmpSlice = td.CmpSlice

CmpSlice is a deprecated alias of td.CmpSlice.

var CmpSmuggle = td.CmpSmuggle

CmpSmuggle is a deprecated alias of td.CmpSmuggle.

var CmpString = td.CmpString

CmpString is a deprecated alias of td.CmpString.

var CmpStruct = td.CmpStruct

CmpStruct is a deprecated alias of td.CmpStruct.

var CmpSubBagOf = td.CmpSubBagOf

CmpSubBagOf is a deprecated alias of td.CmpSubBagOf.

var CmpSubJSONOf = td.CmpSubJSONOf

CmpSubJSONOf is a deprecated alias of td.CmpSubJSONOf.

var CmpSubMapOf = td.CmpSubMapOf

CmpSubMapOf is a deprecated alias of td.CmpSubMapOf.

var CmpSubSetOf = td.CmpSubSetOf

CmpSubSetOf is a deprecated alias of td.CmpSubSetOf.

var CmpSuperBagOf = td.CmpSuperBagOf

CmpSuperBagOf is a deprecated alias of td.CmpSuperBagOf.

var CmpSuperJSONOf = td.CmpSuperJSONOf

CmpSuperJSONOf is a deprecated alias of td.CmpSuperJSONOf.

var CmpSuperMapOf = td.CmpSuperMapOf

CmpSuperMapOf is a deprecated alias of td.CmpSuperMapOf.

var CmpSuperSetOf = td.CmpSuperSetOf

CmpSuperSetOf is a deprecated alias of td.CmpSuperSetOf.

var CmpTrue = td.CmpTrue

CmpTrue is a deprecated alias of td.CmpTrue.

var CmpTruncTime = td.CmpTruncTime

CmpTruncTime is a deprecated alias of td.CmpTruncTime.

var CmpValues = td.CmpValues

CmpValues is a deprecated alias of td.CmpValues.

var CmpZero = td.CmpZero

CmpZero is a deprecated alias of td.CmpZero.

var Code = td.Code

Code is a deprecated alias of td.Code.

var Contains = td.Contains

Contains is a deprecated alias of td.Contains.

var ContainsKey = td.ContainsKey

ContainsKey is a deprecated alias of td.ContainsKey.

var Delay = td.Delay

Delay is a deprecated alias of td.ContainsKey.

var Empty = td.Empty

Empty is a deprecated alias of td.Empty.

var EqDeeply = td.EqDeeply

EqDeeply is a deprecated alias of td.EqDeeply.

var EqDeeplyError = td.EqDeeplyError

EqDeeplyError is a deprecated alias of td.EqDeeplyError.

var Gt = td.Gt

Gt is a deprecated alias of td.Gt.

var Gte = td.Gte

Gte is a deprecated alias of td.Gte.

var HasPrefix = td.HasPrefix

HasPrefix is a deprecated alias of td.HasPrefix.

var HasSuffix = td.HasSuffix

HasSuffix is a deprecated alias of td.HasSuffix.

var Ignore = td.Ignore

Ignore is a deprecated alias of td.Ignore.

var Isa = td.Isa

Isa is a deprecated alias of td.Isa.

var JSON = td.JSON

JSON is a deprecated alias of td.JSON.

var Keys = td.Keys

Keys is a deprecated alias of td.Keys.

var Lax = td.Lax

Lax is a deprecated alias of td.Lax.

var Len = td.Len

Len is a deprecated alias of td.Len.

var Lt = td.Lt

Lt is a deprecated alias of td.Lt.

var Lte = td.Lte

Lte is a deprecated alias of td.Lte.

var Map = td.Map

Map is a deprecated alias of td.Map.

var MapEach = td.MapEach

MapEach is a deprecated alias of td.MapEach.

var N = td.N

N is a deprecated alias of td.N.

var NaN = td.NaN

NaN is a deprecated alias of td.NaN.

var NewT = td.NewT

NewT is a deprecated alias of td.NewT.

var Nil = td.Nil

Nil is a deprecated alias of td.Nil.

var None = td.None

None is a deprecated alias of td.None.

var Not = td.Not

Not is a deprecated alias of td.Not.

var NotAny = td.NotAny

NotAny is a deprecated alias of td.NotAny.

var NotEmpty = td.NotEmpty

NotEmpty is a deprecated alias of td.NotEmpty.

var NotNaN = td.NotNaN

NotNaN is a deprecated alias of td.NotNaN.

var NotNil = td.NotNil

NotNil is a deprecated alias of td.NotNil.

var NotZero = td.NotZero

NotZero is a deprecated alias of td.NotZero.

var PPtr = td.PPtr

PPtr is a deprecated alias of td.PPtr.

var Ptr = td.Ptr

Ptr is a deprecated alias of td.Ptr.

var Re = td.Re

Re is a deprecated alias of td.Re.

var ReAll = td.ReAll

ReAll is a deprecated alias of td.ReAll.

var Require = td.Require

Require is a deprecated alias of td.Require.

var SStruct = td.SStruct

SStruct is a deprecated alias of td.SStruct.

var Set = td.Set

Set is a deprecated alias of td.Set.

var Shallow = td.Shallow

Shallow is a deprecated alias of td.Shallow.

var Slice = td.Slice

Slice is a deprecated alias of td.Slice.

var Smuggle = td.Smuggle

Smuggle is a deprecated alias of td.Smuggle.

var String = td.String

String is a deprecated alias of td.String.

var Struct = td.Struct

Struct is a deprecated alias of td.Struct.

var SubBagOf = td.SubBagOf

SubBagOf is a deprecated alias of td.SubBagOf.

var SubJSONOf = td.SubJSONOf

SubJSONOf is a deprecated alias of td.SubJSONOf.

var SubMapOf = td.SubMapOf

SubMapOf is a deprecated alias of td.SubMapOf.

var SubSetOf = td.SubSetOf

SubSetOf is a deprecated alias of td.SubSetOf.

var SuperBagOf = td.SuperBagOf

SuperBagOf is a deprecated alias of td.SuperBagOf.

var SuperJSONOf = td.SuperJSONOf

SuperJSONOf is a deprecated alias of td.SuperJSONOf.

var SuperMapOf = td.SuperMapOf

SuperMapOf is a deprecated alias of td.SuperMapOf.

var SuperSetOf = td.SuperSetOf

SuperSetOf is a deprecated alias of td.SuperSetOf.

var Tag = td.Tag

Tag is a deprecated alias of td.Tag.

var TruncTime = td.TruncTime

TruncTime is a deprecated alias of td.TruncTime.

var Values = td.Values

Values is a deprecated alias of td.Values.

var Zero = td.Zero

Zero is a deprecated alias of td.Zero.

Types

type ArrayEntries

type ArrayEntries = td.ArrayEntries

ArrayEntries is a deprecated alias of td.ArrayEntries.

type BoundsKind

type BoundsKind = td.BoundsKind

BoundsKind is a deprecated alias of td.BoundsKind.

type ContextConfig

type ContextConfig = td.ContextConfig

ContextConfig is a deprecated alias of td.ContextConfig.

type MapEntries

type MapEntries = td.MapEntries

MapEntries is a deprecated alias of td.MapEntries.

type SmuggledGot

type SmuggledGot = td.SmuggledGot

SmuggledGot is a deprecated alias of td.SmuggledGot.

type StructFields

type StructFields = td.StructFields

StructFields is a deprecated alias of td.StructFields.

type T

type T = td.T

T is a deprecated alias of td.T.

type TestDeep

type TestDeep = td.TestDeep

TestDeep is a deprecated alias of td.TestDeep.

type TestingFT

type TestingFT = td.TestingFT

TestingFT is a deprecated alias of td.TestingFT, which is itself a deprecated alias of testing.TB.

type TestingT

type TestingT = td.TestingT

TestingT is a deprecated alias of td.TestingT.