README

GoDoc

ogletest is a unit testing framework for Go with the following features:

  • An extensive and extensible set of matchers for expressing expectations.
  • Automatic failure messages; no need to say t.Errorf("Expected %v, got %v"...).
  • Clean, readable output that tells you exactly what you need to know.
  • Built-in support for mocking through the oglemock package.
  • Style and semantics similar to Google Test and Google JS Test.

It integrates with Go's built-in testing package, so it works with the go test command, and even with other types of test within your package. Unlike the testing package which offers only basic capabilities for signalling failures, it offers ways to express expectations and get nice failure messages automatically.

Installation

First, make sure you have installed Go 1.0.2 or newer. See here for instructions.

Use the following command to install ogletest and its dependencies, and to keep them up to date:

go get -u github.com/jacobsa/ogletest

Documentation

See here for package documentation containing an exhaustive list of exported symbols. Alternatively, you can install the package and then use godoc:

godoc github.com/jacobsa/ogletest

An important part of ogletest is its use of matchers provided by the oglematchers package. See that package's documentation for information on the built-in matchers available, and check out the oglematchers.Matcher interface if you want to define your own.

Example

Let's say you have a function in your package people with the following signature:

// GetRandomPerson returns the name and phone number of Tony, Dennis, or Scott.
func GetRandomPerson() (name, phone string) {
  [...]
}

A silly function, but it will do for an example. You can write a couple of tests for it as follows:

package people

import (
  "github.com/jacobsa/oglematchers"
  "github.com/jacobsa/ogletest"
  "testing"
)

// Give ogletest a chance to run your tests when invoked by 'go test'.
func TestOgletest(t *testing.T) { ogletest.RunTests(t) }

// Create a test suite, which groups together logically related test methods
// (defined below). You can share common setup and teardown code here; see the
// package docs for more info.
type PeopleTest struct {}
func init() { ogletest.RegisterTestSuite(&PeopleTest{}) }

func (t *PeopleTest) ReturnsCorrectNames() {
  // Call the function a few times, and make sure it never strays from the set
  // of expected names.
  for i := 0; i < 25; i++ {
    name, _ := GetRandomPerson()
    ogletest.ExpectThat(name, oglematchers.AnyOf("Tony", "Dennis", "Scott"))
  }
}

func (t *PeopleTest) FormatsPhoneNumbersCorrectly() {
  // Call the function a few times, and make sure it returns phone numbers in a
  // standard US format.
  for i := 0; i < 25; i++ {
    _, phone := GetRandomPerson()
    ogletest.ExpectThat(phone, oglematchers.MatchesRegexp(`^\(\d{3}\) \d{3}-\d{4}$`))
}

Note that test control functions (RunTests, ExpectThat, and so on) are part of the ogletest package, whereas built-in matchers (AnyOf, MatchesRegexp, and more) are part of the oglematchers library. You can of course use dot imports so that you don't need to prefix each function with its package name:

import (
  . "github.com/jacobsa/oglematchers"
  . "github.com/jacobsa/ogletest"
)

If you save the test in a file whose name ends in _test.go, you can run your tests by simply invoking the following in your package directory:

go test

Here's what the failure output of ogletest looks like, if your function's implementation is bad.

[----------] Running tests from PeopleTest
[ RUN      ] PeopleTest.FormatsPhoneNumbersCorrectly
people_test.go:32:
Expected: matches regexp "^\(\d{3}\) \d{3}-\d{4}$"
Actual:   +1 800 555 5555

[  FAILED  ] PeopleTest.FormatsPhoneNumbersCorrectly
[ RUN      ] PeopleTest.ReturnsCorrectNames
people_test.go:23:
Expected: or(Tony, Dennis, Scott)
Actual:   Bart

[  FAILED  ] PeopleTest.ReturnsCorrectNames
[----------] Finished with tests from PeopleTest

And if the test passes:

[----------] Running tests from PeopleTest
[ RUN      ] PeopleTest.FormatsPhoneNumbersCorrectly
[       OK ] PeopleTest.FormatsPhoneNumbersCorrectly
[ RUN      ] PeopleTest.ReturnsCorrectNames
[       OK ] PeopleTest.ReturnsCorrectNames
[----------] Finished with tests from PeopleTest
Expand ▾ Collapse ▴

Documentation

Overview

    Package ogletest provides a framework for writing expressive unit tests. It integrates with the builtin testing package, so it works with the gotest command. Unlike the testing package which offers only basic capabilities for signalling failures, it offers ways to express expectations and get nice failure messages automatically.

    For example:

    ////////////////////////////////////////////////////////////////////////
    // testing package test
    ////////////////////////////////////////////////////////////////////////
    
    someStr, err := ComputeSomeString()
    if err != nil {
      t.Errorf("ComputeSomeString: expected nil error, got %v", err)
    }
    
    !strings.Contains(someStr, "foo") {
      t.Errorf("ComputeSomeString: expected substring foo, got %v", someStr)
    }
    
    ////////////////////////////////////////////////////////////////////////
    // ogletest test
    ////////////////////////////////////////////////////////////////////////
    
    someStr, err := ComputeSomeString()
    ExpectEq(nil, err)
    ExpectThat(someStr, HasSubstr("foo")
    

    Failure messages require no work from the user, and look like the following:

    foo_test.go:103:
    Expected: has substring "foo"
    Actual:   "bar baz"
    

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func AbortTest

    func AbortTest()

      Immediately stop executing the running test, causing it to fail with the failures previously recorded. Behavior is undefined if no failures have been recorded.

      func AddFailure

      func AddFailure(format string, a ...interface{})

        Call AddFailureRecord with a record whose file name and line number come from the caller of this function, and whose error string is created by calling fmt.Sprintf using the arguments to this function.

        func AddFailureRecord

        func AddFailureRecord(r FailureRecord)

          Record a failure for the currently running test (and continue running it). Most users will want to use ExpectThat, ExpectEq, etc. instead of this function. Those that do want to report arbitrary errors will probably be satisfied with AddFailure, which is easier to use.

          func AssertEq

          func AssertEq(expected, actual interface{}, errorParts ...interface{})

            AssertEq(e, a) is equivalent to AssertThat(a, oglematchers.Equals(e)).

            func AssertFalse

            func AssertFalse(b interface{}, errorParts ...interface{})

              AssertFalse(b) is equivalent to AssertThat(b, oglematchers.Equals(false)).

              func AssertGe

              func AssertGe(x, y interface{}, errorParts ...interface{})

                AssertGe(x, y) is equivalent to AssertThat(x, oglematchers.GreaterOrEqual(y)).

                func AssertGt

                func AssertGt(x, y interface{}, errorParts ...interface{})

                  AssertGt(x, y) is equivalent to AssertThat(x, oglematchers.GreaterThan(y)).

                  func AssertLe

                  func AssertLe(x, y interface{}, errorParts ...interface{})

                    AssertLe(x, y) is equivalent to AssertThat(x, oglematchers.LessOrEqual(y)).

                    func AssertLt

                    func AssertLt(x, y interface{}, errorParts ...interface{})

                      AssertLt(x, y) is equivalent to AssertThat(x, oglematchers.LessThan(y)).

                      func AssertNe

                      func AssertNe(expected, actual interface{}, errorParts ...interface{})

                        AssertNe(e, a) is equivalent to AssertThat(a, oglematchers.Not(oglematchers.Equals(e))).

                        func AssertThat

                        func AssertThat(
                        	x interface{},
                        	m oglematchers.Matcher,
                        	errorParts ...interface{})

                          AssertThat is identical to ExpectThat, except that in the event of failure it halts the currently running test immediately. It is thus useful for things like bounds checking:

                          someSlice := [...]
                          AssertEq(1, len(someSlice))  // Protects next line from panicking.
                          ExpectEq("taco", someSlice[0])
                          

                          func AssertTrue

                          func AssertTrue(b interface{}, errorParts ...interface{})

                            AssertTrue(b) is equivalent to AssertThat(b, oglematchers.Equals(true)).

                            func ExpectCall

                            func ExpectCall(o oglemock.MockObject, method string) oglemock.PartialExpecation

                              ExpectCall expresses an expectation that the method of the given name should be called on the supplied mock object. It returns a function that should be called with the expected arguments, matchers for the arguments, or a mix of both.

                              For example:

                              mockWriter := [...]
                              ogletest.ExpectCall(mockWriter, "Write")(oglematchers.ElementsAre(0x1))
                                  .WillOnce(oglemock.Return(1, nil))
                              

                              This is a shortcut for calling i.MockController.ExpectCall, where i is the TestInfo struct for the currently-running test. Unlike that direct approach, this function automatically sets the correct file name and line number for the expectation.

                              func ExpectEq

                              func ExpectEq(expected, actual interface{}, errorParts ...interface{})

                                ExpectEq(e, a) is equivalent to ExpectThat(a, oglematchers.Equals(e)).

                                func ExpectFalse

                                func ExpectFalse(b interface{}, errorParts ...interface{})

                                  ExpectFalse(b) is equivalent to ExpectThat(b, oglematchers.Equals(false)).

                                  func ExpectGe

                                  func ExpectGe(x, y interface{}, errorParts ...interface{})

                                    ExpectGe(x, y) is equivalent to ExpectThat(x, oglematchers.GreaterOrEqual(y)).

                                    func ExpectGt

                                    func ExpectGt(x, y interface{}, errorParts ...interface{})

                                      ExpectGt(x, y) is equivalent to ExpectThat(x, oglematchers.GreaterThan(y)).

                                      func ExpectLe

                                      func ExpectLe(x, y interface{}, errorParts ...interface{})

                                        ExpectLe(x, y) is equivalent to ExpectThat(x, oglematchers.LessOrEqual(y)).

                                        func ExpectLt

                                        func ExpectLt(x, y interface{}, errorParts ...interface{})

                                          ExpectLt(x, y) is equivalent to ExpectThat(x, oglematchers.LessThan(y)).

                                          func ExpectNe

                                          func ExpectNe(expected, actual interface{}, errorParts ...interface{})

                                            ExpectNe(e, a) is equivalent to ExpectThat(a, oglematchers.Not(oglematchers.Equals(e))).

                                            func ExpectThat

                                            func ExpectThat(
                                            	x interface{},
                                            	m oglematchers.Matcher,
                                            	errorParts ...interface{})

                                              ExpectThat confirms that the supplied matcher matches the value x, adding a failure record to the currently running test if it does not. If additional parameters are supplied, the first will be used as a format string for the later ones, and the user-supplied error message will be added to the test output in the event of a failure.

                                              For example:

                                              ExpectThat(userName, Equals("jacobsa"))
                                              ExpectThat(users[i], Equals("jacobsa"), "while processing user %d", i)
                                              

                                              func ExpectTrue

                                              func ExpectTrue(b interface{}, errorParts ...interface{})

                                                ExpectTrue(b) is equivalent to ExpectThat(b, oglematchers.Equals(true)).

                                                func Register

                                                func Register(suite TestSuite)

                                                  Register a test suite for execution by RunTests.

                                                  This is the most general registration mechanism. Most users will want RegisterTestSuite, which is a wrapper around this function that requires less boilerplate.

                                                  Panics on invalid input.

                                                  func RegisterTestSuite

                                                  func RegisterTestSuite(p interface{})

                                                    RegisterTestSuite tells ogletest about a test suite containing tests that it should run. Any exported method on the type pointed to by the supplied prototype value will be treated as test methods, with the exception of the methods defined by the following interfaces, which when present are treated as described in the documentation for those interfaces:

                                                    *  SetUpTestSuiteInterface
                                                    *  SetUpInterface
                                                    *  TearDownInterface
                                                    *  TearDownTestSuiteInterface
                                                    

                                                    Each test method is invoked on a different receiver, which is initially a zero value of the test suite type.

                                                    Example:

                                                    // Some value that is needed by the tests but is expensive to compute.
                                                    var someExpensiveThing uint
                                                    
                                                    type FooTest struct {
                                                      // Path to a temporary file used by the tests. Each test gets a
                                                      // different temporary file.
                                                      tempFile string
                                                    }
                                                    func init() { ogletest.RegisterTestSuite(&FooTest{}) }
                                                    
                                                    func (t *FooTest) SetUpTestSuite() {
                                                      someExpensiveThing = ComputeSomeExpensiveThing()
                                                    }
                                                    
                                                    func (t *FooTest) SetUp(ti *ogletest.TestInfo) {
                                                      t.tempFile = CreateTempFile()
                                                    }
                                                    
                                                    func (t *FooTest) TearDown() {
                                                      DeleteTempFile(t.tempFile)
                                                    }
                                                    
                                                    func (t *FooTest) FrobinicatorIsSuccessfullyTweaked() {
                                                      res := DoSomethingWithExpensiveThing(someExpensiveThing, t.tempFile)
                                                      ExpectThat(res, Equals(true))
                                                    }
                                                    

                                                    func RunTests

                                                    func RunTests(t *testing.T)

                                                      Run everything registered with Register (including via the wrapper RegisterTestSuite).

                                                      Failures are communicated to the supplied testing.T object. This is the bridge between ogletest and the testing package (and `go test`); you should ensure that it's called at least once by creating a test function compatible with `go test` and calling it there.

                                                      For example:

                                                      import (
                                                        "github.com/jacobsa/ogletest"
                                                        "testing"
                                                      )
                                                      
                                                      func TestOgletest(t *testing.T) {
                                                        ogletest.RunTests(t)
                                                      }
                                                      

                                                      func StopRunningTests

                                                      func StopRunningTests()

                                                        Request that RunTests stop what it's doing. After the currently running test is finished, including tear-down, the program will exit with an error code.

                                                        Types

                                                        type FailureRecord

                                                        type FailureRecord struct {
                                                        	// The file name within which the expectation failed, e.g. "foo_test.go".
                                                        	FileName string
                                                        
                                                        	// The line number at which the expectation failed.
                                                        	LineNumber int
                                                        
                                                        	// The error associated with the file:line pair above. For example, the
                                                        	// following expectation:
                                                        	//
                                                        	//     ExpectEq(17, "taco")"
                                                        	//
                                                        	// May cause this error:
                                                        	//
                                                        	//     Expected: 17
                                                        	//     Actual:   "taco", which is not numeric
                                                        	//
                                                        	Error string
                                                        }

                                                          FailureRecord represents a single failed expectation or assertion for a test. Most users don't want to interact with these directly; they are generated implicitly using ExpectThat, AssertThat, ExpectLt, etc.

                                                          type SetUpInterface

                                                          type SetUpInterface interface {
                                                          	// This method is called before each test method is invoked, with the same
                                                          	// receiver as that test method. At the time this method is invoked, the
                                                          	// receiver is a zero value for the test suite type. Use this method for
                                                          	// common setup code that works on data not shared across tests.
                                                          	SetUp(*TestInfo)
                                                          }

                                                            Test suites that implement this interface have special meaning to Register.

                                                            type SetUpTestSuiteInterface

                                                            type SetUpTestSuiteInterface interface {
                                                            	// This method will be called exactly once, before the first test method is
                                                            	// run. The receiver of this method will be a zero value of the test suite
                                                            	// type, and is not shared with any other methods. Use this method to set up
                                                            	// any necessary global state shared by all of the test methods.
                                                            	SetUpTestSuite()
                                                            }

                                                              Test suites that implement this interface have special meaning to RegisterTestSuite.

                                                              type TearDownInterface

                                                              type TearDownInterface interface {
                                                              	// This method is called after each test method is invoked, with the same
                                                              	// receiver as that test method. Use this method for common cleanup code that
                                                              	// works on data not shared across tests.
                                                              	TearDown()
                                                              }

                                                                Test suites that implement this interface have special meaning to Register.

                                                                type TearDownTestSuiteInterface

                                                                type TearDownTestSuiteInterface interface {
                                                                	// This method will be called exactly once, after the last test method is
                                                                	// run. The receiver of this method will be a zero value of the test suite
                                                                	// type, and is not shared with any other methods. Use this method to clean
                                                                	// up after any necessary global state shared by all of the test methods.
                                                                	TearDownTestSuite()
                                                                }

                                                                  Test suites that implement this interface have special meaning to RegisterTestSuite.

                                                                  type TestFunction

                                                                  type TestFunction struct {
                                                                  	// The name of this test function, relative to the suite in which it resides.
                                                                  	// If the name is "TweaksFrobnicator", then the function might be presented
                                                                  	// in the ogletest UI as "FooTest.TweaksFrobnicator".
                                                                  	Name string
                                                                  
                                                                  	// If non-nil, a function that is run before Run, passed a pointer to a
                                                                  	// struct containing information about the test run.
                                                                  	SetUp func(*TestInfo)
                                                                  
                                                                  	// The function to invoke for the test body. Must be non-nil. Will not be run
                                                                  	// if SetUp panics.
                                                                  	Run func()
                                                                  
                                                                  	// If non-nil, a function that is run after Run.
                                                                  	TearDown func()
                                                                  }

                                                                  type TestInfo

                                                                  type TestInfo struct {
                                                                  	// A mock controller that is set up to report errors to the ogletest test
                                                                  	// runner. This can be used for setting up mock expectations and handling
                                                                  	// mock calls. The Finish method should not be run by the user; ogletest will
                                                                  	// do that automatically after the test's TearDown method is run.
                                                                  	//
                                                                  	// Note that this feature is still experimental, and is subject to change.
                                                                  	MockController oglemock.Controller
                                                                  
                                                                  	// A context that can be used by tests for long-running operations. In
                                                                  	// particular, this enables conveniently tracing the execution of a test
                                                                  	// function with reqtrace.
                                                                  	Ctx context.Context
                                                                  	// contains filtered or unexported fields
                                                                  }

                                                                    TestInfo represents information about a currently running or previously-run test.

                                                                    type TestSuite

                                                                    type TestSuite struct {
                                                                    	// The name of the overall suite, e.g. "MyPackageTest".
                                                                    	Name string
                                                                    
                                                                    	// If non-nil, a function that will be run exactly once, before any of the
                                                                    	// test functions are run.
                                                                    	SetUp func()
                                                                    
                                                                    	// The test functions comprising this suite.
                                                                    	TestFunctions []TestFunction
                                                                    
                                                                    	// If non-nil, a function that will be run exactly once, after all of the
                                                                    	// test functions have run.
                                                                    	TearDown func()
                                                                    }

                                                                      The input to ogletest.Register. Most users will want to use ogletest.RegisterTestSuite.

                                                                      A test suite is the basic unit of registration in ogletest. It consists of zero or more named test functions which will be run in sequence, along with optional setup and tear-down functions.

                                                                      Directories

                                                                      Path Synopsis
                                                                      Functions for working with source code.
                                                                      Functions for working with source code.