ut

package module
v0.0.0-...-1babf69 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 7, 2021 License: LGPL-3.0 Imports: 14 Imported by: 0

README

µt - microTest, a simple go testing library

µt is a minimalist golang testing library designed so you can easily adapt it to your project, as opposed to forcing you to rewrite all your tests to conform to a particular structure. It has the following features:

  • Toolbox of checking functions, such as Assert, Ok, MustFail, Equals...
  • JSON marshalling out-of-the-box testing
  • Clear error messages when values don't match, even showing a diff
  • Test result storing and regeneration
  • Multi-goroutine support
  • Automated cleanup
  • TestServices allow you to wrap third-party instances of services you need in your tests, such as temporary files, folders, database instances...

Installing

To install µt, simply grab it using go get:

$ go get github.com/epiclabs-io/ut

Basic usage:

µt supports two usage modes: basic and advanced. The basic one gives you access to the built-in checking functions only.

package mypackage_test

import (
	"testing"
	. "github.com/epiclabs-io/ut"
	"github.com/epiclabs-io/ut/example/mypackage"
)

// Operation is a simple struct to demonstrate tests
type Operation struct {
	A   int     `json:"a"`
	B   int     `json:"b"`
	Sum int     `json:"sum"`
	Div float64 `json:"div"`
}

func TestBasic(t *testing.T) {
	// example struct:
	op := Operation{
		A: 10,
		B: 2,
	}
	var err error

	op.Sum = mypackage.Sum(op.A, op.B)
	Assert(t, op.Sum == 12, "Expected sum to equal 12, got %d", op.Sum)
	// another way:
	Equals(t, 12, op.Sum)

	op.Div, err = mypackage.Div(op.A, op.B)
	Ok(t, err)             // check there were no errors
	Equals(t, 5.0, op.Div) // check the correct value was returned

	_, err = mypackage.Div(op.A, 0)
	MustFail(t, err, "Expected div to fail since divisor is 0")
	MustFailWith(t, err, mypackage.ErrDivByZero) // you can also expect a specific error

	// Test JSON marshalling:
	expectedJSON := `{
		"a": 10,
		"b": 2,
		"sum": 12,
		"div": 5
	}`
	JSONEqualsString(t, expectedJSON, op)

	// note that the JSON keys do not have to be in the same order to be considered equal:
	expectedJSON = `{
		"div": 5,
		"b": 2,
		"sum": 12,
		"a": 10
	}`
	JSONEqualsString(t, expectedJSON, op)
}

Advanced usage:

Advanced usage allows for automatically generating test results to files in the testadata directory. When BeginTest() is called with its second parameter set to true, all files will be automatically regenerated.

BeginTest() replaces the regular testing.T object with a compatible one that adds all the functionality of µt.

Always defer a call to t.FinishTest() to allow µt to process all errors from concurrent goroutines, wait for them to finish and also clean up.

package mypackage_test

import (
	"testing"
	"github.com/epiclabs-io/ut"
	"github.com/epiclabs-io/ut/example/mypackage"
)

// We can further reduce testing code and improve clarity by using advanced mode:
func TestAdvanced(tx *testing.T) {
	t := ut.BeginTest(tx, false) // set to true to regenerate test results
	defer t.FinishTest() // always defer t.FinishTest() to cleanup, process errors and store results

	// example struct:
	op := Operation{
		A: 10,
		B: 2,
	}
	var err error

	op.Sum = mypackage.Sum(op.A, op.B)
	t.EqualsKey("sum", op.Sum) // result will be stored in testdata/TestAdvanced/results.json, under the "sum" key.
	// that way it can be regenerated automatically if we change test cases or the behavior of the tested function

	op.Div, err = mypackage.Div(op.A, op.B)
	t.Ok(err) // check there were no errors
	t.EqualsKey("div", op.Div)

	_, err = mypackage.Div(op.A, 0)
	t.MustFail(err, "Expected div to fail since divisor is 0")
	t.MustFailWith(err, mypackage.ErrDivByZero) // you can also expect a specific error

	t.JSONEqualsFile("operation.json", op) // result will be stored in testdata/TestAdvanced/operation.json
	// that way it can be regenerated automatically if we change test cases or the behavior of the tested function
}

Testing within goroutines

µt supports testing within child goroutines. This is not supported by the default go testing framework out of the box.

To create a child goroutine, use t.Go(func(){}) for a managed experience or launch a goroutine the regular way, taking care of incrementing the wait counters

Here is an example:

func TestConcurrent(tx *testing.T) 
	t := ut.BeginTest(tx, false)
	defer t.FinishTest()

	t.Go(func() {
		fmt.Println("lengthy process started...")
		time.Sleep(200 * time.Millisecond)
		// test some work that has to run in parallel
		t.Assert(1 == 1, "one should be equal to one!")
		fmt.Println("lengthy process finished...")

	})

	// you can also launch goroutines yourself, but you'll need to increment
	// the counter with t.RoutineStart() and call
	// t.RoutineEnd() when your routine ends, so the main routine can wait for it to finish

	t.RoutineStart()
	go func() {
		defer t.RoutineEnd()
		fmt.Println("second lengthy process started...")
		time.Sleep(300 * time.Millisecond)
		// test some work that has to run in parallel
		t.Assert(7 == 7, "seven should be equal to one!")
		t.Fatal("crashed!") // you can call any test function inside a goroutine
		fmt.Println("second lengthy process finished...")
	}()

	fmt.Println("Some quick tests here...")
	// test some other things
	t.Assert(5 > 3, "5 should be greater than 3.")
	fmt.Println("finished quick part...")

}

Output (note the 2nd goroutine has a Fatal call.):

Some quick tests here...
finished quick part...
second lengthy process started...
lengthy process started...
lengthy process finished...
/file.go:51: FATAL: crashed!
Error: Fatal error
1 errors
--- FAIL: TestConcurrent (0.30s)
FAIL

Test Services

µt includes the concept ot "test service". A Test service is a wrapper for some third-party functionality you need available during the test ,such as a throwaway database or a temporary folder that must be cleaned after the test ends. µt comes with FileServices by default, which provides temporary files and folders that are automatically deleted once the test is finished.

func TestServices(tx *testing.T) {
	t := ut.BeginTest(tx, false) // set to true to regenerate test results
	defer t.FinishTest()

	tempFileName := t.Services.NewTempFile() // request a temporary file
	err := ioutil.WriteFile(tempFileName, []byte("Some data"), 0666)
	t.Ok(err)

	tempDir := t.Services.NewTempDir() // request a temporary folder
	for i := 0; i < 5; i++ {
		err = ioutil.WriteFile(filepath.Join(tempDir, fmt.Sprintf("file-%d.txt", i)), []byte("some data!"), 0666)
		t.Ok(err)
	}
	// temp files and folders are cleaned up.
}

Customizing for your project

One aspect that makes µt powerful is how easy it is to customize and extend for your project. This enables you to add custom test functions and services that are unique to your project.

To extend µt, do the following:

  1. Create a testutils package. You probably already have in your project some package where you have put all sorts of helper functions to help you test. If you already have it, use it.
  2. Add a two new files with this content:

testutils.go: Here we add custom testing functions

// ExampleTestTools defines test helper functions
// for your project
type ExampleTestTools struct {
	*ut.TestTools
	Services *exampleServices
}

// BeginTest starts the test
// set generateResults to true to save test results to files.
func BeginTest(tb testing.TB, generateResults bool) *ExampleTestTools {
	ett := new(ExampleTestTools)
	ett.TestTools = ut.ToolsBeginTest(tb, false)
	ett.Services = newExampleServices(ett)
	return ett
}

testservices.go: Here we add custom test services

type exampleServices struct {
	tt               *ExampleTestTools
	*ut.FileServices // embed file services so we get managed temp files and folders
}

func newExampleServices(tt *ExampleTestTools) *exampleServices {
	return &exampleServices{
		tt:           tt,
		FileServices: ut.NewFileServices(tt.TestTools),
	}
}

That's the basic. Now you can add custom testers like below:

func (ett *ExampleTestTools) IsLongString(st string) {
	if len(st) < 100 {
		// use Internal methods to correctly print the line where the error took place,
		// otherwise the error message would always refer to this function, not very useful.
		ut.Internal.Fatalf(0, "Expected the string to be long, got string of length=%d", len(st))
		ett.FailNow()
	}
}

You can also add custom services:

func (es *exampleServices) NewOpenFileForWriting() *os.File {
	file, err := os.Create(es.NewTempFile())
	es.tt.Ok(err)
	es.tt.AddService(file) // add service so .Close() is called when test ends.
	return file
}

Putting it all together:

func TestCustom(tx *testing.T) {
	t := testutils.BeginTest(tx, false)
	defer t.FinishTest()

	longString := strings.Repeat("A", 101)
	t.IsLongString(longString) // assert it is a long string

	file := t.Services.NewOpenFileForWriting() // get a new file for writing stuff

	i, err := file.WriteString(longString)
	t.Ok(err)
	t.Assert(i == len(longString), "Expected to have written the entire string")
}

Licensing

µt is licensed under the GNU LGPLv3.

Authors

µt is used by Ethergit and other internal projects. It is written and maintained by @jpeletier / Epic Labs. Please feel free to contact me for any questions or comments!

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var GENERATE_RESULTS bool

GENERATE_RESULTS is a global flag that haves all tests generate test results rather than verify them

View Source 
var Internal internal

Internal defines test functions that can be used to build other test functions It is built as a struct to avoid polluting the namespace These functions just make checks or print messages, they don't stop the test

Functions

func Assert 

func Assert(tb T, condition bool, msg string, v ...interface{})

Assert fails the test if the condition is false.

func CreateDirectory 

func CreateDirectory(path string)

CreateDirectory creates a directory and all necessary parents.

func Equals 

func Equals(tb T, expected, actual interface{})

Equals fails the test if exp is not equal to act.

func JSONEquals 

func JSONEquals(tb T, expected, actual []byte)

JSONEquals fails if provided JSONs are not equivalent

func JSONEqualsString 

func JSONEqualsString(tb T, expected string, actual interface{})

JSONEqualsString performs a JSON comparison of the given object with the JSON contained in the referenced string

func MustFail 

func MustFail(tb T, err error, msg string, v ...interface{})

MustFail checks if err == nil. If so, it fails the test

func MustFailWith 

func MustFailWith(tb T, err error, expectedError error)

MustFailWith checks if err equals an expected error. If not, it will fail the test.

func NewService 

func NewService(cleanup func() error) *serviceWrapper

func Ok 

func Ok(tb T, err error)

Ok fails the test if an err is not nil.

func RandomArray 

func RandomArray(i, length int) []byte

RandomArray returns a deterministically generated random array so values are the same across tests.

Types

type DefaultServices 

type DefaultServices struct {
	*FileServices
	RandomServices
}

type DefaultTestTools 

type DefaultTestTools struct {
	*TestTools
	Services *DefaultServices
}

func BeginTest 

func BeginTest(tb testing.TB, generateResults bool) *DefaultTestTools

type FileServices 

type FileServices struct {
	// contains filtered or unexported fields
}

func NewFileServices 

func NewFileServices(t *TestTools) *FileServices

func (*FileServices) NewTempDir 

func (fs *FileServices) NewTempDir() string

func (*FileServices) NewTempFile 

func (fs *FileServices) NewTempFile() string

type RandomServices 

type RandomServices struct{}

func (*RandomServices) RandomArray 

func (rs *RandomServices) RandomArray(i, length int) []byte

RandomArray returns a deterministically seeded random array of the given length

type Service 

type Service interface {
	Close() error
}

Service is an interface to define a test service that needs cleanup on finish

type StringSubTest 

type StringSubTest string

StringSubTest is a simple subtest that is a string

func (*StringSubTest) String 

func (ss *StringSubTest) String() string

type SubTest 

type SubTest interface {
	fmt.Stringer
}

SubTest interface allows you to define a custom subtest

type T 

type T interface {
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Fail()
	FailNow()
	Failed() bool
	Fatal(args ...interface{})
	Fatalf(format string, args ...interface{})
	Log(args ...interface{})
	Logf(format string, args ...interface{})
	Name() string
}

T is a interface to *testing.T with the minimal set of methods needed

type TempDir 

type TempDir struct {
	// contains filtered or unexported fields
}

func (*TempDir) Close 

func (td *TempDir) Close() error

type TestTools 

type TestTools struct {
	T
	W sync.WaitGroup

	SubTest     SubTest
	TestdataDir string

	Results results
	// contains filtered or unexported fields
}

TestTools is a replacement for testing.T that adds useful testing methods

func ToolsBeginTest 

func ToolsBeginTest(t T, generateResults bool) *TestTools

ToolsBeginTest takes a *testing.T and returns a replacement TestTools. Don't forget to defer t.FinishTest() to ensure cleanup

func (*TestTools) AddService 

func (tt *TestTools) AddService(s Service)

AddService adds a service that will be cleaned up when the test ends for any reason.

func (*TestTools) Assert 

func (tt *TestTools) Assert(condition bool, msg string, v ...interface{})

Assert verifies if the condition is true. If not, it fails the test

func (*TestTools) EndSubTest 

func (tt *TestTools) EndSubTest()

EndSubTest indicates a subtest has finished

func (*TestTools) Equals 

func (tt *TestTools) Equals(expected, actual interface{})

Equals tests if both objects are "deeply equal", otherwise it fails the test

func (*TestTools) EqualsFile 

func (tt *TestTools) EqualsFile(file string, actual interface{})

EqualsFile checks if the passed "actual" value is equivalent to its JSON version contained in the indicated file in the current test's testadata folder

func (*TestTools) EqualsKey 

func (tt *TestTools) EqualsKey(key string, actual interface{})

EqualsKey verifies if the passed "actual" value is equal to the value in the given key of the current test's results.json

func (*TestTools) EqualsTextFile 

func (tt *TestTools) EqualsTextFile(file string, actual string)

EqualsTextFile checks if the passed "actual" value is equivalent to the text contained in the indicated file in the current test's testadata folder

func (*TestTools) Error 

func (tt *TestTools) Error(err error)

Error stops the test with the given error

func (*TestTools) Fatal 

func (tt *TestTools) Fatal(args ...interface{})

Fatal will fail the test immediately with an error message

func (*TestTools) Fatalf 

func (tt *TestTools) Fatalf(formatString string, args ...interface{})

Fatalf will fail the test immediately with a formatted error message

func (*TestTools) FinishTest 

func (tt *TestTools) FinishTest()

FinishTest waits for all test goroutines and cleans up

func (*TestTools) Go 

func (tt *TestTools) Go(subroutine func())

Go will launch a test goroutine

func (*TestTools) JSONBytesEqualsFile 

func (tt *TestTools) JSONBytesEqualsFile(file string, actual []byte)

JSONBytesEqualsFile performs a JSON comparison of the provided JSON bytes with the JSON contained in the referenced file

func (*TestTools) JSONEquals 

func (tt *TestTools) JSONEquals(expected, actual []byte)

JSONEquals checks if the passed values are JSON-equal, comparing values taking into account keys can be in different order, etc.

func (*TestTools) JSONEqualsFile 

func (tt *TestTools) JSONEqualsFile(file string, actual interface{})

JSONEqualsFile performs a JSON comparison of the given object with the JSON contained in the referenced file

func (*TestTools) MustFail 

func (tt *TestTools) MustFail(err error, msg string, v ...interface{})

MustFail checks if err == nil. If so, it fails the test

func (*TestTools) MustFailWith 

func (tt *TestTools) MustFailWith(err error, expectedError error)

MustFailWith checks if err equals an expected error. If not, it will fail the test.

func (*TestTools) MustPanic 

func (tt *TestTools) MustPanic(f func())

MustPanic runs a function and checks that it panics

func (*TestTools) MustPanicWith 

func (tt *TestTools) MustPanicWith(expectedMessage interface{}, f func())

MustPanicWith runs a function and checks that it panics throwing a specific value

func (*TestTools) Ok 

func (tt *TestTools) Ok(err error)

Ok checks if there is no error. Otherwise it fails the test

func (*TestTools) RoutineEnd 

func (tt *TestTools) RoutineEnd()

RoutineEnd notifies a child goroutine is finished

func (*TestTools) RoutineStart 

func (tt *TestTools) RoutineStart()

RoutineStart adds one to the goroutine waiting counter

func (*TestTools) StartSubTest 

func (tt *TestTools) StartSubTest(fmtString string, args ...interface{})

StartSubTest marks the beginning of a new subtest

func (*TestTools) TestJSONMarshaller 

func (tt *TestTools) TestJSONMarshaller(filename string, sample interface{})

TestJSONMarshaller is a convenient tool to test JSON marshalling/unmarshalling matching the marshalled data to the referenced file.

Source Files

View all Source files

Directories

Path Synopsis
example
mypackage
somepackage
testutils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.