How to write a unit test

See also: Unit testing

This document demonstrates how to write a unit test for juju.

We will assume a scenario where we are creating a new provider for a cloud called “magic”, so we have a package called magic that lives at github.com/juju/juju/provider/magic with a bunch of code files, magic1.go, magic2.go, … , and we want set up a unit test for the code in file magic1.go.

Contents:

Prepare for the test

Create package_test.go

This step is necessary only if this file doesn’t already exist.

In the code directory (in our example, provider/magic/), create a file with the name package_test.go. This file contains mandatory contents before you can start doing any test. The exact contents will depend on whether you need a MongoDB for your tests (i.e., you use the util suite JujuConSuite) or not. Below we illustrate both.

Here is an example for the basic case where you do not need a MongoDB: We import the “testing” package from the standard library and then the gocheck package as gc. We also create a function Test that will be the entrypoint into our test suites.


// Copyright 20XX Canonical Ltd.

// Licensed under the AGPLv3, see LICENCE file for details.

package magic_test

import (

  "testing"

  gc "gopkg.in/check.v1"

)


func Test(t *testing.T) {

  gc.TestingT(t)

}

Here is an example for the basic case where you do need a MongoDB: We import the standard testing package as stdtesting and then the Juju testing package. Then we create a function Test that does the same as before (Test is a wrapper around gc.TestingT(t)) but also gives you access to a MongoDB.


// Copyright 20XX Canonical Ltd.

// Licensed under the AGPLv3, see LICENCE file for details.

package magic_test

import (

  stdtesting "testing"

  "github.com/juju/juju/testing"

)

func Test(t *stdtesting.T) {

  testing.MgoTestPackage(t)

}

Create <code-filename>_test.go

In the code directory (in our scenario, provider/magic), for each file that you want to test (in our scenario, magic1.go), create a <code-filename>_test.go (given our scenario, magic1_test.go).

Import gocheck

See also: gocheck

In magic1_test.go, import the gocheck package as gc:

import (

  gc "gopkg.in/check.v1"

)

gc is the usual alias for gocheck across all the Juju repositories.

Add a unit test suite

See also: Unit test suite

Also in magic1_test.go, add a unit test suite. A unit test suite can be as simple as an empty struct, but can also inherit complex functionality from predefined util test suites. For more see How to create a unit test suite.

Write the test

See also: Checkers

In magic1_test.go, below the test suite, start adding your unit test functions.

The process is as follows: You target some behavior (usually a function) in the code file (in our case, magic1). You then write a test for it, where the test usually follows the same Given, When, Then logic.

For example, suppose your magic1.go file defines a simple function called Sum:

func Sum(a, b int) int {
	return a + b
}

Then, in your magic1_test.go file you can write a test for it as follows (where gc.Equals is a Checker):

// GIVEN a equals 5 AND b equals 3
// WHEN a and b are summed 
// THEN we get 8
func (s *magicSuite) TestSum(c *gc.C) {
	a := 5
	b := 3

	res := magic.Sum(a,b)

	c.Assert(res, gc.Equals, 8)
}

Run the test

Finally, to run the test, do:

go test github.com/juju/juju/provider/magic/

This will run all the tests in the magic directory, including the one we just wrote.

You can also run an individual test. For more customized launching of tests, see gocheck > Selecting which tests to run .


Last updated 3 months ago.