Codebase list golang-github-frankban-quicktest / a90278e
Include JSONEquals and CodecEquals in docs Francesco Banconi 4 years ago
2 changed file(s) with 75 addition(s) and 12 deletion(s). Raw diff Collapse all Expand all
+26
-10
checker.go less more
3737 }
3838
3939 // Equals is a Checker checking equality of two comparable values.
40 //
4041 // For instance:
4142 //
4243 // c.Assert(answer, qt.Equals, 42)
7475 // CmpEquals returns a Checker checking equality of two arbitrary values
7576 // according to the provided compare options. See DeepEquals as an example of
7677 // such a checker, commonly used when no compare options are required.
78 //
7779 // Example calls:
7880 //
7981 // c.Assert(list, qt.CmpEquals(cmpopts.SortSlices), []int{42, 47})
126128 // The comparison is done using the github.com/google/go-cmp/cmp package.
127129 // When comparing structs, by default no exported fields are allowed. CmpEquals
128130 // can be used when more customized compare options are required.
131 //
129132 // Example call:
130133 //
131134 // c.Assert(got, qt.DeepEquals, []int{42, 47})
141144
142145 // Matches is a Checker checking that the provided string or fmt.Stringer
143146 // matches the provided regular expression pattern.
147 //
144148 // For instance:
145149 //
146150 // c.Assert("these are the voyages", qt.Matches, "these are .*")
170174
171175 // ErrorMatches is a Checker checking that the provided value is an error whose
172176 // message matches the provided regular expression pattern.
177 //
173178 // For instance:
174179 //
175180 // c.Assert(err, qt.ErrorMatches, "bad wolf .*")
198203
199204 // PanicMatches is a Checker checking that the provided function panics with a
200205 // message matching the provided regular expression pattern.
206 //
201207 // For instance:
202208 //
203209 // c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, "bad wolf .*")
240246 }
241247
242248 // IsNil is a Checker checking that the provided value is nil.
249 //
243250 // For instance:
244251 //
245252 // c.Assert(got, qt.IsNil)
265272 }
266273
267274 // HasLen is a Checker checking that the provided value has the given length.
275 //
268276 // For instance:
269277 //
270278 // c.Assert([]int{42, 47}, qt.HasLen, 2)
303311 // Satisfies is a Checker checking that the provided value, when used as
304312 // argument of the provided predicate function, causes the function to return
305313 // true. The function must be of type func(T) bool, having got assignable to T.
314 //
306315 // For instance:
307316 //
308317 // // Check that an error from os.Open satisfies os.IsNotExist.
351360 }
352361
353362 // Not returns a Checker negating the given Checker.
363 //
354364 // For instance:
355365 //
356366 // c.Assert(got, qt.Not(qt.IsNil))
390400 //
391401 // For example:
392402 //
393 // c.Assert("hello world", qt.Contains, "world")
394 // c.Assert([]int{3,5,7,99}, qt.Contains, 7)
403 // c.Assert("hello world", qt.Contains, "world")
404 // c.Assert([]int{3,5,7,99}, qt.Contains, 7)
405 //
395406 var Contains Checker = &containsChecker{
396407 argNames: []string{"got", "want"},
397408 }
421432 //
422433 // For example:
423434 //
424 // c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
425 // c.Assert([][]string{{"a", "b"}, {"c", "d"}}, qt.Any(qt.DeepEquals), []string{"c", "d"})
435 // c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
436 // c.Assert([][]string{{"a", "b"}, {"c", "d"}}, qt.Any(qt.DeepEquals), []string{"c", "d"})
426437 //
427438 // See also All and Contains.
428439 func Any(c Checker) Checker {
472483 //
473484 // For example:
474485 //
475 // c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
476 // c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})
486 // c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
487 // c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})
477488 //
478489 // See also Any and Contains.
479490 func All(c Checker) Checker {
536547 //
537548 // It uses DeepEquals to do the comparison. If a more sophisticated
538549 // comparison is required, use CodecEquals directly.
550 //
551 // For instance:
552 //
553 // c.Assert(`{"First": 47.11}`, qt.JSONEquals, &MyStruct{First: 47.11})
554 //
539555 var JSONEquals = CodecEquals(json.Marshal, json.Unmarshal)
540556
541557 type codecEqualChecker struct {
547563
548564 // CodecEquals returns a checker that checks for codec value equivalence.
549565 //
550 // It expects two arguments: a byte slice or a string containing some codec-marshaled
551 // data, and a Go value.
566 // It expects two arguments: a byte slice or a string containing some
567 // codec-marshaled data, and a Go value.
552568 //
553569 // It uses unmarshal to unmarshal the data into an interface{} value.
554570 // It marshals the Go value using marshal, then unmarshals the result into
555571 // an interface{} value.
556572 //
557 // It then checks that the two interface{} values are deep-equal to one another,
558 // using CmpEquals(opts) to perform the check.
573 // It then checks that the two interface{} values are deep-equal to one
574 // another, using CmpEquals(opts) to perform the check.
559575 //
560576 // See JSONEquals for an example of this in use.
561577 func CodecEquals(
+49
-2
doc.go less more
7272 Equals
7373
7474 Equals checks that two values are equal, as compared with Go's == operator.
75
7576 For instance:
7677
7778 c.Assert(answer, qt.Equals, 42)
8687
8788 DeepEquals checks that two arbitrary values are deeply equal.
8889 The comparison is done using the github.com/google/go-cmp/cmp package.
89 When comparing structs, by default no exported fields are allowed. CmpEquals
90 (see below) can be used when more customized compare options are required.
90 When comparing structs, by default no exported fields are allowed.
91 If a more sophisticated comparison is required, use CmpEquals (see below).
92
9193 Example call:
9294
9395 c.Assert(got, qt.DeepEquals, []int{42, 47})
9799 CmpEquals checks equality of two arbitrary values according to the provided
98100 compare options. DeepEquals is more commonly used when no compare options are
99101 required.
102
100103 Example calls:
101104
102105 c.Assert(list, qt.CmpEquals(cmpopts.SortSlices), []int{42, 47})
106109
107110 Matches checks that a string or result of calling the String method
108111 (if the value implements fmt.Stringer) matches the provided regular expression.
112
109113 For instance:
110114
111115 c.Assert("these are the voyages", qt.Matches, `these are .*`)
115119
116120 ErrorMatches checks that the provided value is an error whose message matches
117121 the provided regular expression.
122
118123 For instance:
119124
120125 c.Assert(err, qt.ErrorMatches, `bad wolf .*`)
123128
124129 PanicMatches checks that the provided function panics with a message matching
125130 the provided regular expression.
131
126132 For instance:
127133
128134 c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, `bad wolf .*`)
130136 IsNil
131137
132138 IsNil checks that the provided value is nil.
139
133140 For instance:
134141
135142 c.Assert(got, qt.IsNil)
137144 HasLen
138145
139146 HasLen checks that the provided value has the given length.
147
140148 For instance:
141149
142150 c.Assert([]int{42, 47}, qt.HasLen, 2)
147155 Satisfies checks that the provided value, when used as argument of the provided
148156 predicate function, causes the function to return true. The function must be of
149157 type func(T) bool, having got assignable to T.
158
150159 For instance:
151160
152161 // Check that an error from os.Open satisfies os.IsNotExist.
158167 Not
159168
160169 Not returns a Checker negating the given Checker.
170
161171 For instance:
162172
163173 c.Assert(got, qt.Not(qt.IsNil))
169179 same as using Any(Equals), except that it has a special case for strings - if
170180 the first argument is a string, the second argument must also be a string and
171181 strings.Contains will be used.
182
172183 For example:
173184
174185 c.Assert("hello world", qt.Contains, "world")
178189
179190 Any returns a Checker that uses the given checker to check elements of a slice
180191 or array or the values from a map. It succeeds if any element passes the check.
192
181193 For example:
182194
183195 c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
190202 All returns a Checker that uses the given checker to check elements of slice or
191203 array or the values of a map. It succeeds if all elements pass the check.
192204 On failure it prints the error from the first index that failed.
205
193206 For example:
194207
195208 c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
196209 c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})
197210
198211 See also Any and Contains.
212
213 JSONEquals
214
215 JSONEquals checks whether a byte slice or string is JSON-equivalent to a Go
216 value. See CodecEquals for more information.
217
218 It uses DeepEquals to do the comparison. If a more sophisticated comparison is
219 required, use CodecEquals directly.
220
221 For instance:
222
223 c.Assert(`{"First": 47.11}`, qt.JSONEquals, &MyStruct{First: 47.11})
224
225 CodecEquals
226
227 CodecEquals returns a checker that checks for codec value equivalence.
228
229 func CodecEquals(
230 marshal func(interface{}) ([]byte, error),
231 unmarshal func([]byte, interface{}) error,
232 opts ...cmp.Option,
233 ) Checker
234
235 It expects two arguments: a byte slice or a string containing some
236 codec-marshaled data, and a Go value.
237
238 It uses unmarshal to unmarshal the data into an interface{} value.
239 It marshals the Go value using marshal, then unmarshals the result into
240 an interface{} value.
241
242 It then checks that the two interface{} values are deep-equal to one another,
243 using CmpEquals(opts) to perform the check.
244
245 See JSONEquals for an example of this in use.
199246 */
200247 package quicktest