/usr/share/gocode/src/github.com/jacobsa/ogletest/README.md is in golang-github-jacobsa-ogletest-dev 0.0~git20150610-6.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | [![GoDoc](https://godoc.org/github.com/jacobsa/ogletest?status.svg)](https://godoc.org/github.com/jacobsa/ogletest)
`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][googletest] and
[Google JS Test][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][golang-install] 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][reference] 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][matcher-reference] 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:
```go
// 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:
```go
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][matcher-reference] library. You can of
course use dot imports so that you don't need to prefix each function with its
package name:
```go
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
[reference]: http://godoc.org/github.com/jacobsa/ogletest
[matcher-reference]: http://godoc.org/github.com/jacobsa/oglematchers
[golang-install]: http://golang.org/doc/install.html
[googletest]: http://code.google.com/p/googletest/
[google-js-test]: http://code.google.com/p/google-js-test/
[howtowrite]: http://golang.org/doc/code.html
[oglemock]: https://github.com/jacobsa/oglemock
|