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
|
[](https://godoc.org/github.com/smartystreets/assertions/internal/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/smartystreets/assertions/internal/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/smartystreets/assertions/internal/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/smartystreets/assertions/internal/oglematchers"
"github.com/smartystreets/assertions/internal/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/smartystreets/assertions/internal/oglematchers"
. "github.com/smartystreets/assertions/internal/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/smartystreets/assertions/internal/ogletest
[matcher-reference]: http://godoc.org/github.com/smartystreets/assertions/internal/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/smartystreets/assertions/internal/oglemock
|
