DEV Community

Cover image for Example tests in Go
Stefan Alfbo
Stefan Alfbo

Posted on

Example tests in Go

I really like the tooling in Go when working with different kind of tests.

This time we will explore the Example feature in the testing package from the standard library. This is often used in the documentation of packages and can be displayed as it's done in the fmt package.

Example from fmt

To show how this is working in practice we will reuse the calculator code from the quick.Check post.



package calculator

// Calculator defines a simple calculator with basic operations.
type Calculator struct{}

func (c *Calculator) Add(a, b int) int {
    return a + b
}

func (c *Calculator) Subtract(a, b int) int {
    return a - b
}

func (c *Calculator) Multiply(a, b int) int {
    return a * b
}

func isZero(n int) bool {
    return n == 0
}

func (c *Calculator) Divide(a, b int) int {
    if isZero(b) {
        panic("division by zero")
    }

    return a / b
}


Enter fullscreen mode Exit fullscreen mode

The example tests are located in a package's _test.go file, and of course there is a naming convention for an example test, the function should start with the prefix Example.

Lets create a calculator_test.go file and write our first example test.



package calculator_test

import (
    calculator "example/tests"
    "fmt"
)

func ExampleCalculator_Add() {
    c := calculator.Calculator{}
    fmt.Println(c.Add(1, 2))
    // Output: 3
}



Enter fullscreen mode Exit fullscreen mode

And by running go test -v we will get this output.

go test

As you can see it runs the example test like a regular unit test. If we change the comment to // Output: 4 in the example test above, we will get following result.

failed test

Now the test failed, but lets move on and see if can visualize our example test. I have initialized the calculator go module like this.



go mod init example/tests


Enter fullscreen mode Exit fullscreen mode

By running the command, go doc, the output will look like this.

go doc

No traces of the example test in that output. However if we install the godoc tool we will get a better result.



go install golang.org/x/tools/cmd/godoc


Enter fullscreen mode Exit fullscreen mode

And then start the go documentation server.



godo -http=:6060


Enter fullscreen mode Exit fullscreen mode

Now when we surf to, http://localhost:6060/, there will be a familiar page there, and somewhere in the middle of that page we can see our package.

example test

Click on tests and go down to the documentation for our Add function.

example test for add

Voila, there it is, the example test. The fmt documentation also has an entire test file as an example. To make that happen you will need to fulfill this:

The entire test file is presented as the example when it contains a single example function, at least one other function, type, variable, or constant declaration, and no test or benchmark functions.

Ok, create a new file called, calculator_subtract_test.go and add the following code to it.



package calculator_test

import (
    calculator "example/tests"

    "fmt"
)

func Print(result int) {
    fmt.Println(result)
}

func ExampleCalculator_Subtract() {
    c := calculator.Calculator{}
    Print(c.Subtract(2, 1))
    // Output: 1
}


Enter fullscreen mode Exit fullscreen mode

Here we are adding at least one other function, Print. Refresh the documentation page and you will see the following in the example code for the Subtract function.

subtraction code

There it is, an entire test file as an example. To learn more then perhaps this blog, Testable Examples in Go, on the The Go Blog can be a good starting point.

Take care!

Top comments (0)