gocheck

Introduction

The Go language provides an internal testing library, named testing, which is relatively slim due to the fact that the standard library correctness by itself is verified using it. The gocheck package, on the other hand, expects the standard library from Go to be working correctly, and builds on it to offer a richer testing framework for libraries and applications to use.

gocheck includes features such as:

Helpful error reporting to aid on figuring problems out (see below)
Richer test helpers: assertions which interrupt the test immediately, deep multi-type comparisons, string matching, etc
Suite-based grouping of tests
Fixtures: per suite and/or per test set up and tear down
Management of temporary directories
Panic-catching logic, with proper error reporting
Proper counting of successes, failures, panics, missed tests, skips, etc
Explicit test skipping
Support for expected failures
Verbosity flag which disables output caching (helpful to debug hanging tests, for instance)
Fully tested (yes, it manages to test itself reliably! :-)

The following features will be available in future releases:

Optional parallel test execution
Benchmark support

Compatibility with gotest

gocheck works as an extension to the testing package and to the gotest runner. That means you can keep all the tests you currently have, and start using gocheck-based tests right away with no conflicts. The gocheck API was purposefully made similar to the testing module one to ease the migration as well.

Installing and updating

To start using gocheck right away, just run the following command:


go get launchpad.net/gocheck

To ensure you're using the latest version, run the following command instead:


go get -u launchpad.net/gocheck

If you get an error such as "bzr: no such file or directory", ensure you have the Bazaar DVCS installed (e.g. "sudo apt-get install bzr" in Ubuntu, or "sudo port install bzr" with MacPorts).

API documentation

Check it out online at:

http://goneat.org/lp/gocheck

Basic example

Here is a simple example of how to use gocheck.


package hello_test

import (
    . "launchpad.net/gocheck"
    "testing"
    "os"
)

// Hook up gocheck into the gotest runner.
func Test(t *testing.T) { TestingT(t) }


type S struct{}
var _ = Suite(&S{})

func (s *S) TestHelloWorld(c *C) {
    c.Check(42, Equals, "42")
    c.Check(os.Errno(13), Matches, "perm.*accepted")
}

See Assertions and checks below for more information on these tests.

Using fixtures

To use fixtures, simply add one or more of the following methods to the test suite:

func (s *SuiteType) SetUpSuite(c *C) - Run once when the suite starts running.
func (s *SuiteType) TearDownSuite(c *C) - Run once after all tests have finished running.
func (s *SuiteType) SetUpTest(c *C) - Run before each test starts running.
func (s *SuiteType) TearDownTest(c *C) - Run after each test runs.

Here is an example preparing some data in a temporary directory before each test runs:


type S struct{
    dir string
}

func (s *S) SetUpTest(c *C) {
    s.dir = c.MkDir()
    // Use s.dir to prepare some data.
}

func (s *S) TestWithDir(c *C) {
    // Use the data in s.dir in the test.
}

Skipping tests

Many times it's useful to skip one or multiple tests explicitly depending on factors such as the architecture being run or the availability of resources (network, etc). gocheck enables skipping individual tests using the Skip method inside the test itself, and skipping multiple tests by using Skip within SetUpSuite or SetUpTest.

As an example, here is a test suite which will skip all the tests within the suite unless the -integ option is provided to gotest.


var integration = flag.Bool("integ", false, "Include integration tests")

type Integration struct{}

func (s *Integration) SetUpSuite(c *C) {
    if *integration {
        c.Skip("-integ not provided")
    }
}

Running tests and output sample

To run the tests, simply use the ''gotest'' tool as usual:


$ gotest
rm -f _test/hello.a _gotest_.6
cd _test/ofiles && 6g -o ../../_gotest_.6 hello.go  
rm -f _test/hello.a
gopack grc _test/hello.a _gotest_.6 

----------------------------------------------------------------------
FAIL: hello_test.go:16: S.TestHelloWorld

hello_test.go:17:
    c.Check(42, Equals, "42")
... obtained int = 42
... expected string = "42"

hello_test.go:18:
    c.Check(os.Errno(13), Matches, "perm.*accepted")
... value os.Errno = 13 ("permission denied")
... regex string = "perm.*accepted"

OOPS: 0 passed, 1 FAILED
--- FAIL: hello_test.Test
FAIL

Assertions and checks

gocheck uses two methods of *C to verify expectations on values obtained in test cases: Assert and Check. Both of these methods accept the same arguments, and the only difference between them is that when Assert fails, the test is interrupted immediately, while Check will fail the test, return false, and allow it to continue.

Assert and Check have the following types:


func (c *C) Assert(obtained interface{}, checker Checker, ...args interface{})
func (c *C) Check(obtained interface{}, checker Checker, ...args interface{}) bool

Here are some usage examples:


func (s *S) TestSimpleChecks(c *C) {
    c.Assert(value, Equals, 42)
    c.Assert(s, Matches, "hel.*there")
    c.Assert(err, IsNil)
    c.Assert(foo, Equals, bar, Bug("Issue #3245 is happening again."))
}

This last statement will display the provided message next to the usual debugging information in case of failures.

By implementing the Checker interface, you can provide your own custom verifications. There are several standard checkers available. Please check the documentation for details and examples:

http://goneat.org/lp/gocheck#Checker

Selecting which tests to run

gocheck can filter tests out based on the test name or the suite name, or even both. To run tests selectively, simply pass the command line option ''-f'' when running ''gotest''. Note that this option is specific to ''Gocheck'', and won't affect ''gotest'' itself.

Some examples:


$ go test -gocheck.f MyTestSuite
$ go test -gocheck.f "Test.*Works"
$ go test -gocheck.f "MyTestSuite.Test.*Works"

Verbose modes

gocheck offers two levels of verbosity modes through the -gocheck.v and -gocheck.vv flags. In the first mode, passing tests will also be reported. The second mode, though, will disable log caching entirely and will stream starting and ending suite calls and everything logged in between straight to the output. This is useful to debug hanging tests, for instance.

The -gocheck.v and -gocheck.vv flags were introduced in release r2010.12.26

License

gocheck is made available under the Simplified BSD License.