test

README

Test — convenient testing routines

test is a tiny library, which provides convenient generic testing routines with minimal interface. Its purpose is to reduce repeatable cluttering, which plagues many tests, for example, in the following form:

import "testing"

func TestSomething(t *testing.T) {
	if gotToTest != shouldBeEqualToThis {
		t.Fatalf(…)
	}
}

func TestAnotherSomething(t *testing.T) {
	if gotToTest == shouldNotBeEqualToThis {
		t.Fatalf(…)
	}
}

It should be mentioned, that frequently the messages in the calls to the method Fatalf are almost the same (and actually don't matter much). So, they could be replaced with some generic one, which just informs a developer with a line number of the test file and the values, which fail the check. With such an approach, the checks could be made generic too. In the end, every cluttering three lines of the tests could be replaced with just one call to a generic function.

The library offers exactly this in a form of its high-level workhorse functions Eq and NotEq. The functions check correspondingly equality and inequality of the provided values and message on failures through the provided instances of interface Failer. The interface is compatible with type testing.T and others, which provide method Fatalf. So, the usage of the functions would be something akin to the following:

import (
	"testing"

	"codeberg.org/alex-ilchukov/test"
)

func TestSomething(t *testing.T) {
	test.Eq(t, gotToTest, shouldBeEqualToThis)
}

func TestAnotherSomething(t *testing.T) {
	test.NotEq(t, gotToTest, shouldNotBeEqualToThis)
}

The failure messages include lines of codes, where the failures have happened, but the functions suppose, that they're called directly from the bodies of Test… functions. Also, the format template is fixed for the both functions.

Nevertheless, these limitations could be overcome with usage of testing contexts in form of instances of type T. (Both Eq and NotEq are just tiny wrappers around calls to the methods of some fixed instances of the type.) The type allows to specify, how far the stack should be unrolled to find the required line number and what format strings to use. For example, a common situation with bulk testing could be resolved like this:

import (
	"testing"

	"codeberg.org/alex-ilchukov/test"
)

func TestInBulk(t *testing.T) {
	tests := []struct{…}{…}

	// CallerSkip is not specified here, because line number has been
	// completely ommitted from the format template. Also, notice
	// numbered parameters in the string. The order goes like the
	// following: line number, obtained value, the value which the
	// obtained one should be equal to, all other arguments.
	testt := test.T{EqFormat: "test %[4]d: got %[2]v, should be %[3]v"}
	for i, tt := range tests {
		result := …
		testt.Eq(t, result, tt.result, i)
	}
}

The methods of the instances of T are variadic and just supply the additional arguments to the method Fatalf of the provided instance of Failer. In case of indirect calls to the methods, CallerSkip field could fix the stack unrolling:

import (
	"testing"

	"codeberg.org/alex-ilchukov/test"
)

// Use the format string of the library, but with deeper stack unrolling to
// show the line number of functions `Test…` instead of `prepareAndTest`
var testt = test.T{CallerSkip: 2, EqFormat: test.EqFormat}

func prepareAndTest(t *testing.T, …) {
	…
	testt.Eq(t, …, …)
}

func TestSomething1(t *testing.T) {
	…
	prepareAndTest(t, …)
}

func TestSomething2(t *testing.T) {
	…
	prepareAndTest(t, …)
}

License

The library is licensed under MIT license.

Documentation

Overview

Package test provides convenient testing routines in form of high-level generic functions Eq and NotEq, which check equality and inequality of the provided values and message on failures of the check with help of the provided instance of interface Failer. The interface is compatible with types from the package testing of the standard library of Go. The functions report in a fixed formats, which also include line numbers of their callers. They're supposed to be called from testing functions Test*.

The package provides more low-level layer in form of type T and its generic methods. The type allows to set up the depth of the unrolling of the caller stack and format templates of the messages. Also, its methods are variadic and allow to specify additional parameters, which could be supplied to the format template.

It should be mentioned, that the functions and the methods of the type also report on inability to unroll the stack. In such a case, they ignore the parameters.

Index

• Constants
• func Eq[V comparable](f Failer, got, shouldBe V)
• func NotEq[V comparable](f Failer, got, shouldNotBe V)
• type Failer
• type T
  • func (t *T) Eq[V comparable](f Failer, got, shouldBe V, args ...any)
  • func (t *T) NotEq[V comparable](f Failer, got, shouldNotBe V, args ...any)

Constants

const EqFormat = "test.Eq failed:%d: got %v, should be %v"

EqFormat is the format string, used by the function Eq

const NotEqFormat = "test.NotEq failed:%d: got %v and %[2]v"

NotEqFormat is the format string, used by the function NotEq

const Version = "v1.0.0"

Version of the library

Functions

func Eq

func Eq[V comparable](f Failer, got, shouldBe V)

Eq is a generic function of checking on equality between two provided values. It reports on failure of the condition through the provided instance of Failer, using (in exactly this order) line of the caller, first value (which is supposed to be obtained through the tested calculation) and second value (which the first value should be equal to). If the information on the caller is impossible to obtain, the function reports on that through a distinct message, ignoring the parameters.

func NotEq

func NotEq[V comparable](f Failer, got, shouldNotBe V)

NotEq is a generic function of checking on inequality between two provided values. It reports on failure of the condition through the provided instance of Failer, using (in exactly this order) line of the caller and first value. If the information on the caller is impossible to obtain, the function reports on that through a distinct message, ignoring the parameters.

Types

type Failer

type Failer interface {
	// Fatalf should report on a fatal situation in formatted way, which is
	// similar, for example, to [testing.T.Fatalf]
	Fatalf(string, ...any)
}

Failer is an abstract type of instances, which report on fatal situations

type T

type T struct {
	// CallerSkip is the parameter to the function [runtime.Caller], which
	// obtains data on files and lines of callers of the testing methods
	CallerSkip int

	// EqFormat is a format string, formed with the syntax of [fmt.Printf].
	// It is used to create a signal string, reporting on the fact, that
	// the provided value is not that should be (see method [T.Eq]). The
	// format should support the following parameters in the following
	// order:
	// 1)  integer (%d) line of the caller;
	// 2)  the provided value (%v);
	// 3)  the value, that should be (%v).
	//
	// As the method supports supplying of additional arguments, they
	// should appear after the parameters above.
	//
	// Examples:
	//
	//	"failure at %[1]d: got %[2]v, should be %[3]v"
	//	"%d: test %[4]d: %[2]v != %[3]v
	//
	// In the last example an additional parameter has been mentioned
	// (which seems like a test's order number). A caller of the method
	// [T.Eq] should provide a corresponding argument for such a format.
	EqFormat string

	// NotEqFormat is a format string, formed with the syntax of
	// [fmt.Printf]. It is used to create a signal string, reporting on the
	// fact, that the provided value is that should not be (see method
	// [T.NotEq]). The format should support the following parameters in
	// the following order:
	// 1)  integer (%d) line of the caller;
	// 2)  the provided value (%v), which is equal to the value, that
	//     should not be.
	//
	// As the method supports supplying of additional arguments, they
	// should appear after the parameters above.
	NotEqFormat string
}

T is a type of testing contexts. It provides testing methods T.Eq and T.NotEq, and encapsulates basic technical information to properly report failing conditions with the methods.

func (*T) Eq

func (t *T) Eq[V comparable](f Failer, got, shouldBe V, args ...any)

Eq is a generic method of checking on equality between two provided values. It reports on failure of the condition through the provided instance of Failer, using (in exactly this order) line of the caller, first value (which is supposed to be obtained through the tested calculation) and second value (which the first value should be equal to). The method also supports additional arguments, which are supplied to the instance of Failer after the values above, keeping the order. It takes its format string from the field T.EqFormat, but if the information on the caller is impossible to obtain, the method reports on that through a distinct message, ignoring the parameters.

func (*T) NotEq

func (t *T) NotEq[V comparable](f Failer, got, shouldNotBe V, args ...any)

NotEq is a generic method of checking on inequality between two provided values. It reports on failure of the condition through the provided instance of Failer, using (in exactly this order) line of the caller and first value. The method also supports additional arguments, which are supplied to the instance of Failer after the values above, keeping the order. It takes its format string from the field T.NotEqFormat field, but if the information on the caller is impossible to obtain, the method reports on that through a distinct message, ignoring the parameters.