ensuring

Documentation

Overview

Package ensuring contains the implementation for the ensure test framework.

It is in a separate package from ensure to allow shadowing the ensure package without losing access to the types. Use [ensure.New] to create a new instance of Ensure.

Index

• type Chain
  • func (c *Chain) Contains(expected interface{})
  • func (c *Chain) DoesNotContain(expected interface{})
  • func (c *Chain) Equals(expected interface{})
  • func (c *Chain) IsEmpty()
  • func (c *Chain) IsError(expected error)
  • func (c *Chain) IsFalse()
  • func (c *Chain) IsNil()
  • func (c *Chain) IsNotEmpty()
  • func (c *Chain) IsNotError()
  • func (c *Chain) IsNotNil()
  • func (c *Chain) IsTrue()
  • func (c *Chain) MatchesAllErrors(expectedErrors ...error)
  • func (c *Chain) MatchesRegexp(pattern string)
• type E
  • func InternalCreateDoNotCallDirectly(t T) E
  • func (e E) Failf(format string, args ...interface{})
  • func (e E) GoMockController() *gomock.Controller
  • func (e E) InterfaceT() T
  • func (e E) New(t T) E
  • func (e E) Run(name string, fn func(ensure E))
  • func (e E) RunParallel(name string, fn func(ensure E))
  • func (e E) RunTableByIndex(table interface{}, fn func(ensure E, i int))
  • func (e E) T() *testing.T
• type T

Types

type Chain

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

Chain chains assertions to the ensure function call.

func (*Chain) Contains

func (c *Chain) Contains(expected interface{})

Contains ensures that the actual value contains the expected value. It only supports searching strings, arrays, or slices for the expected value. If both the actual and expected are strings, strings.Contains(...) is used.

For example:

ensure("abc").Contains("b") // Succeeds
ensure("abc").Contains("z") // Fails

ensure([]string{"abc", "xyz"}).Contains("xyz") // Succeeds
ensure([]string{"abc", "xyz"}).Contains("y") // Fails

func (*Chain) DoesNotContain

func (c *Chain) DoesNotContain(expected interface{})

DoesNotContain ensures that the actual value does not contain the expected value. It only supports verifying that strings, arrays, or slices do not contain the expected value. If both the actual and expected are strings, strings.Contains(...) is used.

For example:

ensure("abc").DoesNotContain("b") // Fails
ensure("abc").DoesNotContain("z") // Succeeds

ensure([]string{"abc", "xyz"}).DoesNotContain("xyz") // Fails
ensure([]string{"abc", "xyz"}).DoesNotContain("y") // Succeeds

func (*Chain) Equals

func (c *Chain) Equals(expected interface{})

Equals ensures the actual value equals the expected value. Equals uses deep.Equal to print easy to read diffs.

func (*Chain) IsEmpty

func (c *Chain) IsEmpty()

IsEmpty ensures that the actual value is empty. It only supports arrays, slices, strings, or maps.

func (*Chain) IsError

func (c *Chain) IsError(expected error)

IsError ensures the actual value equals the expected error. IsError uses errors.Is to support Go 1.13+ error comparisons.

func (*Chain) IsFalse

func (c *Chain) IsFalse()

IsFalse ensures the actual value is the boolean "false".

func (*Chain) IsNil

func (c *Chain) IsNil()

IsNil ensures the actual value is nil or a nil pointer.

func (*Chain) IsNotEmpty

func (c *Chain) IsNotEmpty()

IsNotEmpty ensures that the actual value is not empty. It only supports arrays, slices, strings, or maps.

func (*Chain) IsNotError

func (c *Chain) IsNotError()

IsNotError ensures that the actual value is nil. It is analogous to IsError(nil).

func (*Chain) IsNotNil

func (c *Chain) IsNotNil()

IsNotNil ensures the actual value is not nil and not a nil pointer.

func (*Chain) IsTrue

func (c *Chain) IsTrue()

IsTrue ensures the actual value is the boolean "true".

func (*Chain) MatchesAllErrors

func (c *Chain) MatchesAllErrors(expectedErrors ...error)

MatchesAllErrors ensures the actual value is all of the expected errors. This is useful for validating various levels of a wrapped error.

If no errors are provided, this method assumes no error is expected.

MatchesAllErrors uses errors.Is with each expected error to support Go 1.13+ error comparisons.

func (*Chain) MatchesRegexp

func (c *Chain) MatchesRegexp(pattern string)

MatchesRegexp ensures that the actual value matches the regular expression pattern provided. It only supports strings as actual values.

type E

type E func(actual interface{}) *Chain

E ensures the actual value is correct using Chain. E also has methods that can be called directly.

func InternalCreateDoNotCallDirectly

func InternalCreateDoNotCallDirectly(t T) E

InternalCreateDoNotCallDirectly should NOT be called directly. Instead use [ensure.New] (`ensure := ensure.New(t)`) to allow for easy test refactoring.

func (E) Failf

func (e E) Failf(format string, args ...interface{})

Failf fails the test immediately with a formatted message. The formatted message follows the same format as the fmt package.

func (E) GoMockController

func (e E) GoMockController() *gomock.Controller

GoMockController exposes a GoMock Controller scoped to the current test context. Learn more about GoMock here: https://github.com/golang/mock

func (E) InterfaceT

func (e E) InterfaceT() T

InterfaceT exposes the scoped T. Usually, E.T will be more useful, as it exposes the full testing.T. InterfaceT is intended for use when a non-testing.T type was provided to `ensure.New`, as in the case of mocking.

func (E) New

func (e E) New(t T) E

New creates an instance of ensure with the provided testing context.

This allows the `ensure` package to be shadowed by the `ensure` variable, while still allowing new instances of ensure to be created.

func (E) Run

func (e E) Run(name string, fn func(ensure E))

Run runs fn as a subtest called name, using testing.T.Run.

func (E) RunParallel

func (e E) RunParallel(name string, fn func(ensure E))

RunParallel runs fn as a subtest called name, using testing.T.Run. It calls testing.T.Parallel just before calling fn, causing fn to be run in parallel with (and only with) other parallel tests. See the testing.T.Parallel docs for more info.

func (E) RunTableByIndex

func (e E) RunTableByIndex(table interface{}, fn func(ensure E, i int))

RunTableByIndex runs the table which is a slice (or array) of structs. The struct must have a "Name" field which is a unique string describing each test. The fn is executed for each entry, with a scoped ensure instance and an index for an entry in the table.

For example:

table := []struct {
  Name    string
  Input   string
  IsEmpty bool
}{
  {
    Name:    "with non empty input",
    Input:   "my string",
    IsEmpty: false,
  },
  {
    Name:    "with empty input",
    Input:   "",
    IsEmpty: true,
  },
}

ensure.RunTableByIndex(table, func(ensure Ensure, i int) {
  entry := table[i]

  isEmpty := strs.IsEmpty(entry.Input)
  ensure(isEmpty).Equals(entry.IsEmpty)
})

Support for mocks is also included. Please see the README for an example.

func (E) T

func (e E) T() *testing.T

T exposes the scoped testing.T.

If an instance of *testing.T was not provided to ensure.New(t), this method cannot be used. The test will fail immediately.

type T

type T = testctx.T

T implements a subset of methods on testing.T. More methods may be added to T with a minor ensure release.