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
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - 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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EqualDecimal ¶
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 EqualTimeTol ¶
EqualTimeTol - asserts that two time.Time are the same, allowing for (relative) tolerance given as a parameter
func ErrorIncludesMessage ¶
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
Types ¶
This section is empty.
Source Files