odize

README

odize

Testing, supercharged! odize is a lightweight wrapper over the standard testing lib that enables some additional features.

Motivation

Bringing the JS ecosystem to golang! Jokes aside, I wanted to remove boilerplate code from the tests while still using the core testing library. Heavy inspiration from vitest and jest, odize aims to be a light weight, easy to use test framework on top of the standard library.

The golang testing standard lib is more than capable for most cases, it's preferable to default to the standard lib where possible.

If what you're working on needs to be able to filter tests by tag, have more granular setup / teardown code, please consider odize.

Features

Feature	Description
Powered by std lib	Lightweight wrapper over the standard testing library, easy plug and play, no need to update your test commands.
Lifecycle hooks	Have granular control in the setup / teardown tests with helper functions: BeforeAll, BeforeEach, AfterEach, AfterAll
Test filtering	Run a subset of tests based off either group tags, or via test options.
Assertions	Built in core assertions AssertEqual, AssertTrue, AssertFalse, AssertNoError, AssertError, AssertNil

Basic usage

Install

go get github.com/code-gorilla-au/odize@latest

Create your group

Create a test group

// Note you can add test tags to filter tests
func TestScenarioOne(t *testing.T) {
	group := odize.NewGroup(t, nil)

	seedAge := 1
	var user UserEntity

	group.BeforeEach(func() {
		seedAge++
		user = UserEntity{
			Name: "John",
			Age:  seedAge,
		}
	})

	err := group.
		Test("user age should equal 2", func(t *testing.T) {
			AssertEqual(t, 2, user.Age)
		}).
		Test("user age should equal 3", func(t *testing.T) {
			AssertEqual(t, 3, user.Age)
		}).
		Test("user age should equal 4", func(t *testing.T) {
			AssertEqual(t, 4, user.Age)
		}).
		Test("user age should equal 5", func(t *testing.T) {
			AssertEqual(t, 5, user.Age)
		}).
		Test("user age should equal 6", func(t *testing.T) {
			AssertEqual(t, 6, user.Age)
		}).
		Run()

	AssertNoError(t, err)

}

Run test

Run the test command with your normal flags

go test --short -cover -v -failfast ./...

Terminal output

go test -v --short -cover -failfast ./...
=== RUN   TestDecorateBlock
=== RUN   TestDecorateBlock/should_contain_label
=== RUN   TestDecorateBlock/should_contain_content
=== RUN   TestDecorateBlock/should_contain_line_decorator
--- PASS: TestDecorateBlock (0.00s)
    --- PASS: TestDecorateBlock/should_contain_label (0.00s)
    --- PASS: TestDecorateBlock/should_contain_content (0.00s)
    --- PASS: TestDecorateBlock/should_contain

Lifecycle hooks

Odize has helper functions that help provide granular setup / teardown helpers for each test within the group.

Hook	Description
BeforeAll	Invoke before all tests within a group
BeforeEach	Invoke before each test within a group
AfterEach	Invoke after each test within a group
AfterAll	Invoke after all tests within a group

Test options

Optionally, you are able to provide some test options to a test within a group. This provides fine grain control over the test group, especially when you need to isolate a singular test within a group to debug.

Option	Description
Skip	Skip specified test
Only	Within the test group, only run the specified test

Providing options to a test

Skip example

func TestSkipExample(t *testing.T) {
	group := odize.NewGroup(t, nil)

	err := group.
		Test("should equal 2", func(t *testing.T) {
			result := add(1,1)
			AssertEqual(t, 2, result)
		}).
		Test("should equal 4", func(t *testing.T) {
			result := add(2,2)
			AssertEqual(t, 4, result)
		}).
		Test("should equal 3", func(t *testing.T) {
			// Note this test will be skipped
			result := add(1,2)
			AssertEqual(t, 3, result)
		}, Skip()).
		Run(t)

	AssertNoError(t, err)
}

func TestOnlyExample(t *testing.T) {
	group := odize.NewGroup(t, nil)

	err := group.
		Test("should equal 2", func(t *testing.T) {
			result := add(1,1)
			AssertEqual(t, 2, result)
		}).
		Test("should equal 3", func(t *testing.T) {
			// Note, only this test will be run within this group
			result := add(1,2)
			AssertEqual(t, 3, result)
		}, Only()).
		Run(t)

	AssertNoError(t, err)
}

Filtering tests

Provide the specific environment variable with values ODIZE_TAGS="unit".

Multiple tags can be passed with a comma , delimiter ODIZE_TAGS="unit,system"

Create group

create filtered group

func TestScenarioTwo(t *testing.T) {
	group := odize.NewGroup(t, &[]string{"integration"})

/** omit rest of the code **/
}

Run test

# only run unit tests
ODIZE_TAGS="unit" go test --short -v -cover  -failfast ./... 

=== RUN   TestSkipGroup
    unit_test.go:159: Skipping test group  TestSkipGroup
--- SKIP: TestSkipGroup (0.00s)

Examples

See examples provided for more details.

Documentation

Overview

Package odize lightweight wrapper over the standard testing lib that enables some additional features such as tagging and test lifecycle hooks.

Index

• Constants
• Variables
• func AssertEqual(t *testing.T, expected any, actual any)
• func AssertError(t *testing.T, err error)
• func AssertFalse(t *testing.T, value bool)
• func AssertNil(t *testing.T, value any)
• func AssertNoError(t *testing.T, err error)
• func AssertTrue(t *testing.T, value bool)
• type ErrorList
  • func (e *ErrorList) Append(err error)
  • func (e *ErrorList) Error() string
  • func (e *ErrorList) Len() int
  • func (e *ErrorList) Pop() error
  • func (e *ErrorList) Unwrap() []error
• type TestFn
• type TestFuncOpts
  • func Only() TestFuncOpts
  • func Skip() TestFuncOpts
• type TestGroup
  • func NewGroup(t *testing.T, tags *[]string) *TestGroup
  • func (tg *TestGroup) AfterAll(fn func())
  • func (tg *TestGroup) AfterEach(fn func())
  • func (tg *TestGroup) BeforeAll(fn func())
  • func (tg *TestGroup) BeforeEach(fn func())
  • func (tg *TestGroup) Run() error
  • func (tg *TestGroup) Test(name string, testFn TestFn, options ...TestFuncOpts) *TestGroup
• type TestOpts
• type TestRegistryEntry

Constants

const (
	// ODIZE_TAGS is the environment variable that is used to filter tests
	ODIZE_TAGS = "ODIZE_TAGS"
	// ENV variable declared in pipelines such as Github Actions
	ENV_CI = "CI"
)

Variables

var (
	ErrTestOptionNotAllowedInCI = fmt.Errorf("test option 'Only' not allowed in CI environment")
)

Functions

func AssertEqual

func AssertEqual(t *testing.T, expected any, actual any)

AssertEqual checks if two values are equal

Example:

AssertEqual(t, "a", "b")

func AssertError

func AssertError(t *testing.T, err error)

AssertError checks if error is not nil

Example:

AssertError(t, err)

func AssertFalse

func AssertFalse(t *testing.T, value bool)

AssertFalse checks if value is true

Example:

AssertFalse(t, methodReturnsFalse())

func AssertNil

func AssertNil(t *testing.T, value any)

Assert value is nil

Example:

AssertNil(t, myValue)

func AssertNoError

func AssertNoError(t *testing.T, err error)

AssertNoError checks if error is nil

Example:

AssertNoError(t, err)

func AssertTrue

func AssertTrue(t *testing.T, value bool)

AssertTrue checks if value is true

Example:

AssertTrue(t, methodReturnsTrue())

Types

type ErrorList

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

ErrorList - keep track of a number of errors

func (*ErrorList) Append

func (e *ErrorList) Append(err error)

Append - append error to list

func (*ErrorList) Error

func (e *ErrorList) Error() string

Error - return error string

func (*ErrorList) Len

func (e *ErrorList) Len() int

func (*ErrorList) Pop

func (e *ErrorList) Pop() error

Pop - remove the first error from the list and return

func (*ErrorList) Unwrap

func (e *ErrorList) Unwrap() []error

Unwrap - returns list of errors

type TestFn

type TestFn = func(t *testing.T)

TestFn - Test function

type TestFuncOpts

type TestFuncOpts = func(*TestOpts)

func Only

func Only() TestFuncOpts

Only - Only run this test. If multiple tests are marked as only, the group will run only the tests marked as only

func Skip

func Skip() TestFuncOpts

Skip - Skip this test

type TestGroup

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

TestGroup - Group tests together, contains lifecycle context.

func NewGroup

func NewGroup(t *testing.T, tags *[]string) *TestGroup

NewGroup - Create a new test group.

If t he ODIZE_TAGS environment variable is set, then only tests with matching tags will be run.

func (*TestGroup) AfterAll

func (tg *TestGroup) AfterAll(fn func())

AfterAll - Run after all tests

func (*TestGroup) AfterEach

func (tg *TestGroup) AfterEach(fn func())

AfterEach - Run after each test

func (*TestGroup) BeforeAll

func (tg *TestGroup) BeforeAll(fn func())

BeforeAll - Run before all tests

func (*TestGroup) BeforeEach

func (tg *TestGroup) BeforeEach(fn func())

BeforeEach - Run before each test

func (*TestGroup) Run

func (tg *TestGroup) Run() error

Run - Run all tests within a group.If the ODIZE_TAGS environment variable is set, then only tests with matching tags will be run.

If errors are encountered, tests will not run.

func (*TestGroup) Test

func (tg *TestGroup) Test(name string, testFn TestFn, options ...TestFuncOpts) *TestGroup

Test - Add a test to the group

type TestOpts

type TestOpts struct {
	Only bool
	Skip bool
}

TestOpts - Test options for granular control over each test

type TestRegistryEntry

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

TestRegistryEntry - Test name and function to execute on run