ogletest: github.com/jacobsa/ogletest Index | Files | Directories

package ogletest

import "github.com/jacobsa/ogletest"

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

Package Files

assert_aliases.go assert_that.go doc.go expect_aliases.go expect_call.go expect_that.go methods.go register_test_suite.go run_tests.go test_info.go

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 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 following methods (which need not be present):

*  SetUpTestSuite() -- 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.

*  TearDownTestSuite() -- 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.

*  SetUp(testInfo) -- called before each test method is invoked, with the
   same receiver as that test method, and with a TestInfo arg. 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.

*  TearDown() -- 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.

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() {
  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)

RunTests runs the test suites registered with ogletest, communicating failures to the supplied testing.T object. This is the bridge between ogletest and the testing package (and gotest); you should ensure that it's called at least once by creating a gotest-compatible test function and calling it there.

For example:

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

func TestOgletest(t *testing.T) {
  ogletest.RunTests(t)
}

type ExpectationResult

type ExpectationResult interface {
    // SetCaller updates the file name and line number associated with the
    // expectation. This allows, for example, a utility function to express that
    // *its* caller should have its line number printed if the expectation fails,
    // instead of the line number of the ExpectThat call within the utility
    // function.
    SetCaller(fileName string, lineNumber int)

    // MatchResult returns the result returned by the expectation's matcher for
    // the supplied candidate.
    MatchResult() error
}

ExpectationResult is an interface returned by ExpectThat that allows callers to get information about the result of the expectation and set their own custom information. This is not useful to the average consumer, but may be helpful if you're writing widely used test utility functions.

func AssertEq

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

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

func AssertFalse

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

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

func AssertGe

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

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

func AssertGt

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

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

func AssertLe

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

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

func AssertLt

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

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

func AssertNe

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

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

func AssertThat

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

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{}) ExpectationResult

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

func ExpectEq

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

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

func ExpectFalse

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

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

func ExpectGe

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

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

func ExpectGt

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

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

func ExpectLe

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

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

func ExpectLt

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

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

func ExpectNe

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

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

func ExpectThat

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

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{}) ExpectationResult

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

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
    // contains filtered or unexported fields
}

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

Directories

PathSynopsis
test_cases
test_cases/mock_image

Package ogletest imports 13 packages (graph) and is imported by 12 packages. Updated 2014-04-23. Refresh now. Tools for package owners.