Warren Turkal edited this page Sep 14, 2015 · 7 revisions

Writing self-documenting tests is remarkably easy with GoConvey.


First, take a look through the examples folder to get the basic idea. We'd recommend reviewing isolated_execution_test.go for a more thorough understanding of how you can compose test cases.


See GoDoc for exported functions and assertions. You'd be most interested in the convey package.

Quick tutorial

In your test file, import needed packages:

	. ""

(Notice the dot-notation for the convey package, for convenience.)

Since GoConvey uses go test, set up a Test function:

func TestSomething(t *testing.T) {

To set up test cases, we use Convey() to define scope/context/behavior/ideas, and So() to make assertions. For example:

Convey("1 should equal 1", t, func() {
	So(1, ShouldEqual, 1)

There's a working GoConvey test. Notice that we pass in the *testing.T object. Only the top-level calls to Convey() require that. For nested calls, you must omit it. For instance:

Convey("Comparing two variables", t, func() {
	myVar := "Hello, world!"

	Convey(`"Asdf" should NOT equal "qwerty"`, func() {
		So("Asdf", ShouldNotEqual, "qwerty")

	Convey("myVar should not be nil", func() {
		So(myVar, ShouldNotBeNil)

If you haven't yet implemented a test or scope, just set its function to nil to skip it:

Convey("This isn't yet implemented", nil)


Next, you should learn about the standard assertions. You may also skip ahead to executing tests or to Skip to make testing more convenient.