assert

README

Assert

Go testing micro library. This library is small yet opinionated as it aims to be as simple as possible while provide testing utilities for 80% of the cases in order to remove boilerplate from the testing code, improve test expressiveness and standardize test failure messages. All the edge cases (the rest 20%) are not covered and have to be tested the way you would do without this library. Before you decide on using it please read and consider this. On the other hand if you're looking for a fully flagged all in one testing solution, this is not the place, however testify might be it.

Usage example

If you are still here cool! Bare with me and I'll show what this library can bring you :)

Let's assume we have some db method receiver implementing FetchRecord method which in turn accepts id and returns some record along with the error if there is any. Now we'd like to test this behavior. So by using assert library the test would look something like this:

func TestRecordFetching(t *testing.T){
    record, err := db.FetchRecord(123)

    assert.NoError(t.Fatalf, err)
    assert.EqualStrings(t, "Bart", record.FirstName)
    assert.EqualStrings(t, "Simpson", record.LastName)
}

Which is effectively the same as following test by using only inbuilt testing facilities:

func TestRecordFetching(t *testing.T){
    record, err := db.FetchRecord(123)

    if err != nil {
        t.Fatalf("\nEquality assertion failed:\n\twant: no error \n\t got: error '%s'", err)
    }

    expectedName := "Bart"
    if record.FirstName != expectedName {
        t.Errorf("\nEquality assertion failed:\n\twant: '%s' \n\t got: '%s'", expectedName, record.FirstName)
    }

    expectedLastName := "Simpson"
    if record.LastName != expectedLastName {
        t.Errorf("\nEquality assertion failed:\n\twant: '%s' \n\t got: '%s'", expectedLastName, record.LastName)
    }
}

As we can see even in this pretty simple and small test above there are a lot of boilerplate and repetition. And since software developers are extremely lazy people (like I am :D) which in practice brings us to short and ambiguous failure messages in the production test suits (The best I've seen so far t.Error("write something useful here") :))

I hope that assert library will help to reduce boilerplate code and consumption of cognitive energy in making up failure messages while guarantee consistent and descriptive messages across the test suite. So you can focus on the test itself and the logic you want to test.

For more examples please check Docs section below

Installation

$ go get github.com/amekss/assert

(optional) To run unit tests:

$ cd $GOPATH/src/github.com/amekss/assert
$ go test -cover

Docs

Equality

func TestEquality(t *testing.T) {
    // asserts that two values are the same
    assert.EqualStrings(t, expectedStr, "foo")
    assert.EqualErrors(t, expectedErr, errors.New("bar"))
    assert.EqualInt(t, expectedInt, 10)
    assert.EqualFloat32(t, expectedFloat32, float32(2.5))
    assert.EqualFloat64(t, expectedFloat64, float64(2.5))
    assert.EqualTime(t, expectedTime, time.Now())
}

Note: There is no assert.Equal method and no current plans on implementing one. IMHO well written tests serves as live documentation and assert.Equal(t, a, b) doesn't reads as good as for example assert.EqualStrings(t, a, b) since just by looking at it its quite clear that we're testing strings here.

Equality within a tolerance

func TestEqualityTol(t *testing.T) {
    // asserts that two values are the same within a relative tolerance

    // tolerance is expressed in percentage for float comparisons (e.g. 2%)
    assert.EqualFloat32Tol(t, expectedFloat32, float32(101.0), float32(0.02))
    assert.EqualFloat64Tol(t, expectedFloat64, float64(101.0), float64(0.02))

    // tolerance is expressed in time.Duration for time.Time comparisons
    assert.EqualTimeTol(t, expectedTime, time.Now(), time.ParseDuration("1s"))
}

Boolean

func TestBoolean(t *testing.T) {
    // asserts that expression is evaluated to true or false
    assert.True(t, true==true)
    assert.False(t, true!=true)
}

Inclusion

func TestInclusion(t *testing.T) {
    // asserts that first string is a substring of the other (substring of error message in the case of errors)
    assert.IncludesString(t, "fo", "foo")
    assert.ErrorIncludesMessage(t, "foo", err)
}

Nils & Panics

func TestNils(t *testing.T) {
    // asserts that error is not produced
    assert.NoError(t, err)
    // asserts panic is produced
    defer assert.Panic(t, "foo")
    // assert that nil is received
    assert.IsNil(t, nil)
}

Advanced reporters

By default assert will use Errorf() of the *testing.T to report error and that's why tests are not interrupted on the first encountered failures. Which helps to get full picture and list of all failed assertions in the test report, while sometimes it's better to interrupt tests when the failure is encountered. For example when function call under test are returning some value along with error, so one might want to stop further assertions on value if the error is not nil, as it might cause some panics and add some unnecessary noise to the test results. For this very reason you can customize reporter function by passing in the one you need as follows:

func TestSomeBehavior(t *testing.T) {
    // fail fast behavior, stop current test further assertions on failure
    assert.NoError(t.Fatalf, err)
    // default shortcut - Errorf() on t will be called under the hood current test won't be interrupted on failure
    assert.EqualStrings(t, "foo", foo)
    // same as default reporting behavior
    assert.EqualStrings(t.Errorf, "bar", bar)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Documentation

Overview

Package assert - makes sure that 2 things are the same

Package assert - private utility functions to convert stuff to string

Package assert - makes sure that one thing includes other

Package assert utility for formating test failure messages

Package assert private utility functions for error reporting

Index

• func EqualDecimal(reporter interface{}, want, got decimal.Decimal)
• func EqualErrors(reporter interface{}, want, got error)
• func EqualFloat32(reporter interface{}, want, got float32)
• func EqualFloat32Tol(reporter interface{}, want, got, relTol float32)
• func EqualFloat64(reporter interface{}, want, got float64)
• func EqualFloat64Tol(reporter interface{}, want, got, relTol float64)
• func EqualInt(reporter interface{}, want, got int)
• func EqualStrings(reporter interface{}, want, got string)
• func EqualTime(reporter interface{}, want, got time.Time)
• func EqualTimeTol(reporter interface{}, want, got time.Time, relTol time.Duration)
• func ErrorIncludesMessage(reporter interface{}, expectedPhrase string, got error)
• func False(reporter interface{}, expression bool)
• func IncludesString(reporter interface{}, expectedPhrase, got string)
• func IsNil(reporter interface{}, got interface{})
• func NoError(reporter interface{}, got error)
• func Panic(reporter interface{}, withMessage string)
• func True(reporter interface{}, expression bool)

Functions

func EqualDecimal

func EqualDecimal(reporter interface{}, want, got decimal.Decimal)

EqualDecimal - asserts that two decimals are the same

func EqualErrors

func EqualErrors(reporter interface{}, want, got error)

EqualErrors - asserts that specific error was produced

func EqualFloat32

func EqualFloat32(reporter interface{}, want, got float32)

EqualFloat32 - asserts that two floats are the same

func EqualFloat32Tol

func EqualFloat32Tol(reporter interface{}, want, got, relTol float32)

EqualFloat32Tol - asserts that two floats are the same, allowing for (relative) tolerance given as a parameter

func EqualFloat64

func EqualFloat64(reporter interface{}, want, got float64)

EqualFloat64 - asserts that two floats are the same

func EqualFloat64Tol

func EqualFloat64Tol(reporter interface{}, want, got, relTol float64)

EqualFloat64Tol - asserts that two floats are the same, allowing for (relative) tolerance given as a parameter

func EqualInt

func EqualInt(reporter interface{}, want, got int)

EqualInt - asserts that two integers are the same

func EqualStrings

func EqualStrings(reporter interface{}, want, got string)

EqualStrings - asserts that two strings are equal

func EqualTime

func EqualTime(reporter interface{}, want, got time.Time)

EqualTime - asserts that two time.Time are the same

func EqualTimeTol

func EqualTimeTol(reporter interface{}, want, got time.Time, relTol time.Duration)

EqualTimeTol - asserts that two time.Time are the same, allowing for (relative) tolerance given as a parameter

func ErrorIncludesMessage

func ErrorIncludesMessage(reporter interface{}, expectedPhrase string, got error)

ErrorIncludesMessage - asserts that received error includes particular string in the message

func False

func False(reporter interface{}, expression bool)

False - asserts that passed expression is evaluated to false

func IncludesString

func IncludesString(reporter interface{}, expectedPhrase, got string)

IncludesString - asserts that string includes substring

func IsNil

func IsNil(reporter interface{}, got interface{})

IsNil - asserts that provided interface has nil value

func NoError

func NoError(reporter interface{}, got error)

NoError - asserts that no error was produced

func Panic

func Panic(reporter interface{}, withMessage string)

Panic - asserts that code caused panic with specific message

func True

func True(reporter interface{}, expression bool)

True - asserts that passed expression is evaluated to true