README
¶
spec
Spec is a simple BDD test organizer for Go. It minimally extends the standard
library testing package by facilitating easy organization of Go 1.7+
subtests.
Spec differs from other BDD libraries for Go in that it:
- Does not reimplement or replace any functionality of the
testingpackage - Does not provide an alternative test parallelization strategy to the
testingpackage - Does not provide assertions
- Does not encourage the use of dot-imports
- Does not reuse any closures between test runs (to avoid test pollution)
- Does not use global state, excessive interface types, or reflection
Spec is intended for gophers who want to write BDD tests in idiomatic Go using
the standard library testing package. Spec aims to do "one thing right,"
and does not provide a wide DSL or any functionality outside of test
organization.
Features
- Clean, simple syntax
- Supports focusing and pending tests
- Supports sequential, random, reverse, and parallel test order
- Provides granular control over test order and subtest nesting
- Provides a test writer to manage test output
- Provides a generic, asynchronous reporting interface
- Provides multiple reporter implementations
Notes
- Use
go test -vto see individual subtests.
Examples
Most functionality is demonstrated here.
Quick example:
func TestObject(t *testing.T) {
spec.Run(t, "object", func(t *testing.T, when spec.G, it spec.S) {
var someObject *myapp.Object
it.Before(func() {
someObject = myapp.NewObject()
})
it.After(func() {
someObject.Close()
})
it("should have some default", func() {
if someObject.Default != "value" {
t.Error("bad default")
}
})
when("something happens", func() {
it.Before(func() {
someObject.Connect()
})
it("should do one thing", func() {
if err := someObject.DoThing(); err != nil {
t.Error(err)
}
})
it("should do another thing", func() {
if result := someObject.DoOtherThing(); result != "good result" {
t.Error("bad result")
}
})
}, spec.Random())
when("some slow things happen", func() {
it("should do one thing in parallel", func() {
if result := someObject.DoSlowThing(); result != "good result" {
t.Error("bad result")
}
})
it("should do another thing in parallel", func() {
if result := someObject.DoOtherSlowThing(); result != "good result" {
t.Error("bad result")
}
})
}, spec.Parallel())
}, spec.Report(report.Terminal{}))
}
With less nesting:
func TestObject(t *testing.T) {
spec.Run(t, "object", testObject)
}
func testObject(t *testing.T, when spec.G, it spec.S) {
var someObject myapp.Object
...
}
Documentation
¶
Index ¶
- func Focus(t *testing.T, text string, f func(*testing.T, G, S), opts ...Option) bool
- func Pend(t *testing.T, text string, f func(*testing.T, G, S), _ ...Option) bool
- func Run(t *testing.T, text string, f func(*testing.T, G, S), opts ...Option) bool
- type G
- type Option
- type Plan
- type Reporter
- type S
- type Spec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Focus ¶
Focus focuses every spec in the suite. This is useful as a shortcut for unfocusing all focused specs.
Valid Options: Sequential(), Random(), Reverse(), Parallel() Local(), Global(), Flat(), Nested()
Types ¶
type G ¶
G defines a group of specs. Unlike other testing libraries, it is re-evaluated for each subspec.
Valid Options: Sequential(), Random(), Reverse(), Parallel() Local(), Global(), Flat(), Nested()
type Option ¶
type Option func(*config)
An Option is used to control the behavior of a call to Run, G, or S. Options are inherited by subgroups and subspecs.
Example: If the top-level Run group is specified as Random(), each subgroup will inherit the Random() order. This means that each group will be randomized individually, unless another ordering is specified on any of the subgroups. If the Run group is also passed Global(), then all specs inside Run will run in completely random order, regardless of any ordering specified on the subgroups.
func Flat ¶
func Flat() Option
Flat indicates that a parent subtest should not be created for the group. This is the default behavior.
Valid Option for: Run, G
func Global ¶
func Global() Option
Global indicates that test order applies globally to all descendant specs. For example, a group with Random() and Global() will run all descendant specs in random order, regardless of subgroup. Specs in different subgroups may be interleaved.
Valid Option for: Run, G
func Local ¶
func Local() Option
Local indicates that the test order applies to each subgroup individually. For example, a group with Random() and Local() will run all subgroups and specs in random order, and each subgroup will be randomized, but specs in different subgroups will not be interleaved. This is the default behavior.
Valid Option for: Run, G
func Nested ¶
func Nested() Option
Nested indicates that a parent subtest should be created for the group. This allows for more control over parallelism.
Valid Option for: Run, G
func Parallel ¶
func Parallel() Option
Parallel indicates that a spec or group of specs should be run in parallel. This Option is equivalent to t.Parallel().
Valid Option for: Run, G, S
func Random ¶
func Random() Option
Random indicates that a group of specs should be run in random order. Randomization is per group, such that all groupings are maintained.
Valid Option for: Run, G
func Reverse ¶
func Reverse() Option
Reverse indicates that a group of specs should be run in reverse order.
Valid Option for: Run, G
func Seed ¶
Seed specifies the random seed used for any randomized specs in a Run block. The random seed is always displayed before specs are run. If not specified, the current time is used.
Valid Option for: Run
func Sequential ¶
func Sequential() Option
Sequential indicates that a group of specs should be run in order. This is the default behavior.
Valid Option for: Run, G
type Plan ¶
type Plan struct {
Text string
Total int
Pending int
Focused int
Seed int64
HasRandom bool
HasFocus bool
}
A Plan provides a Reporter with information about a suite.
type Reporter ¶
type Reporter interface {
// Start provides the Reporter with a Plan that describes the suite.
// No specs will run until the Start method call finishes.
Start(*testing.T, Plan)
// Specs provides the Reporter with a channel of Specs.
// The specs will start running concurrently with the Specs method call.
// The Run method will not complete until the Specs method call completes.
Specs(*testing.T, <-chan Spec)
}
A Reporter is provided with information about a suite as it runs.
type S ¶
S defines a spec.
Valid Options: Parallel()
func (S) Focus ¶
Focus skips all specs except the focused spec and other focused specs.
Valid Options: Parallel()
Source Files
Directories