1
package spec
2

3
import (
4
	"io"
5
	"testing"
6
)
7

8
// An Option controls the behavior of a suite, group, or spec.
9
// Options are inherited by subgroups and subspecs.
10
//
11
// Example:
12
// If the top-level Run group is specified as Random(), each subgroup will
13
// inherit the Random() order. This means that each group will be randomized
14
// individually, unless another ordering is specified on any of the subgroups.
15
// If the Run group is also passed Global(), then all specs inside Run will run
16
// in completely random order, regardless of any ordering specified on the
17
// subgroups.
18
type Option func(*config)
19

20
// Report specifies a Reporter for a suite.
21
//
22
// Valid Option for:
23
// New, Run, Focus, Pend
24
func Report(r Reporter) Option {
25
	return func(c *config) {
26
		c.report = r
27
	}
28
}
29

30
// Seed specifies the random seed used for any randomized specs in a Run block.
31
// The random seed is always displayed before specs are run.
32
// If not specified, the current time is used.
33
//
34
// Valid Option for:
35
// New, Run, Focus, Pend
36
func Seed(s int64) Option {
37
	return func(c *config) {
38
		c.seed = s
39
	}
40
}
41

42
// Sequential indicates that a group of specs should be run in order.
43
// This is the default behavior.
44
//
45
// Valid Option for:
46
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
47
func Sequential() Option {
48
	return func(c *config) {
49
		c.order = orderSequential
50
	}
51
}
52

53
// Random indicates that a group of specs should be run in random order.
54
// Randomization is per group, such that all groupings are maintained.
55
//
56
// Valid Option for:
57
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
58
func Random() Option {
59
	return func(c *config) {
60
		c.order = orderRandom
61
	}
62
}
63

64
// Reverse indicates that a group of specs should be run in reverse order.
65
//
66
// Valid Option for:
67
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
68
func Reverse() Option {
69
	return func(c *config) {
70
		c.order = orderReverse
71
	}
72
}
73

74
// Parallel indicates that a spec or group of specs should be run in parallel.
75
// This Option is equivalent to t.Parallel().
76
//
77
// Valid Option for:
78
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend, S
79
func Parallel() Option {
80
	return func(c *config) {
81
		c.order = orderParallel
82
	}
83
}
84

85
// Local indicates that the test order applies to each subgroup individually.
86
// For example, a group with Random() and Local() will run all subgroups and
87
// specs in random order, and each subgroup will be randomized, but specs in
88
// different subgroups will not be interleaved.
89
// This is the default behavior.
90
//
91
// Valid Option for:
92
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
93
func Local() Option {
94
	return func(c *config) {
95
		c.scope = scopeLocal
96
	}
97
}
98

99
// Global indicates that test order applies globally to all descendant specs.
100
// For example, a group with Random() and Global() will run all descendant
101
// specs in random order, regardless of subgroup. Specs in different subgroups
102
// may be interleaved.
103
//
104
// Valid Option for:
105
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
106
func Global() Option {
107
	return func(c *config) {
108
		c.scope = scopeGlobal
109
	}
110
}
111

112
// Flat indicates that a parent subtest should not be created for the group.
113
// This is the default behavior.
114
//
115
// Valid Option for:
116
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
117
func Flat() Option {
118
	return func(c *config) {
119
		c.nest = nestOff
120
	}
121
}
122

123
// Nested indicates that a parent subtest should be created for the group.
124
// This allows for more control over parallelism.
125
//
126
// Valid Option for:
127
// New, Run, Focus, Pend, Suite, Suite.Focus, Suite.Pend, G, G.Focus, G.Pend
128
func Nested() Option {
129
	return func(c *config) {
130
		c.nest = nestOn
131
	}
132
}
133

134
type order int
135

136
const (
137
	orderInherit order = iota
138
	orderSequential
139
	orderParallel
140
	orderRandom
141
	orderReverse
142
)
143

144
func (o order) or(last order) order {
145
	return order(defaultZero(int(o), int(last)))
146
}
147

148
type scope int
149

150
const (
151
	scopeInherit scope = iota
152
	scopeLocal
153
	scopeGlobal
154
)
155

156
func (s scope) or(last scope) scope {
157
	return scope(defaultZero(int(s), int(last)))
158
}
159

160
type nest int
161

162
const (
163
	nestInherit nest = iota
164
	nestOff
165
	nestOn
166
)
167

168
func (n nest) or(last nest) nest {
169
	return nest(defaultZero(int(n), int(last)))
170
}
171

172
func defaultZero(next, last int) int {
173
	if next == 0 {
174
		return last
175
	}
176
	return next
177
}
178

179
func defaultZero64(next, last int64) int64 {
180
	if next == 0 {
181
		return last
182
	}
183
	return next
184
}
185

186
type config struct {
187
	seed   int64
188
	order  order
189
	scope  scope
190
	nest   nest
191
	pend   bool
192
	focus  bool
193
	before bool
194
	after  bool
195
	t      *testing.T
196
	out    func(io.Writer)
197
	report Reporter
198
}
199

200
type options []Option
201

202
func (o options) apply() *config {
203
	cfg := &config{}
204
	for _, opt := range o {
205
		opt(cfg)
206
	}
207
	return cfg
208
}
209

210