onpar

README

onpar

Parallel testing framework for Go

Assertions

OnPar provides built-in assertion mechanisms using Expect statement to make expectations. Here is some more information about Expect and some of the matchers that come with OnPar.

• Expect
• Matchers

Specs

Test assertions are done within a Spec() function. Each Spec has a name and a function. The function takes a testing.T as an argument and any output from a BeforeEach(). Each Spec is run in parallel (t.Parallel() is invoked for each spec before calling the given function).

func TestSpecs(t *testing.T) {
    o := onpar.New()
    defer o.Run(t)

    o.BeforeEach(func(t *testing.T) (*testing.T, int, float64) {
        return t, 99, 101.0
    })

    o.AfterEach(func(t *testing.T, a int, b float64) {
            // ...
    })

    o.Spec("something informative", func(t *testing.T, a int, b float64) {
        if a != 99 {
            t.Errorf("%d != 99", a)
        }
    })
}

Grouping

Groups are used to keep Specs in logical place. The intention is to gather each Spec in a reasonable place. Each Group can have a BeforeEach() and a AfterEach() but are not required to.

func TestGrouping(t *testing.T) {
    o := onpar.New()
    defer o.Run(t)

    o.BeforeEach(func(t *testing.T) (*testing.T, int, float64) {
        return t, 99, 101.0
    })

    o.Group("some-group", func() {
        o.BeforeEach(func(t *teting.T, a int, b float64) (*testing.T, string) {
            return t, "foo"
        })

        o.AfterEach(func(t *testing.T, s string) {
            // ...
        })

        o.Spec("something informative", func(t *testing.T, s string) {
            // ...
        })
    })
}

Run Order

Each BeforeEach() runs before any Spec in the same Group. It will also run before any sub-group Specs and their BeforeEaches. Any AfterEach() will run after the Spec and before parent AfterEaches.

func TestRunOrder(t *testing.T) {
    o := onpar.New()
    defer o.Run(t)

    o.BeforeEach(func(t *testing.T) (*testing.T, int, string) {
        // Spec "A": Order = 1
        // Spec "B": Order = 1
        // Spec "C": Order = 1
        return t, 99, "foo"
    })

    o.AfterEach(func(t *testing.T, i int, s string) {
        // Spec "A": Order = 4
        // Spec "B": Order = 6
        // Spec "C": Order = 6
    })

    o.Group("DA", func() {
        o.AfterEach(func(t *testing.T, i int, s string) {
            // Spec "A": Order = 3
            // Spec "B": Order = 5
            // Spec "C": Order = 5
        })

        o.Spec("A", func(t *testing.T, i int, s string) {
            // Spec "A": Order = 2
        })

        o.Group("DB", func() {
            o.BeforeEach(func(t *testing.T, i int, s string) (*testing.T, float64) {
                // Spec "B": Order = 2
                // Spec "C": Order = 2
                return t, 101
            })

            o.AfterEach(func(t *testing.T, f float64) {
                // Spec "B": Order = 4
                // Spec "C": Order = 4
            })

            o.Spec("B", func(t *testing.T, f float64) {
                // Spec "B": Order = 3
            })

            o.Spec("C", func(t *testing.T, f float64) {
                // Spec "C": Order = 3
            })
        })

        o.Group("DC", func() {
            o.BeforeEach(func(t *testing.T, i int, s string) *testing.T {
                // Will not be invoked
            })

            o.AfterEach(func(t *testing.T) {
                // Will not be invoked
            })
        })
    })
}

Avoiding Closure

Why bother with returning values from a BeforeEach? To avoid closure of course! When running Specs in parallel (which they always do), each variable needs a new instance to avoid race conditions. If you use closure, then this gets tough. So onpar will pass the arguments to the given function returned by the BeforeEach.

The BeforeEach is a gatekeeper for arguments. The returned values from BeforeEach are required for the following Specs. Child Groups are also passed what their direct parent BeforeEach returns.

Documentation

Index

• type Onpar
  • func New(opts ...Opt) *Onpar
  • func NewWithCallCount(count int) *Onpar
  • func (o *Onpar) AfterEach(f interface{})
  • func (o *Onpar) BeforeEach(f interface{})
  • func (o *Onpar) Group(name string, f func())
  • func (o *Onpar) Run(t *testing.T)
  • func (o *Onpar) Spec(name string, f interface{})
• type Opt
  • func WithCallCount(count int) Opt

Types

type Onpar

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

Onpar stores the state of the specs and groups

func New

func New(opts ...Opt) *Onpar

New creates a new Onpar test suite

func NewWithCallCount

func NewWithCallCount(count int) *Onpar

NewWithCallCount is deprecated syntax for New(WithCallCount(count))

func (*Onpar) AfterEach

func (o *Onpar) AfterEach(f interface{})

AfterEach is used to cleanup anything from the specs or BeforeEaches. The function takes arguments the same as specs. Inner AfterEaches are invoked before outer ones.

func (*Onpar) BeforeEach

func (o *Onpar) BeforeEach(f interface{})

BeforeEach is used for any setup that may be required for the specs. Each argument returned will be required to be received by following specs. Outer BeforeEaches are invoked before inner ones.

func (*Onpar) Group

func (o *Onpar) Group(name string, f func())

Group is used to gather and categorize specs. Each group can have a single `BeforeEach()` and `AfterEach()`.

func (*Onpar) Run

func (o *Onpar) Run(t *testing.T)

Run is used to initiate the tests.

func (*Onpar) Spec

func (o *Onpar) Spec(name string, f interface{})

Spec is a test that runs in parallel with other specs. The provided function takes the `testing.T` for test assertions and any arguments the `BeforeEach()` returns.

type Opt

type Opt func(Onpar) Onpar

Opt is an option type to pass to onpar's constructor.

func WithCallCount

func WithCallCount(count int) Opt

WithCallCount sets a call count to pass to runtime.Caller.