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 failure.go register.go register_test_suite.go run_tests.go test_info.go

func AbortTest Uses

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 Uses

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 Uses

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 Uses

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

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

func AssertFalse Uses

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

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

func AssertGe Uses

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

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

func AssertGt Uses

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

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

func AssertLe Uses

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

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

func AssertLt Uses

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

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

func AssertNe Uses

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

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

func AssertThat Uses

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 Uses

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

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

func ExpectCall Uses

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 Uses

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

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

func ExpectFalse Uses

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

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

func ExpectGe Uses

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

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

func ExpectGt Uses

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

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

func ExpectLe Uses

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

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

func ExpectLt Uses

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

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

func ExpectNe Uses

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

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

func ExpectThat Uses

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 Uses

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

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

func Register Uses

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 Uses

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 Uses

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 Uses

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.

type FailureRecord Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

PathSynopsis
srcutilFunctions for working with source code.
test_cases
test_cases/mock_image

Package ogletest imports 17 packages (graph) and is imported by 25 packages. Updated 2017-05-04. Refresh now. Tools for package owners.