1
package gomega
2

3
import (
4
	"fmt"
5
	"time"
6

7
	"github.com/google/go-cmp/cmp"
8
	"github.com/onsi/gomega/matchers"
9
	"github.com/onsi/gomega/types"
10
)
11

12
// Equal uses reflect.DeepEqual to compare actual with expected.  Equal is strict about
13
// types when performing comparisons.
14
// It is an error for both actual and expected to be nil.  Use BeNil() instead.
15
func Equal(expected any) types.GomegaMatcher {
16
	return &matchers.EqualMatcher{
17
		Expected: expected,
18
	}
19
}
20

21
// BeEquivalentTo is more lax than Equal, allowing equality between different types.
22
// This is done by converting actual to have the type of expected before
23
// attempting equality with reflect.DeepEqual.
24
// It is an error for actual and expected to be nil.  Use BeNil() instead.
25
func BeEquivalentTo(expected any) types.GomegaMatcher {
26
	return &matchers.BeEquivalentToMatcher{
27
		Expected: expected,
28
	}
29
}
30

31
// BeComparableTo uses gocmp.Equal from github.com/google/go-cmp (instead of reflect.DeepEqual) to perform a deep comparison.
32
// You can pass cmp.Option as options.
33
// It is an error for actual and expected to be nil.  Use BeNil() instead.
34
func BeComparableTo(expected any, opts ...cmp.Option) types.GomegaMatcher {
35
	return &matchers.BeComparableToMatcher{
36
		Expected: expected,
37
		Options:  opts,
38
	}
39
}
40

41
// BeIdenticalTo uses the == operator to compare actual with expected.
42
// BeIdenticalTo is strict about types when performing comparisons.
43
// It is an error for both actual and expected to be nil.  Use BeNil() instead.
44
func BeIdenticalTo(expected any) types.GomegaMatcher {
45
	return &matchers.BeIdenticalToMatcher{
46
		Expected: expected,
47
	}
48
}
49

50
// BeNil succeeds if actual is nil
51
func BeNil() types.GomegaMatcher {
52
	return &matchers.BeNilMatcher{}
53
}
54

55
// BeTrue succeeds if actual is true
56
//
57
// In general, it's better to use `BeTrueBecause(reason)` to provide a more useful error message if a true check fails.
58
func BeTrue() types.GomegaMatcher {
59
	return &matchers.BeTrueMatcher{}
60
}
61

62
// BeFalse succeeds if actual is false
63
//
64
// In general, it's better to use `BeFalseBecause(reason)` to provide a more useful error message if a false check fails.
65
func BeFalse() types.GomegaMatcher {
66
	return &matchers.BeFalseMatcher{}
67
}
68

69
// BeTrueBecause succeeds if actual is true and displays the provided reason if it is false
70
// fmt.Sprintf is used to render the reason
71
func BeTrueBecause(format string, args ...any) types.GomegaMatcher {
72
	return &matchers.BeTrueMatcher{Reason: fmt.Sprintf(format, args...)}
73
}
74

75
// BeFalseBecause succeeds if actual is false and displays the provided reason if it is true.
76
// fmt.Sprintf is used to render the reason
77
func BeFalseBecause(format string, args ...any) types.GomegaMatcher {
78
	return &matchers.BeFalseMatcher{Reason: fmt.Sprintf(format, args...)}
79
}
80

81
// HaveOccurred succeeds if actual is a non-nil error
82
// The typical Go error checking pattern looks like:
83
//
84
//	err := SomethingThatMightFail()
85
//	Expect(err).ShouldNot(HaveOccurred())
86
func HaveOccurred() types.GomegaMatcher {
87
	return &matchers.HaveOccurredMatcher{}
88
}
89

90
// Succeed passes if actual is a nil error
91
// Succeed is intended to be used with functions that return a single error value. Instead of
92
//
93
//	err := SomethingThatMightFail()
94
//	Expect(err).ShouldNot(HaveOccurred())
95
//
96
// You can write:
97
//
98
//	Expect(SomethingThatMightFail()).Should(Succeed())
99
//
100
// It is a mistake to use Succeed with a function that has multiple return values.  Gomega's Ω and Expect
101
// functions automatically trigger failure if any return values after the first return value are non-zero/non-nil.
102
// This means that Ω(MultiReturnFunc()).ShouldNot(Succeed()) can never pass.
103
func Succeed() types.GomegaMatcher {
104
	return &matchers.SucceedMatcher{}
105
}
106

107
// MatchError succeeds if actual is a non-nil error that matches the passed in
108
// string, error, function, or matcher.
109
//
110
// These are valid use-cases:
111
//
112
// When passed a string:
113
//
114
//	Expect(err).To(MatchError("an error"))
115
//
116
// asserts that err.Error() == "an error"
117
//
118
// When passed an error:
119
//
120
//	Expect(err).To(MatchError(SomeError))
121
//
122
// First checks if errors.Is(err, SomeError).
123
// If that fails then it checks if reflect.DeepEqual(err, SomeError) repeatedly for err and any errors wrapped by err
124
//
125
// When passed a matcher:
126
//
127
//	Expect(err).To(MatchError(ContainSubstring("sprocket not found")))
128
//
129
// the matcher is passed err.Error().  In this case it asserts that err.Error() contains substring "sprocket not found"
130
//
131
// When passed a func(err) bool and a description:
132
//
133
//	Expect(err).To(MatchError(os.IsNotExist, "IsNotExist"))
134
//
135
// the function is passed err and matches if the return value is true.  The description is required to allow Gomega
136
// to print a useful error message.
137
//
138
// It is an error for err to be nil or an object that does not implement the
139
// Error interface
140
//
141
// The optional second argument is a description of the error function, if used.  This is required when passing a function but is ignored in all other cases.
142
func MatchError(expected any, functionErrorDescription ...any) types.GomegaMatcher {
143
	return &matchers.MatchErrorMatcher{
144
		Expected:           expected,
145
		FuncErrDescription: functionErrorDescription,
146
	}
147
}
148

149
// BeClosed succeeds if actual is a closed channel.
150
// It is an error to pass a non-channel to BeClosed, it is also an error to pass nil
151
//
152
// In order to check whether or not the channel is closed, Gomega must try to read from the channel
153
// (even in the `ShouldNot(BeClosed())` case).  You should keep this in mind if you wish to make subsequent assertions about
154
// values coming down the channel.
155
//
156
// Also, if you are testing that a *buffered* channel is closed you must first read all values out of the channel before
157
// asserting that it is closed (it is not possible to detect that a buffered-channel has been closed until all its buffered values are read).
158
//
159
// Finally, as a corollary: it is an error to check whether or not a send-only channel is closed.
160
func BeClosed() types.GomegaMatcher {
161
	return &matchers.BeClosedMatcher{}
162
}
163

164
// Receive succeeds if there is a value to be received on actual.
165
// Actual must be a channel (and cannot be a send-only channel) -- anything else is an error.
166
//
167
// Receive returns immediately and never blocks:
168
//
169
// - If there is nothing on the channel `c` then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass.
170
//
171
// - If the channel `c` is closed then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass.
172
//
173
// - If there is something on the channel `c` ready to be read, then Expect(c).Should(Receive()) will pass and Ω(c).ShouldNot(Receive()) will fail.
174
//
175
// If you have a go-routine running in the background that will write to channel `c` you can:
176
//
177
//	Eventually(c).Should(Receive())
178
//
179
// This will timeout if nothing gets sent to `c` (you can modify the timeout interval as you normally do with `Eventually`)
180
//
181
// A similar use-case is to assert that no go-routine writes to a channel (for a period of time).  You can do this with `Consistently`:
182
//
183
//	Consistently(c).ShouldNot(Receive())
184
//
185
// You can pass `Receive` a matcher.  If you do so, it will match the received object against the matcher.  For example:
186
//
187
//	Expect(c).Should(Receive(Equal("foo")))
188
//
189
// When given a matcher, `Receive` will always fail if there is nothing to be received on the channel.
190
//
191
// Passing Receive a matcher is especially useful when paired with Eventually:
192
//
193
//	Eventually(c).Should(Receive(ContainSubstring("bar")))
194
//
195
// will repeatedly attempt to pull values out of `c` until a value matching "bar" is received.
196
//
197
// Furthermore, if you want to have a reference to the value *sent* to the channel you can pass the `Receive` matcher a pointer to a variable of the appropriate type:
198
//
199
//	var myThing thing
200
//	Eventually(thingChan).Should(Receive(&myThing))
201
//	Expect(myThing.Sprocket).Should(Equal("foo"))
202
//	Expect(myThing.IsValid()).Should(BeTrue())
203
//
204
// Finally, if you want to match the received object as well as get the actual received value into a variable, so you can reason further about the value received,
205
// you can pass a pointer to a variable of the appropriate type first, and second a matcher:
206
//
207
//	var myThing thing
208
//	Eventually(thingChan).Should(Receive(&myThing, ContainSubstring("bar")))
209
func Receive(args ...any) types.GomegaMatcher {
210
	return &matchers.ReceiveMatcher{
211
		Args: args,
212
	}
213
}
214

215
// BeSent succeeds if a value can be sent to actual.
216
// Actual must be a channel (and cannot be a receive-only channel) that can sent the type of the value passed into BeSent -- anything else is an error.
217
// In addition, actual must not be closed.
218
//
219
// BeSent never blocks:
220
//
221
// - If the channel `c` is not ready to receive then Expect(c).Should(BeSent("foo")) will fail immediately
222
// - If the channel `c` is eventually ready to receive then Eventually(c).Should(BeSent("foo")) will succeed.. presuming the channel becomes ready to receive  before Eventually's timeout
223
// - If the channel `c` is closed then Expect(c).Should(BeSent("foo")) and Ω(c).ShouldNot(BeSent("foo")) will both fail immediately
224
//
225
// Of course, the value is actually sent to the channel.  The point of `BeSent` is less to make an assertion about the availability of the channel (which is typically an implementation detail that your test should not be concerned with).
226
// Rather, the point of `BeSent` is to make it possible to easily and expressively write tests that can timeout on blocked channel sends.
227
func BeSent(arg any) types.GomegaMatcher {
228
	return &matchers.BeSentMatcher{
229
		Arg: arg,
230
	}
231
}
232

233
// MatchRegexp succeeds if actual is a string or stringer that matches the
234
// passed-in regexp.  Optional arguments can be provided to construct a regexp
235
// via fmt.Sprintf().
236
func MatchRegexp(regexp string, args ...any) types.GomegaMatcher {
237
	return &matchers.MatchRegexpMatcher{
238
		Regexp: regexp,
239
		Args:   args,
240
	}
241
}
242

243
// ContainSubstring succeeds if actual is a string or stringer that contains the
244
// passed-in substring.  Optional arguments can be provided to construct the substring
245
// via fmt.Sprintf().
246
func ContainSubstring(substr string, args ...any) types.GomegaMatcher {
247
	return &matchers.ContainSubstringMatcher{
248
		Substr: substr,
249
		Args:   args,
250
	}
251
}
252

253
// HavePrefix succeeds if actual is a string or stringer that contains the
254
// passed-in string as a prefix.  Optional arguments can be provided to construct
255
// via fmt.Sprintf().
256
func HavePrefix(prefix string, args ...any) types.GomegaMatcher {
257
	return &matchers.HavePrefixMatcher{
258
		Prefix: prefix,
259
		Args:   args,
260
	}
261
}
262

263
// HaveSuffix succeeds if actual is a string or stringer that contains the
264
// passed-in string as a suffix.  Optional arguments can be provided to construct
265
// via fmt.Sprintf().
266
func HaveSuffix(suffix string, args ...any) types.GomegaMatcher {
267
	return &matchers.HaveSuffixMatcher{
268
		Suffix: suffix,
269
		Args:   args,
270
	}
271
}
272

273
// MatchJSON succeeds if actual is a string or stringer of JSON that matches
274
// the expected JSON.  The JSONs are decoded and the resulting objects are compared via
275
// reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter.
276
func MatchJSON(json any) types.GomegaMatcher {
277
	return &matchers.MatchJSONMatcher{
278
		JSONToMatch: json,
279
	}
280
}
281

282
// MatchXML succeeds if actual is a string or stringer of XML that matches
283
// the expected XML.  The XMLs are decoded and the resulting objects are compared via
284
// reflect.DeepEqual so things like whitespaces shouldn't matter.
285
func MatchXML(xml any) types.GomegaMatcher {
286
	return &matchers.MatchXMLMatcher{
287
		XMLToMatch: xml,
288
	}
289
}
290

291
// MatchYAML succeeds if actual is a string or stringer of YAML that matches
292
// the expected YAML.  The YAML's are decoded and the resulting objects are compared via
293
// reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter.
294
func MatchYAML(yaml any) types.GomegaMatcher {
295
	return &matchers.MatchYAMLMatcher{
296
		YAMLToMatch: yaml,
297
	}
298
}
299

300
// BeEmpty succeeds if actual is empty.  Actual must be of type string, array, map, chan, or slice.
301
func BeEmpty() types.GomegaMatcher {
302
	return &matchers.BeEmptyMatcher{}
303
}
304

305
// HaveLen succeeds if actual has the passed-in length.  Actual must be of type string, array, map, chan, or slice.
306
func HaveLen(count int) types.GomegaMatcher {
307
	return &matchers.HaveLenMatcher{
308
		Count: count,
309
	}
310
}
311

312
// HaveCap succeeds if actual has the passed-in capacity.  Actual must be of type array, chan, or slice.
313
func HaveCap(count int) types.GomegaMatcher {
314
	return &matchers.HaveCapMatcher{
315
		Count: count,
316
	}
317
}
318

319
// BeZero succeeds if actual is the zero value for its type or if actual is nil.
320
func BeZero() types.GomegaMatcher {
321
	return &matchers.BeZeroMatcher{}
322
}
323

324
// ContainElement succeeds if actual contains the passed in element. By default
325
// ContainElement() uses Equal() to perform the match, however a matcher can be
326
// passed in instead:
327
//
328
//	Expect([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubstring("Bar")))
329
//
330
// Actual must be an array, slice or map. For maps, ContainElement searches
331
// through the map's values.
332
//
333
// If you want to have a copy of the matching element(s) found you can pass a
334
// pointer to a variable of the appropriate type. If the variable isn't a slice
335
// or map, then exactly one match will be expected and returned. If the variable
336
// is a slice or map, then at least one match is expected and all matches will be
337
// stored in the variable.
338
//
339
//	var findings []string
340
//	Expect([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubString("Bar", &findings)))
341
func ContainElement(element any, result ...any) types.GomegaMatcher {
342
	return &matchers.ContainElementMatcher{
343
		Element: element,
344
		Result:  result,
345
	}
346
}
347

348
// BeElementOf succeeds if actual is contained in the passed in elements.
349
// BeElementOf() always uses Equal() to perform the match.
350
// When the passed in elements are comprised of a single element that is either an Array or Slice, BeElementOf() behaves
351
// as the reverse of ContainElement() that operates with Equal() to perform the match.
352
//
353
//	Expect(2).Should(BeElementOf([]int{1, 2}))
354
//	Expect(2).Should(BeElementOf([2]int{1, 2}))
355
//
356
// Otherwise, BeElementOf() provides a syntactic sugar for Or(Equal(_), Equal(_), ...):
357
//
358
//	Expect(2).Should(BeElementOf(1, 2))
359
//
360
// Actual must be typed.
361
func BeElementOf(elements ...any) types.GomegaMatcher {
362
	return &matchers.BeElementOfMatcher{
363
		Elements: elements,
364
	}
365
}
366

367
// BeKeyOf succeeds if actual is contained in the keys of the passed in map.
368
// BeKeyOf() always uses Equal() to perform the match between actual and the map keys.
369
//
370
//	Expect("foo").Should(BeKeyOf(map[string]bool{"foo": true, "bar": false}))
371
func BeKeyOf(element any) types.GomegaMatcher {
372
	return &matchers.BeKeyOfMatcher{
373
		Map: element,
374
	}
375
}
376

377
// ConsistOf succeeds if actual contains precisely the elements passed into the matcher.  The ordering of the elements does not matter.
378
// By default ConsistOf() uses Equal() to match the elements, however custom matchers can be passed in instead.  Here are some examples:
379
//
380
//	Expect([]string{"Foo", "FooBar"}).Should(ConsistOf("FooBar", "Foo"))
381
//	Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Bar"), "Foo"))
382
//	Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Foo"), ContainSubstring("Foo")))
383
//
384
// Actual must be an array, slice or map.  For maps, ConsistOf matches against the map's values.
385
//
386
// You typically pass variadic arguments to ConsistOf (as in the examples above).  However, if you need to pass in a slice you can provided that it
387
// is the only element passed in to ConsistOf:
388
//
389
//	Expect([]string{"Foo", "FooBar"}).Should(ConsistOf([]string{"FooBar", "Foo"}))
390
//
391
// Note that Go's type system does not allow you to write this as ConsistOf([]string{"FooBar", "Foo"}...) as []string and []any are different types - hence the need for this special rule.
392
func ConsistOf(elements ...any) types.GomegaMatcher {
393
	return &matchers.ConsistOfMatcher{
394
		Elements: elements,
395
	}
396
}
397

398
// HaveExactElements succeeds if actual contains elements that precisely match the elements passed into the matcher. The ordering of the elements does matter.
399
// By default HaveExactElements() uses Equal() to match the elements, however custom matchers can be passed in instead.  Here are some examples:
400
//
401
//	Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements("Foo", "FooBar"))
402
//	Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements("Foo", ContainSubstring("Bar")))
403
//	Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements(ContainSubstring("Foo"), ContainSubstring("Foo")))
404
//
405
// Actual must be an array or slice.
406
func HaveExactElements(elements ...any) types.GomegaMatcher {
407
	return &matchers.HaveExactElementsMatcher{
408
		Elements: elements,
409
	}
410
}
411

412
// ContainElements succeeds if actual contains the passed in elements. The ordering of the elements does not matter.
413
// By default ContainElements() uses Equal() to match the elements, however custom matchers can be passed in instead. Here are some examples:
414
//
415
//	Expect([]string{"Foo", "FooBar"}).Should(ContainElements("FooBar"))
416
//	Expect([]string{"Foo", "FooBar"}).Should(ContainElements(ContainSubstring("Bar"), "Foo"))
417
//
418
// Actual must be an array, slice or map.
419
// For maps, ContainElements searches through the map's values.
420
func ContainElements(elements ...any) types.GomegaMatcher {
421
	return &matchers.ContainElementsMatcher{
422
		Elements: elements,
423
	}
424
}
425

426
// HaveEach succeeds if actual solely contains elements that match the passed in element.
427
// Please note that if actual is empty, HaveEach always will fail.
428
// By default HaveEach() uses Equal() to perform the match, however a
429
// matcher can be passed in instead:
430
//
431
//	Expect([]string{"Foo", "FooBar"}).Should(HaveEach(ContainSubstring("Foo")))
432
//
433
// Actual must be an array, slice or map.
434
// For maps, HaveEach searches through the map's values.
435
func HaveEach(element any) types.GomegaMatcher {
436
	return &matchers.HaveEachMatcher{
437
		Element: element,
438
	}
439
}
440

441
// HaveKey succeeds if actual is a map with the passed in key.
442
// By default HaveKey uses Equal() to perform the match, however a
443
// matcher can be passed in instead:
444
//
445
//	Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKey(MatchRegexp(`.+Foo$`)))
446
func HaveKey(key any) types.GomegaMatcher {
447
	return &matchers.HaveKeyMatcher{
448
		Key: key,
449
	}
450
}
451

452
// HaveKeyWithValue succeeds if actual is a map with the passed in key and value.
453
// By default HaveKeyWithValue uses Equal() to perform the match, however a
454
// matcher can be passed in instead:
455
//
456
//	Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue("Foo", "Bar"))
457
//	Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue(MatchRegexp(`.+Foo$`), "Bar"))
458
func HaveKeyWithValue(key any, value any) types.GomegaMatcher {
459
	return &matchers.HaveKeyWithValueMatcher{
460
		Key:   key,
461
		Value: value,
462
	}
463
}
464

465
// HaveField succeeds if actual is a struct and the value at the passed in field
466
// matches the passed in matcher.  By default HaveField used Equal() to perform the match,
467
// however a matcher can be passed in in stead.
468
//
469
// The field must be a string that resolves to the name of a field in the struct.  Structs can be traversed
470
// using the '.' delimiter.  If the field ends with '()' a method named field is assumed to exist on the struct and is invoked.
471
// Such methods must take no arguments and return a single value:
472
//
473
//	type Book struct {
474
//	    Title string
475
//	    Author Person
476
//	}
477
//	type Person struct {
478
//	    FirstName string
479
//	    LastName string
480
//	    DOB time.Time
481
//	}
482
//	Expect(book).To(HaveField("Title", "Les Miserables"))
483
//	Expect(book).To(HaveField("Title", ContainSubstring("Les"))
484
//	Expect(book).To(HaveField("Author.FirstName", Equal("Victor"))
485
//	Expect(book).To(HaveField("Author.DOB.Year()", BeNumerically("<", 1900))
486
func HaveField(field string, expected any) types.GomegaMatcher {
487
	return &matchers.HaveFieldMatcher{
488
		Field:    field,
489
		Expected: expected,
490
	}
491
}
492

493
// HaveExistingField succeeds if actual is a struct and the specified field
494
// exists.
495
//
496
// HaveExistingField can be combined with HaveField in order to cover use cases
497
// with optional fields. HaveField alone would trigger an error in such situations.
498
//
499
//	Expect(MrHarmless).NotTo(And(HaveExistingField("Title"), HaveField("Title", "Supervillain")))
500
func HaveExistingField(field string) types.GomegaMatcher {
501
	return &matchers.HaveExistingFieldMatcher{
502
		Field: field,
503
	}
504
}
505

506
// HaveValue applies the given matcher to the value of actual, optionally and
507
// repeatedly dereferencing pointers or taking the concrete value of interfaces.
508
// Thus, the matcher will always be applied to non-pointer and non-interface
509
// values only. HaveValue will fail with an error if a pointer or interface is
510
// nil. It will also fail for more than 31 pointer or interface dereferences to
511
// guard against mistakenly applying it to arbitrarily deep linked pointers.
512
//
513
// HaveValue differs from gstruct.PointTo in that it does not expect actual to
514
// be a pointer (as gstruct.PointTo does) but instead also accepts non-pointer
515
// and even interface values.
516
//
517
//	actual := 42
518
//	Expect(actual).To(HaveValue(42))
519
//	Expect(&actual).To(HaveValue(42))
520
func HaveValue(matcher types.GomegaMatcher) types.GomegaMatcher {
521
	return &matchers.HaveValueMatcher{
522
		Matcher: matcher,
523
	}
524
}
525

526
// BeNumerically performs numerical assertions in a type-agnostic way.
527
// Actual and expected should be numbers, though the specific type of
528
// number is irrelevant (float32, float64, uint8, etc...).
529
//
530
// There are six, self-explanatory, supported comparators:
531
//
532
//	Expect(1.0).Should(BeNumerically("==", 1))
533
//	Expect(1.0).Should(BeNumerically("~", 0.999, 0.01))
534
//	Expect(1.0).Should(BeNumerically(">", 0.9))
535
//	Expect(1.0).Should(BeNumerically(">=", 1.0))
536
//	Expect(1.0).Should(BeNumerically("<", 3))
537
//	Expect(1.0).Should(BeNumerically("<=", 1.0))
538
func BeNumerically(comparator string, compareTo ...any) types.GomegaMatcher {
539
	return &matchers.BeNumericallyMatcher{
540
		Comparator: comparator,
541
		CompareTo:  compareTo,
542
	}
543
}
544

545
// BeTemporally compares time.Time's like BeNumerically
546
// Actual and expected must be time.Time. The comparators are the same as for BeNumerically
547
//
548
//	Expect(time.Now()).Should(BeTemporally(">", time.Time{}))
549
//	Expect(time.Now()).Should(BeTemporally("~", time.Now(), time.Second))
550
func BeTemporally(comparator string, compareTo time.Time, threshold ...time.Duration) types.GomegaMatcher {
551
	return &matchers.BeTemporallyMatcher{
552
		Comparator: comparator,
553
		CompareTo:  compareTo,
554
		Threshold:  threshold,
555
	}
556
}
557

558
// BeAssignableToTypeOf succeeds if actual is assignable to the type of expected.
559
// It will return an error when one of the values is nil.
560
//
561
//	Expect(0).Should(BeAssignableToTypeOf(0))         // Same values
562
//	Expect(5).Should(BeAssignableToTypeOf(-1))        // different values same type
563
//	Expect("foo").Should(BeAssignableToTypeOf("bar")) // different values same type
564
//	Expect(struct{ Foo string }{}).Should(BeAssignableToTypeOf(struct{ Foo string }{}))
565
func BeAssignableToTypeOf(expected any) types.GomegaMatcher {
566
	return &matchers.AssignableToTypeOfMatcher{
567
		Expected: expected,
568
	}
569
}
570

571
// Panic succeeds if actual is a function that, when invoked, panics.
572
// Actual must be a function that takes no arguments and returns no results.
573
func Panic() types.GomegaMatcher {
574
	return &matchers.PanicMatcher{}
575
}
576

577
// PanicWith succeeds if actual is a function that, when invoked, panics with a specific value.
578
// Actual must be a function that takes no arguments and returns no results.
579
//
580
// By default PanicWith uses Equal() to perform the match, however a
581
// matcher can be passed in instead:
582
//
583
//	Expect(fn).Should(PanicWith(MatchRegexp(`.+Foo$`)))
584
func PanicWith(expected any) types.GomegaMatcher {
585
	return &matchers.PanicMatcher{Expected: expected}
586
}
587

588
// BeAnExistingFile succeeds if a file exists.
589
// Actual must be a string representing the abs path to the file being checked.
590
func BeAnExistingFile() types.GomegaMatcher {
591
	return &matchers.BeAnExistingFileMatcher{}
592
}
593

594
// BeARegularFile succeeds if a file exists and is a regular file.
595
// Actual must be a string representing the abs path to the file being checked.
596
func BeARegularFile() types.GomegaMatcher {
597
	return &matchers.BeARegularFileMatcher{}
598
}
599

600
// BeADirectory succeeds if a file exists and is a directory.
601
// Actual must be a string representing the abs path to the file being checked.
602
func BeADirectory() types.GomegaMatcher {
603
	return &matchers.BeADirectoryMatcher{}
604
}
605

606
// HaveHTTPStatus succeeds if the Status or StatusCode field of an HTTP response matches.
607
// Actual must be either a *http.Response or *httptest.ResponseRecorder.
608
// Expected must be either an int or a string.
609
//
610
//	Expect(resp).Should(HaveHTTPStatus(http.StatusOK))   // asserts that resp.StatusCode == 200
611
//	Expect(resp).Should(HaveHTTPStatus("404 Not Found")) // asserts that resp.Status == "404 Not Found"
612
//	Expect(resp).Should(HaveHTTPStatus(http.StatusOK, http.StatusNoContent))   // asserts that resp.StatusCode == 200 || resp.StatusCode == 204
613
func HaveHTTPStatus(expected ...any) types.GomegaMatcher {
614
	return &matchers.HaveHTTPStatusMatcher{Expected: expected}
615
}
616

617
// HaveHTTPHeaderWithValue succeeds if the header is found and the value matches.
618
// Actual must be either a *http.Response or *httptest.ResponseRecorder.
619
// Expected must be a string header name, followed by a header value which
620
// can be a string, or another matcher.
621
func HaveHTTPHeaderWithValue(header string, value any) types.GomegaMatcher {
622
	return &matchers.HaveHTTPHeaderWithValueMatcher{
623
		Header: header,
624
		Value:  value,
625
	}
626
}
627

628
// HaveHTTPBody matches if the body matches.
629
// Actual must be either a *http.Response or *httptest.ResponseRecorder.
630
// Expected must be either a string, []byte, or other matcher
631
func HaveHTTPBody(expected any) types.GomegaMatcher {
632
	return &matchers.HaveHTTPBodyMatcher{Expected: expected}
633
}
634

635
// And succeeds only if all of the given matchers succeed.
636
// The matchers are tried in order, and will fail-fast if one doesn't succeed.
637
//
638
//	Expect("hi").To(And(HaveLen(2), Equal("hi"))
639
//
640
// And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
641
func And(ms ...types.GomegaMatcher) types.GomegaMatcher {
642
	return &matchers.AndMatcher{Matchers: ms}
643
}
644

645
// SatisfyAll is an alias for And().
646
//
647
//	Expect("hi").Should(SatisfyAll(HaveLen(2), Equal("hi")))
648
func SatisfyAll(matchers ...types.GomegaMatcher) types.GomegaMatcher {
649
	return And(matchers...)
650
}
651

652
// Or succeeds if any of the given matchers succeed.
653
// The matchers are tried in order and will return immediately upon the first successful match.
654
//
655
//	Expect("hi").To(Or(HaveLen(3), HaveLen(2))
656
//
657
// And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
658
func Or(ms ...types.GomegaMatcher) types.GomegaMatcher {
659
	return &matchers.OrMatcher{Matchers: ms}
660
}
661

662
// SatisfyAny is an alias for Or().
663
//
664
//	Expect("hi").SatisfyAny(Or(HaveLen(3), HaveLen(2))
665
func SatisfyAny(matchers ...types.GomegaMatcher) types.GomegaMatcher {
666
	return Or(matchers...)
667
}
668

669
// Not negates the given matcher; it succeeds if the given matcher fails.
670
//
671
//	Expect(1).To(Not(Equal(2))
672
//
673
// And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
674
func Not(matcher types.GomegaMatcher) types.GomegaMatcher {
675
	return &matchers.NotMatcher{Matcher: matcher}
676
}
677

678
// WithTransform applies the `transform` to the actual value and matches it against `matcher`.
679
// The given transform must be either a function of one parameter that returns one value or a
680
// function of one parameter that returns two values, where the second value must be of the
681
// error type.
682
//
683
//	var plus1 = func(i int) int { return i + 1 }
684
//	Expect(1).To(WithTransform(plus1, Equal(2))
685
//
686
//	 var failingplus1 = func(i int) (int, error) { return 42, "this does not compute" }
687
//	 Expect(1).To(WithTransform(failingplus1, Equal(2)))
688
//
689
// And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
690
func WithTransform(transform any, matcher types.GomegaMatcher) types.GomegaMatcher {
691
	return matchers.NewWithTransformMatcher(transform, matcher)
692
}
693

694
// Satisfy matches the actual value against the `predicate` function.
695
// The given predicate must be a function of one parameter that returns bool.
696
//
697
//	var isEven = func(i int) bool { return i%2 == 0 }
698
//	Expect(2).To(Satisfy(isEven))
699
func Satisfy(predicate any) types.GomegaMatcher {
700
	return matchers.NewSatisfyMatcher(predicate)
701
}
702

703