1GoConvey is awesome Go testing
2==============================
3
4[![Build Status](https://travis-ci.org/smartystreets/goconvey.png)](https://travis-ci.org/smartystreets/goconvey)
5[![GoDoc](https://godoc.org/github.com/smartystreets/goconvey?status.svg)](http://godoc.org/github.com/smartystreets/goconvey)
6
7
8Welcome to GoConvey, a yummy Go testing tool for gophers. Works with `go test`. Use it in the terminal or browser according to your viewing pleasure. **[View full feature tour.](http://goconvey.co)**
9
10**Features:**
11
12- Directly integrates with `go test`
13- Fully-automatic web UI (works with native Go tests, too)
14- Huge suite of regression tests
15- Shows test coverage (Go 1.2+)
16- Readable, colorized console output (understandable by any manager, IT or not)
17- Test code generator
18- Desktop notifications (optional)
19- Immediately open problem lines in [Sublime Text](http://www.sublimetext.com) ([some assembly required](https://github.com/asuth/subl-handler))
20
21
22You can ask questions about how to use GoConvey on [StackOverflow](http://stackoverflow.com/questions/ask?tags=goconvey,go&title=GoConvey%3A%20). Use the tags `go` and `goconvey`.
23
24**Menu:**
25
26- [Installation](#installation)
27- [Quick start](#quick-start)
28- [Documentation](#documentation)
29- [Screenshots](#screenshots)
30- [Contributors](#contributors)
31
32
33
34
35Installation
36------------
37
38	$ go get github.com/smartystreets/goconvey
39
40[Quick start](https://github.com/smartystreets/goconvey/wiki#get-going-in-25-seconds)
41-----------
42
43Make a test, for example:
44
45```go
46package package_name
47
48import (
49    "testing"
50    . "github.com/smartystreets/goconvey/convey"
51)
52
53func TestSpec(t *testing.T) {
54
55	// Only pass t into top-level Convey calls
56	Convey("Given some integer with a starting value", t, func() {
57		x := 1
58
59		Convey("When the integer is incremented", func() {
60			x++
61
62			Convey("The value should be greater by one", func() {
63				So(x, ShouldEqual, 2)
64			})
65		})
66	})
67}
68```
69
70
71#### [In the browser](https://github.com/smartystreets/goconvey/wiki/Web-UI)
72
73Start up the GoConvey web server at your project's path:
74
75	$ $GOPATH/bin/goconvey
76
77Then watch the test results display in your browser at:
78
79	http://localhost:8080
80
81
82If the browser doesn't open automatically, please click [http://localhost:8080](http://localhost:8080) to open manually.
83
84There you have it.
85![](http://d79i1fxsrar4t.cloudfront.net/goconvey.co/gc-1-dark.png)
86As long as GoConvey is running, test results will automatically update in your browser window.
87
88![](http://d79i1fxsrar4t.cloudfront.net/goconvey.co/gc-5-dark.png)
89The design is responsive, so you can squish the browser real tight if you need to put it beside your code.
90
91
92The [web UI](https://github.com/smartystreets/goconvey/wiki/Web-UI) supports traditional Go tests, so use it even if you're not using GoConvey tests.
93
94
95
96#### [In the terminal](https://github.com/smartystreets/goconvey/wiki/Execution)
97
98Just do what you do best:
99
100    $ go test
101
102Or if you want the output to include the story:
103
104    $ go test -v
105
106
107[Documentation](https://github.com/smartystreets/goconvey/wiki)
108-----------
109
110Check out the
111
112- [GoConvey wiki](https://github.com/smartystreets/goconvey/wiki),
113- [![GoDoc](https://godoc.org/github.com/smartystreets/goconvey?status.png)](http://godoc.org/github.com/smartystreets/goconvey)
114- and the *_test.go files scattered throughout this project.
115
116[Screenshots](http://goconvey.co)
117-----------
118
119For web UI and terminal screenshots, check out [the full feature tour](http://goconvey.co).
120
121Contributors
122----------------------
123
124GoConvey is brought to you by [SmartyStreets](https://github.com/smartystreets) and [several contributors](https://github.com/smartystreets/goconvey/graphs/contributors) (Thanks!).
125