gotest

Overview ¶

Package gotest provides rich assertions for use within and beyond Go's `testing` package.

Quickstart ¶

Grab the package and import it:

go get github.com/kindrid/gotest
import "github.com/kindrid/gotest"
import "github.com/kindrid/gotest/should"

Code normal `testing`-style tests, but use `gotest.Assert` and assertions found in `should` like this:

gotest.Assert(t, actualJson, should.HaveFields,
  "name", reflect.String,
  "children", reflect.Map,
  "hobbies", reflect.Slice)

Assertions are just functions that accept interfaces and return a non-empty string if there's an error. Look at `gotest.should.Assertion` for the details. Look at `should/doc.go` and `should/assertion.go` ofr more details.

Gotest adds some command-line options to your tests. You can see them via `go test . -args -help`. Note that gotest has its own verbosity flag which controls different aspects than `-test.v`.

Overview ¶

GoTest plays well with "vernacular" Go `testing` tests, providing a rich set of assertions to test HTTP Responses, JSON and JSON:API data, general equality, numeric comparison, collections, strings, panics, types, and time.

Most of these rich assertions are provided by SmartyStreet's excellent assertion library (https://github.com/smartystreets/assertions) which builds off Aaron Jacobs' Oglematchers (https://github.com/jacobsa/oglematchers).

In addition, any SmartyTreets-style assertion can be used as is (see https://github.com/smartystreets/goconvey/wiki/Custom-Assertions).

Why ¶

We like Go's stdlib `testing` because it's simple, fast, familiar to most Go coders, has good tooling support, benchmark support, and coverage support.

In earlier versions of Go, we missed subtests for test organization and a more BDD approach. We looked at GinkGo (`github.com/onsi/ginkgo`) and GoConvey (github.com/smartystreets/goconvey/convey)--both with benefits--and chose GoConvey because of the simple and consistent approach it took to writing custom assertions. See the documenataion for "gotest/should" for more details on that. It also had a pretty test runner.

But around the release of Go 1.7 we ran into some problems: the growth of parameterized (table-driven) tests in our code didn't play well with GoConvey. GoConvey's approach to building test suites made it hard to focus specific subtests.

We also ran into an opportunity: `testing` now supported subtests. See https://godoc.org/testing#hdr-Subtests_and_Sub_benchmarks. We were able to drop a lot of fancy suite construction code and gain easier focussing on particular tests. But we had come to appreciate GoConvey's excellent assertion pattern. We considered moving to `github.com/stretchr/testify` and used it's pattern for the custom assertion wrapper (see `Assert` below). It also had a simple custom-assertion pattern, but GoConvey's seemed simpler and more useful. We took a sideways glance at GUnit (`github.com/smartystreets/gunit`) and Labix's GoCheck (`gopkg.in/check.v1 `). Very cool packages, but we wanted to stay closer to `testing` with its new versatility.