assert

package module
v1.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2023 License: MIT Imports: 7 Imported by: 1

README

Package assert - Magic assert macros for Go

Go Go Doc

Package assert provides developer a way to assert expression and output useful contextual information automatically when a case fails. With this package, we can focus on writing test code without worrying about how to print lots of verbose debug information for debug.

Here is a quick sample.

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    str := Foo(42)
    assert.Assert(t, str == "expected")

    // This case fails with following message.
    //
    //     Assertion failed:
    //         str == "expected"
    //     Referenced variables are assigned in following statements:
    //         str := Foo(42)
}

Import

Use go get to install this package.

go get github.com/huandu/go-assert

Current stable version is v1.*. Old versions tagged by v0.* are obsoleted.

Usage

Assertion methods

If we just want to use functions like Assert, Equal or NotEqual, it's recommended to import this package as ..

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    a, b := 1, 2
    assert.Assert(t, a > b)

    // This case fails with message:
    //     Assertion failed:
    //         a > b
}

func TestAssertEquality(t *testing.T) {
    assert.Equal(t, map[string]int{
        "foo": 1,
        "bar": -2,
    }, map[string]int{
        "bar": -2,
        "foo": 10000,
    })

    // This case fails with message:
    //     Assertion failed:
    //     The value of following expression should equal.
    //     [1] map[string]int{
    //             "foo": 1,
    //             "bar": -2,
    //         }
    //     [2] map[string]int{
    //             "bar": -2,
    //             "foo": 10000,
    //         }
    //     Values:
    //     [1] -> (map[string]int)map[bar:-2 foo:1]
    //     [2] -> (map[string]int)map[bar:-2 foo:10000]
}
Advanced assertion wrapper: type A

If we want more controls on assertion, it's recommended to wrap t in an A.

There are lots of useful assert methods implemented in A.

  • Assert/Eqaul/NotEqual: Basic assertion methods.
  • NilError/NonNilError: Test if a func/method returns expected error.
  • Use: Track variables. If any assert method fails, all variables tracked by A and related in assert method will be printed out automatically in assertion message.

Here is a sample to demonstrate how to use A#Use to print related variables in assertion message.

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    a := assert.New(t)
    v1 := 123
    v2 := []string{"wrong", "right"}
    v3 := v2[0]
    v4 := "not related"
    a.Use(&v1, &v2, &v3, &v4)

    a.Assert(v1 == 123 && v3 == "right")

    // This case fails with following message.
    //
    //     Assertion failed:
    //         v1 == 123 && v3 == "right"
    //     Referenced variables are assigned in following statements:
    //         v1 := 123
    //         v3 := v2[0]
    //     Related variables:
    //         v1 -> (int)123
    //         v2 -> ([]string)[wrong right]
    //         v3 -> (string)wrong
}

Documentation

Overview

Package assert provides developer a way to assert expression and output useful contextual information automatically when a case fails. With this package, we can focus on writing test code without worrying about how to print lots of verbose debug information for debug.

See project page for more samples. https://github.com/huandu/go-assert

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Assert 

func Assert(t *testing.T, expr interface{})

Assert tests expr and call `t.Fatalf` to terminate test case if expr is false-equivalent value. `false`, 0, nil and empty string are false-equivalent values.

Sample code. 

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    a, b := 1, 2
    assert.Assert(t, a > b)
}

Output: 

Assertion failed:
    a > b
Referenced variables are assigned in following statements:
    a, b := 1, 2

func AssertEqual 

func AssertEqual(t *testing.T, v1, v2 interface{})

AssertEqual uses `reflect.DeepEqual` to test v1 and v2 equality.

Note: as golint dislike the name of this function, it will be removed in the future. Use Equal instead.

Sample code. 

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    assert.AssertEqual(t, []int{1,2}, []int{1})
}

Output: 

Assertion failed:
    assert.AssertEqual(t, []int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]

func AssertNotEqual 

func AssertNotEqual(t *testing.T, v1, v2 interface{})

AssertNotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.

Note: as golint dislike the name of this function, it will be removed in the future. Use NotEqual instead.

Sample code. 

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    assert.AssertNotEqual(t, []int{1}, []int{1})
}

Output: 

Assertion failed:
    assert.AssertNotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}

func Equal added in v1.1.5 

func Equal(t *testing.T, v1, v2 interface{})

Equal uses `reflect.DeepEqual` to test v1 and v2 equality.

Sample code. 

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    assert.Equal(t, []int{1,2}, []int{1})
}

Output: 

Assertion failed:
    assert.Equal(t, []int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]

func NotEqual added in v1.1.5 

func NotEqual(t *testing.T, v1, v2 interface{})

NotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.

Sample code. 

import "github.com/huandu/go-assert"

func TestSomething(t *testing.T) {
    assert.NotEqual(t, []int{1}, []int{1})
}

Output: 

Assertion failed:
    assert.NotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}

Types

type A added in v1.0.0 

type A struct {
	*testing.T
	// contains filtered or unexported fields
}

The A is a wrapper of testing.T with some extra help methods.

func New added in v1.0.0 

func New(t *testing.T) *A

New creates an assertion object wraps t.

func (*A) Assert added in v1.0.0 

func (a *A) Assert(expr interface{})

Assert tests expr and call `t.Fatalf` to terminate test case if expr is false-equivalent value. `false`, 0, nil and empty string are false-equivalent values.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    x, y := 1, 2
    a.Assert(x > y)
}

Output: 

Assertion failed:
    x > y
Referenced variables are assigned in following statements:
    x, y := 1, 2

func (*A) Equal added in v1.0.0 

func (a *A) Equal(v1, v2 interface{})

Equal uses `reflect.DeepEqual` to test v1 and v2 equality.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    a.Equal([]int{1,2}, []int{1})
}

Output: 

Assertion failed:
    a.Equal([]int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]

func (*A) NilError added in v1.0.0 

func (a *A) NilError(result ...interface{})

NilError expects a function return a nil error. Otherwise, it will terminate the test case using `t.Fatalf`.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    a.NilError(os.Open("path/to/a/file"))
}

Output: 

Assertion failed:
Following expression should return a nil error.
    os.Open("path/to/a/file")
The error is:
    open path/to/a/file: no such file or directory

func (*A) NonNilError added in v1.0.0 

func (a *A) NonNilError(result ...interface{})

NonNilError expects a function return a non-nil error. Otherwise, it will terminate the test case using `t.Fatalf`.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    f := func() (int, error) { return 0, errors.New("expected") }
    a.NilError(f())
}

Output: 

Assertion failed:
Following expression should return a nil error.
    f()
    f := func() (int, error) { return 0, errors.New("expected") }
The error is:
    expected

func (*A) NotEqual added in v1.0.0 

func (a *A) NotEqual(v1, v2 interface{})

NotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    a.NotEqual(t, []int{1}, []int{1})
}

Output: 

Assertion failed:
    a.NotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}

func (*A) Use added in v1.1.0 

func (a *A) Use(args ...interface{})

Use saves args in context and prints related args automatically in assertion method when referenced.

Sample code. 

func TestSomething(t *testing.T) {
    a := assert.New(t)
    v1 := 123
    v2 := []string{"wrong", "right"}
    v3 := v2[0]
    v4 := "not related"
    a.Use(&v1, &v2, &v3, &v4)
}

Output: 

Assertion failed:
    v1 == 123 && v3 == "right"
Referenced variables are assigned in following statements:
    v1 := 123
    v3 := v2[0]
Related variables:
    v1 = (int)123
    v3 = (string)wrong

Source Files

View all Source files

Directories

Path Synopsis
internal
assertion
Package assertion is the implementation detail of package assert.
 Package assertion is the implementation detail of package assert.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.