ogletest

package module
v0.0.0-...-80d50a7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2017 License: Apache-2.0 Imports: 17 Imported by: 75

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

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.

Source Files

View all Source files

Directories

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.