catch

README

Package catch

Package catch provides utility functions that work with the standard library's testing capabilities. The functions encapsulate standard tests, and standardise logging for failures. However, package catch does not output anything directly. All messages are formatted using the standard methods on the test object.

As an example, when the following test fails:

func TestFancyCalculation(t *testing.T) {
    fancyCalculation := 1 + 1
    catch.CheckEqual(t, 1, fancyCalculation)
}

The log will be:

testing_test.go:285: check failed: 1 == fancyCalculation
        expected : 1
        got      : 2

The source files for the test code should be available and unmodified at their original locations when the tests are run. The source code is read and partially parsed to create messages for any failed tests. If the source code is not available, tests can still be run, but the messages for any failed tests will not be complete.

Install

Go version 1.9 or later is required. The package can be installed from the command line using the go tool.

go get gitlab.com/stone.code/catch

This package will not work with go version 1.8 or earlier. It depends on the method Helper for testing.B and testing.T to properly format messages.

Getting Started

Package documentation and examples are on godoc.

Contribute

Feedback and PRs welcome. You can also submit an issue.

This package is considered to be complete, but additional checks may be considered. However, other types of utility functions are probably out-of-scope.

Related Projects

• Catch2: A modern, C++-native, header-only, test framework for unit-tests, TDD and BDD.
• github.com/frankban/quicktest: Package quicktest provides a collection of Go helpers for writing tests.
• github.com/matryer/is: Package is provides a lightweight extension to the standard library's testing capabilities.
• github.com/stretchr/testify: Package testify is a set of packages that provide many tools for testifying that your code will behave as you intend.
• gopkg.in/check.v1: Package check is a rich testing extension for Go's testing package.

License

BSD (c) Robert Johnstone

Documentation

Overview

Package catch provides utility functions that work with the standard library's testing capabilities. The functions encapsulate standard tests, and standardise logging for failures. However, package catch does not output anything directly. All messages are formatted using the standard methods on the test object.

As an example, when the following test fails:

func TestFancyCalculation(t *testing.T) {
    fancyCalculation := 1 + 1
    catch.CheckEqual(t, fancyCalculation, 1)
}

The log will be:

testing_test.go:285: check failed: fancyCalculation == 1
        got      : 2
        expected : 1

The source files for the test code should be available and unmodified at their original locations when the tests are run. The source code is read and partially parsed to create messages for any failed tests. If the source code is not available, tests can still be run, but the messages for any failed tests will not be complete.

Message Formatting

When a test fails, package catch will create an error message based on the the user's source code. The source code for the helper's caller will be opened, and the expression for the arguments included in the error report.

If the line with error contains a line comment, the line comment will also be included in the error message.

Index

• func Check(t TB, value bool)
• func CheckEqual(t TB, got, expected interface{})
• func CheckIsNil(t TB, got interface{})
• func Require(t TB, value bool)
• func RequireEqual(t TB, got, expected interface{})
• func RequireIsNil(t TB, got interface{})
• type TB

Examples

• Check
• CheckEqual
• CheckIsNil
• Require
• Require (Fail)

Functions

func Check

func Check(t TB, value bool)

Check does nothing if 'value' is true, but will a report an error if it is false. The error is reported using Errorf, meaning that the error will be logged and the test will be marked as failing.

Example

package main

import (
	"testing"

	"gitlab.com/stone.code/catch"
)

func main() {
	// This is setup as a benchmark, but that is just to get a context for the
	// tests.
	testing.Benchmark(func(b *testing.B) {
		// Test setup goes here.
		// ...
		fancyResult := 1 + 1

		// Make sure that the result is expected
		catch.Check(b, fancyResult == 2)
	})
}

func CheckEqual

func CheckEqual(t TB, got, expected interface{})

CheckEqual does nothing if 'expected' and 'got' are equal, but will a report an error otherwise. The error is reported using Errorf, meaning that the error will be logged and the test will be marked as failing.

Example

package main

import (
	"testing"

	"gitlab.com/stone.code/catch"
)

func main() {
	// This is setup as a benchmark, but that is just to get a context for the
	// tests.
	testing.Benchmark(func(b *testing.B) {
		// Test setup goes here.
		// ...
		fancyResult := 1 + 1

		// Make sure that the result is expected
		catch.CheckEqual(b, fancyResult, 2)
	})
}

func CheckIsNil

func CheckIsNil(t TB, got interface{})

CheckIsNil does nothing if 'got' is a nil chan, func, map, pointer, or slice value, but will a report an error otherwise. The error is reported using Errorf, meaning that the error will be logged and the test will be marked as failing.

This function can only be called with chan, func, map, pointer, or slice values. It will panic otherwise.

Example

package main

import (
	"testing"

	"gitlab.com/stone.code/catch"
)

func main() {
	// This is setup as a benchmark, but that is just to get a context for the
	// tests.
	testing.Benchmark(func(b *testing.B) {
		// Test setup goes here.
		// ...
		var s []byte

		// Make sure that the result is expected
		catch.CheckIsNil(b, s)
	})
}

func Require

func Require(t TB, value bool)

Require does nothing if 'value' is true, but will a report an error if it is false. The error is reported using Fatalf, meaning that the error will be logged and the test will fail immediately.

Example

package main

import (
	"os"
	"testing"

	"gitlab.com/stone.code/catch"
)

func main() {
	// This is setup as a benchmark, but that is just to get a context for the
	// tests.
	testing.Benchmark(func(b *testing.B) {
		// Open file with test data.  Abort the test if the file cannot be
		// opened.
		file, err := os.Open("required-test-data.txt")
		catch.Require(b, err == nil)
		// No error.  Otherwise, test would have been aborted by the previous
		// call to Require.
		defer file.Close()

		// Count the number of lines in the file.
		fancyResult := 1 + 1

		// Make sure that the result is expected.
		catch.Require(b, fancyResult == 2)
	})
}

Example (Fail)

package main

import (
	"fmt"
	"testing"

	"gitlab.com/stone.code/catch"
)

func main() {
	// This is setup as a benchmark, but that is just to get a context for the
	// tests.
	testing.Benchmark(func(b *testing.B) {
		// Perform a terribly complicated calculations.
		fancyResult := 1 + 2

		// Make sure that the result is expected.
		fmt.Println("Require...")
		catch.Require(b, fancyResult == 2)
		fmt.Println("done.")
	})

}

Output:

Require...

func RequireEqual

func RequireEqual(t TB, got, expected interface{})

RequireEqual does nothing if 'expected' and 'got' are equal, but will a report an error otherwise. The error is reported using Fatalf, meaning that the error will be logged and the test will fail immediately.

func RequireIsNil

func RequireIsNil(t TB, got interface{})

RequireIsNil does nothing if 'got' is a nil chan, func, map, pointer, or slice value, but will a report an error otherwise. The error is reported using Fatalf, meaning that the error will be logged and the test will fail immediately.

This function can only be called with chan, func, map, pointer, or slice values. It will panic otherwise.

Types

type TB

type TB interface {
	Errorf(format string, args ...interface{})
	Fatalf(format string, args ...interface{})
	Logf(format string, args ...interface{})
	Helper()
}

TB is a subset of the interface testing.TB. These methods are the portion of that interface required for the checks.