Documentation

Overview

Package tdsuite adds tests suite feature to go-testdeep in a non-intrusive way, but easily and powerfully.

A tests suite is a set of tests run sequentially that share some data.

Some hooks can be set to be automatically called before the suite is run, before, after and/or between each test, and at the end of the suite.

In addition, a test can discontinue the suite.

Giving a suite using a MySuite type, the test methods have the form:

func (s *MySuite) TestXxx(t *td.T)
func (s *MySuite) TestXxx(assert, require *td.T)

where Xxx does not start with a lowercase letter. Each test method is run in a subtest, the method name serves to identify the subtest.

A test method can return a bool, as in:

func (s *MySuite) TestXxx(t *td.T) bool
func (s *MySuite) TestXxx(assert, require *td.T) bool

in this case, returning false means discontinuing the suite without any error. Consider it as a skip feature.

A test method can instead return an error, as in:

func (s *MySuite) TestXxx(t *td.T) error
func (s *MySuite) TestXxx(assert, require *td.T) error

in this case, returning a non-nil error marks the test as having failed, logs the error and discontinues the suite.

A test method can also return a tuple (bool, error), as in:

func (s *MySuite) TestXxx(t *td.T) (bool, error)
func (s *MySuite) TestXxx(assert, require *td.T) (bool, error)

in this case, both returned values are independent. Returning a false boolean means discontinuing the suite while returning a non-nil error marks the test as having failed and logs the error. So:

Returning       do...
(false, nil)    continue the suite, do not log anything
(false, ERROR)  continue the suite, marks the test as failed & log ERROR
(true, nil)     discontinue the suite & log the discontinuation
(true, ERROR)   discontinue the suite & log the discontinuation, marks the
                test as failed & log ERROR

Test methods are run in lexicographic order.

Very simple tests suite

Used typically to group tests and benefit from already instanciated *td.T instances.

import (
  "testing"

  "github.com/maxatome/go-testdeep/td"
  "github.com/maxatome/go-testdeep/helpers/tdsuite"
)

type MySuite struct{}

func (s MySuite) TestDB(assert, require *td.T) {
  db, err := initDB()
  require.CmpNoError(err)
  assert.CmpNoError(db.Ping())
}

func (s MySuite) TestPerson(assert *td.T) {
  person := Getperson("Bob")
  assert.Cmp(person, Person{Name: "Bob", Age: 44})
}

// TestMySuite is the go test entry point.
func TestMySuite(t *testing.T) {
  tdsuite.Run(t, MySuite{})
}

Suite setup and other hooks

In most cases, a suite is used for sharing information between tests. The type of the suite can implement several methods that are called before, after and/or between tests.

type SuiteDB struct{
  DB *sql.DB
}

// Setup is called once before any test runs.
func (s *SuiteDB) Setup(t *td.T) error {
  db, err := sql.Open(driver, dataSourceName)
  s.DB = db
  return err // automatically logged + failure if non-nil
}

// Destroy is called after all tests are run.
// Destroy is not called if Setup returned an error.
func (s *SuiteDB) Destroy(t *td.T) error {
  return s.DB.Close() // automatically logged + failure if non-nil
}

func (s *SuiteDB) TestPerson(assert, require *td.T) {
  person, err := GetPerson(s.DB, "Bob")
  require.CmpNoError(err)
  assert.Cmp(person, Person{Name: "Bob", Age: 44})
}

// TestMySuite is the go test entry point.
func TestSuiteDB(t *testing.T) {
  tdsuite.Run(t, &SuiteDB{})
}

See documentation below for other possible hooks: PreTest, PostTest and BetweenTests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run

func Run(tb testing.TB, suite interface{}, config ...td.ContextConfig) bool

Run runs the tests suite "suite" using "tb" as base testing framework. "tb" is typically a *testing.T as in:

func TestSuite(t *testing.T) {
  tdsuite.Run(t, &Suite{})
}

but it can also be a *td.T of course.

"config" can be used to alter the internal *td.T instance. See https://pkg.go.dev/github.com/maxatome/go-testdeep/td#ContextConfig for detailed options, as:

func TestSuite(t *testing.T) {
  tdsuite.Run(t, &Suite{}, td.ContextConfig{
    UseEqual: true, // use the Equal method to compare if available
    BeLax:    true, // able to compare different but convertible types
  })
}

Run returns true if all the tests succeeded, false otherwise.

Note that if "suite" is not empty struct, it should probably be a pointer, and so the hooks and tests should have a pointer receiver.

Types

type BetweenTests

type BetweenTests interface {
	BetweenTests(t *td.T, previousTestName, nextTestName string) error
}

BetweenTests is an interface a tests suite can implement. BetweenTests method is called between 2 tests. If it returns an error, the tests suite aborts: no more tests are run.

type Destroy

type Destroy interface {
	Destroy(t *td.T) error
}

Destroy is an interface a tests suite can implement. When running the tests suite, Destroy method is called once after all tests ran. If Setup interface is implemented and Setup method returned an error, Destroy is never called.

type PostTest

type PostTest interface {
	PostTest(t *td.T, testName string) error
}

PostTest is an interface a tests suite can implement. PostTest method is called after each test is run, in the same subtest as the test itself. If PreTest interface is implemented and PreTest method returned an error, PostTest is never called.

type PreTest

type PreTest interface {
	PreTest(t *td.T, testName string) error
}

PreTest is an interface a tests suite can implement. PreTest method is called before each test is run, in the same subtest as the test itself. If PreTest returns an error, the subtest aborts: the test is not run.

Starting go1.14, t.Cleanup() can be called in PreTest method. It can replace the definition of a PostTest method. It can also be used together, in this case cleanup registered functions are called after PostTest.

type Setup

type Setup interface {
	Setup(t *td.T) error
}

Setup is an interface a tests suite can implement. When running the tests suite, Setup method is called once before any test runs. If Setup returns an error, the tests suite aborts: no tests are run.

Starting go1.14, t.Cleanup() can be called in Setup method. It can replace the definition of a Destroy method. It can also be used together, in this case cleanup registered functions are called after Destroy.

Source Files