subtest

Documentation

Overview

Package subtest provides a TestContext to subtests which handles cleanup, and provides a testing.TB, and context.Context.

This package was inspired by github.com/frankban/quicktest.

DEPRECATED

With the addition of T.Cleanup() in go1.14 this package provides very little value. A context.Context can be managed by tests that need it with little enough boilerplate that it doesn't make sense to wrap testing.T in a TestContext.

Index

• func Run(t *testing.T, name string, subtest func(t TestContext)) bool
• type TestContext

Examples

• Run (TableTest)
• Run (TestSuite)

Functions

func Run

func Run(t *testing.T, name string, subtest func(t TestContext)) bool

Run a subtest. When subtest exits, every cleanup function added with TestContext.AddCleanup will be run.

Example (TableTest)

package main

import (
	"io"
	"net/http"
	"strings"
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/x/subtest"
)

var t = &testing.T{}

func main() {
	var testcases = []struct {
		data     io.Reader
		expected int
	}{
		{
			data:     strings.NewReader("invalid input"),
			expected: 400,
		},
		{
			data:     strings.NewReader("valid input"),
			expected: 200,
		},
	}

	for _, tc := range testcases {
		subtest.Run(t, "test-service-call", func(t subtest.TestContext) {
			// startFakeService can shutdown using t.AddCleanup
			url := startFakeService(t)

			req, err := http.NewRequest("POST", url, tc.data)
			assert.NilError(t, err)
			req = req.WithContext(t.Ctx())

			client := newClient(t)
			resp, err := client.Do(req)
			assert.NilError(t, err)
			assert.Equal(t, resp.StatusCode, tc.expected)
		})
	}
}

func startFakeService(_ subtest.TestContext) string {
	return "url"
}

func newClient(_ subtest.TestContext) *http.Client {
	return &http.Client{}
}

Example (TestSuite)

package main

import (
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/x/subtest"
)

var t = &testing.T{}

func main() {
	// do suite setup before subtests

	subtest.Run(t, "test-one", func(t subtest.TestContext) {
		assert.Equal(t, 1, 1)
	})
	subtest.Run(t, "test-two", func(t subtest.TestContext) {
		assert.Equal(t, 2, 2)
	})

	// do suite teardown after subtests
}

Types

type TestContext

type TestContext interface {
	testing.TB
	// AddCleanup function which will be run when before Run returns.
	//
	// Deprecated: Go 1.14+ now includes a testing.TB.Cleanup(func()) which
	// should be used instead. AddCleanup will be removed in a future release.
	AddCleanup(f func())
	// Ctx returns a context for the test case. Multiple calls from the same subtest
	// will return the same context. The context is cancelled when Run
	// returns.
	Ctx() context.Context
	// Parallel calls t.Parallel on the testing.TB. Panics if testing.TB does
	// not implement Parallel.
	Parallel()
}

TestContext provides a testing.TB and a context.Context for a test case.