1
/*
2
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library.
3

4
The godoc documentation describes Gomega's API.  More comprehensive documentation (with examples!) is available at http://onsi.github.io/gomega/
5

6
Gomega on Github: http://github.com/onsi/gomega
7

8
Learn more about Ginkgo online: http://onsi.github.io/ginkgo
9

10
Ginkgo on Github: http://github.com/onsi/ginkgo
11

12
Gomega is MIT-Licensed
13
*/
14
package gomega
15

16
import (
17
	"errors"
18
	"fmt"
19
	"time"
20

21
	"github.com/onsi/gomega/internal"
22
	"github.com/onsi/gomega/types"
23
)
24

25
const GOMEGA_VERSION = "1.38.2"
26

27
const nilGomegaPanic = `You are trying to make an assertion, but haven't registered Gomega's fail handler.
28
If you're using Ginkgo then you probably forgot to put your assertion in an It().
29
Alternatively, you may have forgotten to register a fail handler with RegisterFailHandler() or RegisterTestingT().
30
Depending on your vendoring solution you may be inadvertently importing gomega and subpackages (e.g. ghhtp, gexec,...) from different locations.
31
`
32

33
// Gomega describes the essential Gomega DSL. This interface allows libraries
34
// to abstract between the standard package-level function implementations
35
// and alternatives like *WithT.
36
//
37
// The types in the top-level DSL have gotten a bit messy due to earlier deprecations that avoid stuttering
38
// and due to an accidental use of a concrete type (*WithT) in an earlier release.
39
//
40
// As of 1.15 both the WithT and Ginkgo variants of Gomega are implemented by the same underlying object
41
// however one (the Ginkgo variant) is exported as an interface (types.Gomega) whereas the other (the withT variant)
42
// is shared as a concrete type (*WithT, which is aliased to *internal.Gomega).  1.15 did not clean this mess up to ensure
43
// that declarations of *WithT in existing code are not broken by the upgrade to 1.15.
44
type Gomega = types.Gomega
45

46
// DefaultGomega supplies the standard package-level implementation
47
var Default = Gomega(internal.NewGomega(internal.FetchDefaultDurationBundle()))
48

49
// NewGomega returns an instance of Gomega wired into the passed-in fail handler.
50
// You generally don't need to use this when using Ginkgo - RegisterFailHandler will wire up the global gomega
51
// However creating a NewGomega with a custom fail handler can be useful in contexts where you want to use Gomega's
52
// rich ecosystem of matchers without causing a test to fail.  For example, to aggregate a series of potential failures
53
// or for use in a non-test setting.
54
func NewGomega(fail types.GomegaFailHandler) Gomega {
55
	return internal.NewGomega(internalGomega(Default).DurationBundle).ConfigureWithFailHandler(fail)
56
}
57

58
// WithT wraps a *testing.T and provides `Expect`, `Eventually`, and `Consistently` methods.  This allows you to leverage
59
// Gomega's rich ecosystem of matchers in standard `testing` test suites.
60
//
61
// Use `NewWithT` to instantiate a `WithT`
62
//
63
// As of 1.15 both the WithT and Ginkgo variants of Gomega are implemented by the same underlying object
64
// however one (the Ginkgo variant) is exported as an interface (types.Gomega) whereas the other (the withT variant)
65
// is shared as a concrete type (*WithT, which is aliased to *internal.Gomega).  1.15 did not clean this mess up to ensure
66
// that declarations of *WithT in existing code are not broken by the upgrade to 1.15.
67
type WithT = internal.Gomega
68

69
// GomegaWithT is deprecated in favor of gomega.WithT, which does not stutter.
70
type GomegaWithT = WithT
71

72
// inner is an interface that allows users to provide a wrapper around Default.  The wrapper
73
// must implement the inner interface and return either the original Default or the result of
74
// a call to NewGomega().
75
type inner interface {
76
	Inner() Gomega
77
}
78

79
func internalGomega(g Gomega) *internal.Gomega {
80
	if v, ok := g.(inner); ok {
81
		return v.Inner().(*internal.Gomega)
82
	}
83
	return g.(*internal.Gomega)
84
}
85

86
// NewWithT takes a *testing.T and returns a `gomega.WithT` allowing you to use `Expect`, `Eventually`, and `Consistently` along with
87
// Gomega's rich ecosystem of matchers in standard `testing` test suits.
88
//
89
//	func TestFarmHasCow(t *testing.T) {
90
//	    g := gomega.NewWithT(t)
91
//
92
//	    f := farm.New([]string{"Cow", "Horse"})
93
//	    g.Expect(f.HasCow()).To(BeTrue(), "Farm should have cow")
94
//	 }
95
func NewWithT(t types.GomegaTestingT) *WithT {
96
	return internal.NewGomega(internalGomega(Default).DurationBundle).ConfigureWithT(t)
97
}
98

99
// NewGomegaWithT is deprecated in favor of gomega.NewWithT, which does not stutter.
100
var NewGomegaWithT = NewWithT
101

102
// RegisterFailHandler connects Ginkgo to Gomega. When a matcher fails
103
// the fail handler passed into RegisterFailHandler is called.
104
func RegisterFailHandler(fail types.GomegaFailHandler) {
105
	internalGomega(Default).ConfigureWithFailHandler(fail)
106
}
107

108
// RegisterFailHandlerWithT is deprecated and will be removed in a future release.
109
// users should use RegisterFailHandler, or RegisterTestingT
110
func RegisterFailHandlerWithT(_ types.GomegaTestingT, fail types.GomegaFailHandler) {
111
	fmt.Println("RegisterFailHandlerWithT is deprecated.  Please use RegisterFailHandler or RegisterTestingT instead.")
112
	internalGomega(Default).ConfigureWithFailHandler(fail)
113
}
114

115
// RegisterTestingT connects Gomega to Golang's XUnit style
116
// Testing.T tests.  It is now deprecated and you should use NewWithT() instead to get a fresh instance of Gomega for each test.
117
func RegisterTestingT(t types.GomegaTestingT) {
118
	internalGomega(Default).ConfigureWithT(t)
119
}
120

121
// InterceptGomegaFailures runs a given callback and returns an array of
122
// failure messages generated by any Gomega assertions within the callback.
123
// Execution continues after the first failure allowing users to collect all failures
124
// in the callback.
125
//
126
// This is most useful when testing custom matchers, but can also be used to check
127
// on a value using a Gomega assertion without causing a test failure.
128
func InterceptGomegaFailures(f func()) []string {
129
	originalHandler := internalGomega(Default).Fail
130
	failures := []string{}
131
	internalGomega(Default).Fail = func(message string, callerSkip ...int) {
132
		failures = append(failures, message)
133
	}
134
	defer func() {
135
		internalGomega(Default).Fail = originalHandler
136
	}()
137
	f()
138
	return failures
139
}
140

141
// InterceptGomegaFailure runs a given callback and returns the first
142
// failure message generated by any Gomega assertions within the callback, wrapped in an error.
143
//
144
// The callback ceases execution as soon as the first failed assertion occurs, however Gomega
145
// does not register a failure with the FailHandler registered via RegisterFailHandler - it is up
146
// to the user to decide what to do with the returned error
147
func InterceptGomegaFailure(f func()) (err error) {
148
	originalHandler := internalGomega(Default).Fail
149
	internalGomega(Default).Fail = func(message string, callerSkip ...int) {
150
		err = errors.New(message)
151
		panic("stop execution")
152
	}
153

154
	defer func() {
155
		internalGomega(Default).Fail = originalHandler
156
		if e := recover(); e != nil {
157
			if err == nil {
158
				panic(e)
159
			}
160
		}
161
	}()
162

163
	f()
164
	return err
165
}
166

167
func ensureDefaultGomegaIsConfigured() {
168
	if !internalGomega(Default).IsConfigured() {
169
		panic(nilGomegaPanic)
170
	}
171
}
172

173
// Ω wraps an actual value allowing assertions to be made on it:
174
//
175
//	Ω("foo").Should(Equal("foo"))
176
//
177
// If Ω is passed more than one argument it will pass the *first* argument to the matcher.
178
// All subsequent arguments will be required to be nil/zero.
179
//
180
// This is convenient if you want to make an assertion on a method/function that returns
181
// a value and an error - a common pattern in Go.
182
//
183
// For example, given a function with signature:
184
//
185
//	func MyAmazingThing() (int, error)
186
//
187
// Then:
188
//
189
//	Ω(MyAmazingThing()).Should(Equal(3))
190
//
191
// Will succeed only if `MyAmazingThing()` returns `(3, nil)`
192
//
193
// Ω and Expect are identical
194
func Ω(actual any, extra ...any) Assertion {
195
	ensureDefaultGomegaIsConfigured()
196
	return Default.Ω(actual, extra...)
197
}
198

199
// Expect wraps an actual value allowing assertions to be made on it:
200
//
201
//	Expect("foo").To(Equal("foo"))
202
//
203
// If Expect is passed more than one argument it will pass the *first* argument to the matcher.
204
// All subsequent arguments will be required to be nil/zero.
205
//
206
// This is convenient if you want to make an assertion on a method/function that returns
207
// a value and an error - a common pattern in Go.
208
//
209
// For example, given a function with signature:
210
//
211
//	func MyAmazingThing() (int, error)
212
//
213
// Then:
214
//
215
//	Expect(MyAmazingThing()).Should(Equal(3))
216
//
217
// Will succeed only if `MyAmazingThing()` returns `(3, nil)`
218
//
219
// Expect and Ω are identical
220
func Expect(actual any, extra ...any) Assertion {
221
	ensureDefaultGomegaIsConfigured()
222
	return Default.Expect(actual, extra...)
223
}
224

225
// ExpectWithOffset wraps an actual value allowing assertions to be made on it:
226
//
227
//	ExpectWithOffset(1, "foo").To(Equal("foo"))
228
//
229
// Unlike `Expect` and `Ω`, `ExpectWithOffset` takes an additional integer argument
230
// that is used to modify the call-stack offset when computing line numbers. It is
231
// the same as `Expect(...).WithOffset`.
232
//
233
// This is most useful in helper functions that make assertions.  If you want Gomega's
234
// error message to refer to the calling line in the test (as opposed to the line in the helper function)
235
// set the first argument of `ExpectWithOffset` appropriately.
236
func ExpectWithOffset(offset int, actual any, extra ...any) Assertion {
237
	ensureDefaultGomegaIsConfigured()
238
	return Default.ExpectWithOffset(offset, actual, extra...)
239
}
240

241
/*
242
Eventually enables making assertions on asynchronous behavior.
243

244
Eventually checks that an assertion *eventually* passes.  Eventually blocks when called and attempts an assertion periodically until it passes or a timeout occurs.  Both the timeout and polling interval are configurable as optional arguments.
245
The first optional argument is the timeout (which defaults to 1s), the second is the polling interval (which defaults to 10ms).  Both intervals can be specified as time.Duration, parsable duration strings or floats/integers (in which case they are interpreted as seconds).  In addition an optional context.Context can be passed in - Eventually will keep trying until either the timeout expires or the context is cancelled, whichever comes first.
246

247
Eventually works with any Gomega compatible matcher and supports making assertions against three categories of actual value:
248

249
**Category 1: Making Eventually assertions on values**
250

251
There are several examples of values that can change over time.  These can be passed in to Eventually and will be passed to the matcher repeatedly until a match occurs.  For example:
252

253
	c := make(chan bool)
254
	go DoStuff(c)
255
	Eventually(c, "50ms").Should(BeClosed())
256

257
will poll the channel repeatedly until it is closed.  In this example `Eventually` will block until either the specified timeout of 50ms has elapsed or the channel is closed, whichever comes first.
258

259
Several Gomega libraries allow you to use Eventually in this way.  For example, the gomega/gexec package allows you to block until a *gexec.Session exits successfully via:
260

261
	Eventually(session).Should(gexec.Exit(0))
262

263
And the gomega/gbytes package allows you to monitor a streaming *gbytes.Buffer until a given string is seen:
264

265
	Eventually(buffer).Should(gbytes.Say("hello there"))
266

267
In these examples, both `session` and `buffer` are designed to be thread-safe when polled by the `Exit` and `Say` matchers.  This is not true in general of most raw values, so while it is tempting to do something like:
268

269
	// THIS IS NOT THREAD-SAFE
270
	var s *string
271
	go mutateStringEventually(s)
272
	Eventually(s).Should(Equal("I've changed"))
273

274
this will trigger Go's race detector as the goroutine polling via Eventually will race over the value of s with the goroutine mutating the string.  For cases like this you can use channels or introduce your own locking around s by passing Eventually a function.
275

276
**Category 2: Make Eventually assertions on functions**
277

278
Eventually can be passed functions that **return at least one value**.  When configured this way, Eventually will poll the function repeatedly and pass the first returned value to the matcher.
279

280
For example:
281

282
	   Eventually(func() int {
283
	   	return client.FetchCount()
284
	   }).Should(BeNumerically(">=", 17))
285

286
	will repeatedly poll client.FetchCount until the BeNumerically matcher is satisfied.  (Note that this example could have been written as Eventually(client.FetchCount).Should(BeNumerically(">=", 17)))
287

288
If multiple values are returned by the function, Eventually will pass the first value to the matcher and require that all others are zero-valued.  This allows you to pass Eventually a function that returns a value and an error - a common pattern in Go.
289

290
For example, consider a method that returns a value and an error:
291

292
	func FetchFromDB() (string, error)
293

294
Then
295

296
	Eventually(FetchFromDB).Should(Equal("got it"))
297

298
will pass only if and when the returned error is nil *and* the returned string satisfies the matcher.
299

300
Eventually can also accept functions that take arguments, however you must provide those arguments using .WithArguments().  For example, consider a function that takes a user-id and makes a network request to fetch a full name:
301

302
	func FetchFullName(userId int) (string, error)
303

304
You can poll this function like so:
305

306
	Eventually(FetchFullName).WithArguments(1138).Should(Equal("Wookie"))
307

308
It is important to note that the function passed into Eventually is invoked *synchronously* when polled.  Eventually does not (in fact, it cannot) kill the function if it takes longer to return than Eventually's configured timeout.  A common practice here is to use a context.  Here's an example that combines Ginkgo's spec timeout support with Eventually:
309

310
	It("fetches the correct count", func(ctx SpecContext) {
311
		Eventually(ctx, func() int {
312
			return client.FetchCount(ctx, "/users")
313
		}).Should(BeNumerically(">=", 17))
314
	}, SpecTimeout(time.Second))
315

316
you an also use Eventually().WithContext(ctx) to pass in the context.  Passed-in contexts play nicely with passed-in arguments as long as the context appears first.  You can rewrite the above example as:
317

318
	It("fetches the correct count", func(ctx SpecContext) {
319
		Eventually(client.FetchCount).WithContext(ctx).WithArguments("/users").Should(BeNumerically(">=", 17))
320
	}, SpecTimeout(time.Second))
321

322
Either way the context passed to Eventually is also passed to the underlying function.  Now, when Ginkgo cancels the context both the FetchCount client and Gomega will be informed and can exit.
323

324
By default, when a context is passed to Eventually *without* an explicit timeout, Gomega will rely solely on the context's cancellation to determine when to stop polling.  If you want to specify a timeout in addition to the context you can do so using the .WithTimeout() method.  For example:
325

326
	Eventually(client.FetchCount).WithContext(ctx).WithTimeout(10*time.Second).Should(BeNumerically(">=", 17))
327

328
now either the context cancellation or the timeout will cause Eventually to stop polling.
329

330
If, instead, you would like to opt out of this behavior and have Gomega's default timeouts govern Eventuallys that take a context you can call:
331

332
	EnforceDefaultTimeoutsWhenUsingContexts()
333

334
in the DSL (or on a Gomega instance).  Now all calls to Eventually that take a context will fail if either the context is cancelled or the default timeout elapses.
335

336
**Category 3: Making assertions _in_ the function passed into Eventually**
337

338
When testing complex systems it can be valuable to assert that a _set_ of assertions passes Eventually.  Eventually supports this by accepting functions that take a single Gomega argument and return zero or more values.
339

340
Here's an example that makes some assertions and returns a value and error:
341

342
	Eventually(func(g Gomega) (Widget, error) {
343
		ids, err := client.FetchIDs()
344
		g.Expect(err).NotTo(HaveOccurred())
345
		g.Expect(ids).To(ContainElement(1138))
346
		return client.FetchWidget(1138)
347
	}).Should(Equal(expectedWidget))
348

349
will pass only if all the assertions in the polled function pass and the return value satisfied the matcher.
350

351
Eventually also supports a special case polling function that takes a single Gomega argument and returns no values.  Eventually assumes such a function is making assertions and is designed to work with the Succeed matcher to validate that all assertions have passed.
352
For example:
353

354
	Eventually(func(g Gomega) {
355
		model, err := client.Find(1138)
356
		g.Expect(err).NotTo(HaveOccurred())
357
		g.Expect(model.Reticulate()).To(Succeed())
358
		g.Expect(model.IsReticulated()).To(BeTrue())
359
		g.Expect(model.Save()).To(Succeed())
360
	}).Should(Succeed())
361

362
will rerun the function until all assertions pass.
363

364
You can also pass additional arguments to functions that take a Gomega.  The only rule is that the Gomega argument must be first.  If you also want to pass the context attached to Eventually you must ensure that is the second argument.  For example:
365

366
	Eventually(func(g Gomega, ctx context.Context, path string, expected ...string){
367
		tok, err := client.GetToken(ctx)
368
		g.Expect(err).NotTo(HaveOccurred())
369

370
		elements, err := client.Fetch(ctx, tok, path)
371
		g.Expect(err).NotTo(HaveOccurred())
372
		g.Expect(elements).To(ConsistOf(expected))
373
	}).WithContext(ctx).WithArguments("/names", "Joe", "Jane", "Sam").Should(Succeed())
374

375
You can ensure that you get a number of consecutive successful tries before succeeding using `MustPassRepeatedly(int)`. For Example:
376

377
	int count := 0
378
	Eventually(func() bool {
379
		count++
380
		return count > 2
381
	}).MustPassRepeatedly(2).Should(BeTrue())
382
	// Because we had to wait for 2 calls that returned true
383
	Expect(count).To(Equal(3))
384

385
Finally, in addition to passing timeouts and a context to Eventually you can be more explicit with Eventually's chaining configuration methods:
386

387
	Eventually(..., "10s", "2s", ctx).Should(...)
388

389
is equivalent to
390

391
	Eventually(...).WithTimeout(10*time.Second).WithPolling(2*time.Second).WithContext(ctx).Should(...)
392
*/
393
func Eventually(actualOrCtx any, args ...any) AsyncAssertion {
394
	ensureDefaultGomegaIsConfigured()
395
	return Default.Eventually(actualOrCtx, args...)
396
}
397

398
// EventuallyWithOffset operates like Eventually but takes an additional
399
// initial argument to indicate an offset in the call stack.  This is useful when building helper
400
// functions that contain matchers.  To learn more, read about `ExpectWithOffset`.
401
//
402
// `EventuallyWithOffset` is the same as `Eventually(...).WithOffset`.
403
//
404
// `EventuallyWithOffset` specifying a timeout interval (and an optional polling interval) are
405
// the same as `Eventually(...).WithOffset(...).WithTimeout` or
406
// `Eventually(...).WithOffset(...).WithTimeout(...).WithPolling`.
407
func EventuallyWithOffset(offset int, actualOrCtx any, args ...any) AsyncAssertion {
408
	ensureDefaultGomegaIsConfigured()
409
	return Default.EventuallyWithOffset(offset, actualOrCtx, args...)
410
}
411

412
/*
413
Consistently, like Eventually, enables making assertions on asynchronous behavior.
414

415
Consistently blocks when called for a specified duration.  During that duration Consistently repeatedly polls its matcher and ensures that it is satisfied.  If the matcher is consistently satisfied, then Consistently will pass.  Otherwise Consistently will fail.
416

417
Both the total waiting duration and the polling interval are configurable as optional arguments.  The first optional argument is the duration that Consistently will run for (defaults to 100ms), and the second argument is the polling interval (defaults to 10ms).  As with Eventually, these intervals can be passed in as time.Duration, parsable duration strings or an integer or float number of seconds.  You can also pass in an optional context.Context - Consistently will exit early (with a failure) if the context is cancelled before the waiting duration expires.
418

419
Consistently accepts the same three categories of actual as Eventually, check the Eventually docs to learn more.
420

421
Consistently is useful in cases where you want to assert that something *does not happen* for a period of time.  For example, you may want to assert that a goroutine does *not* send data down a channel.  In this case you could write:
422

423
	Consistently(channel, "200ms").ShouldNot(Receive())
424

425
This will block for 200 milliseconds and repeatedly check the channel and ensure nothing has been received.
426
*/
427
func Consistently(actualOrCtx any, args ...any) AsyncAssertion {
428
	ensureDefaultGomegaIsConfigured()
429
	return Default.Consistently(actualOrCtx, args...)
430
}
431

432
// ConsistentlyWithOffset operates like Consistently but takes an additional
433
// initial argument to indicate an offset in the call stack. This is useful when building helper
434
// functions that contain matchers. To learn more, read about `ExpectWithOffset`.
435
//
436
// `ConsistentlyWithOffset` is the same as `Consistently(...).WithOffset` and
437
// optional `WithTimeout` and `WithPolling`.
438
func ConsistentlyWithOffset(offset int, actualOrCtx any, args ...any) AsyncAssertion {
439
	ensureDefaultGomegaIsConfigured()
440
	return Default.ConsistentlyWithOffset(offset, actualOrCtx, args...)
441
}
442

443
/*
444
StopTrying can be used to signal to Eventually and Consistently that they should abort and stop trying.  This always results in a failure of the assertion - and the failure message is the content of the StopTrying signal.
445

446
You can send the StopTrying signal by either returning StopTrying("message") as an error from your passed-in function _or_ by calling StopTrying("message").Now() to trigger a panic and end execution.
447

448
You can also wrap StopTrying around an error with `StopTrying("message").Wrap(err)` and can attach additional objects via `StopTrying("message").Attach("description", object).  When rendered, the signal will include the wrapped error and any attached objects rendered using Gomega's default formatting.
449

450
Here are a couple of examples.  This is how you might use StopTrying() as an error to signal that Eventually should stop:
451

452
	playerIndex, numPlayers := 0, 11
453
	Eventually(func() (string, error) {
454
	    if playerIndex == numPlayers {
455
	        return "", StopTrying("no more players left")
456
	    }
457
	    name := client.FetchPlayer(playerIndex)
458
	    playerIndex += 1
459
	    return name, nil
460
	}).Should(Equal("Patrick Mahomes"))
461

462
And here's an example where `StopTrying().Now()` is called to halt execution immediately:
463

464
	Eventually(func() []string {
465
		names, err := client.FetchAllPlayers()
466
		if err == client.IRRECOVERABLE_ERROR {
467
			StopTrying("Irrecoverable error occurred").Wrap(err).Now()
468
		}
469
		return names
470
	}).Should(ContainElement("Patrick Mahomes"))
471
*/
472
var StopTrying = internal.StopTrying
473

474
/*
475
TryAgainAfter(<duration>) allows you to adjust the polling interval for the _next_ iteration of `Eventually` or `Consistently`.  Like `StopTrying` you can either return `TryAgainAfter` as an error or trigger it immedieately with `.Now()`
476

477
When `TryAgainAfter(<duration>` is triggered `Eventually` and `Consistently` will wait for that duration.  If a timeout occurs before the next poll is triggered both `Eventually` and `Consistently` will always fail with the content of the TryAgainAfter message.  As with StopTrying you can `.Wrap()` and error and `.Attach()` additional objects to `TryAgainAfter`.
478
*/
479
var TryAgainAfter = internal.TryAgainAfter
480

481
/*
482
PollingSignalError is the error returned by StopTrying() and TryAgainAfter()
483
*/
484
type PollingSignalError = internal.PollingSignalError
485

486
// SetDefaultEventuallyTimeout sets the default timeout duration for Eventually. Eventually will repeatedly poll your condition until it succeeds, or until this timeout elapses.
487
func SetDefaultEventuallyTimeout(t time.Duration) {
488
	Default.SetDefaultEventuallyTimeout(t)
489
}
490

491
// SetDefaultEventuallyPollingInterval sets the default polling interval for Eventually.
492
func SetDefaultEventuallyPollingInterval(t time.Duration) {
493
	Default.SetDefaultEventuallyPollingInterval(t)
494
}
495

496
// SetDefaultConsistentlyDuration sets  the default duration for Consistently. Consistently will verify that your condition is satisfied for this long.
497
func SetDefaultConsistentlyDuration(t time.Duration) {
498
	Default.SetDefaultConsistentlyDuration(t)
499
}
500

501
// SetDefaultConsistentlyPollingInterval sets the default polling interval for Consistently.
502
func SetDefaultConsistentlyPollingInterval(t time.Duration) {
503
	Default.SetDefaultConsistentlyPollingInterval(t)
504
}
505

506
// EnforceDefaultTimeoutsWhenUsingContexts forces `Eventually` to apply a default timeout even when a context is provided.
507
func EnforceDefaultTimeoutsWhenUsingContexts() {
508
	Default.EnforceDefaultTimeoutsWhenUsingContexts()
509
}
510

511
// DisableDefaultTimeoutsWhenUsingContext disables the default timeout when a context is provided to `Eventually`.
512
func DisableDefaultTimeoutsWhenUsingContext() {
513
	Default.DisableDefaultTimeoutsWhenUsingContext()
514
}
515

516
// AsyncAssertion is returned by Eventually and Consistently and polls the actual value passed into Eventually against
517
// the matcher passed to the Should and ShouldNot methods.
518
//
519
// Both Should and ShouldNot take a variadic optionalDescription argument.
520
// This argument allows you to make your failure messages more descriptive.
521
// If a single argument of type `func() string` is passed, this function will be lazily evaluated if a failure occurs
522
// and the returned string is used to annotate the failure message.
523
// Otherwise, this argument is passed on to fmt.Sprintf() and then used to annotate the failure message.
524
//
525
// Both Should and ShouldNot return a boolean that is true if the assertion passed and false if it failed.
526
//
527
// Example:
528
//
529
//	Eventually(myChannel).Should(Receive(), "Something should have come down the pipe.")
530
//	Consistently(myChannel).ShouldNot(Receive(), func() string { return "Nothing should have come down the pipe." })
531
type AsyncAssertion = types.AsyncAssertion
532

533
// GomegaAsyncAssertion is deprecated in favor of AsyncAssertion, which does not stutter.
534
type GomegaAsyncAssertion = types.AsyncAssertion
535

536
// Assertion is returned by Ω and Expect and compares the actual value to the matcher
537
// passed to the Should/ShouldNot and To/ToNot/NotTo methods.
538
//
539
// Typically Should/ShouldNot are used with Ω and To/ToNot/NotTo are used with Expect
540
// though this is not enforced.
541
//
542
// All methods take a variadic optionalDescription argument.
543
// This argument allows you to make your failure messages more descriptive.
544
// If a single argument of type `func() string` is passed, this function will be lazily evaluated if a failure occurs
545
// and the returned string is used to annotate the failure message.
546
// Otherwise, this argument is passed on to fmt.Sprintf() and then used to annotate the failure message.
547
//
548
// All methods return a bool that is true if the assertion passed and false if it failed.
549
//
550
// Example:
551
//
552
//	Ω(farm.HasCow()).Should(BeTrue(), "Farm %v should have a cow", farm)
553
type Assertion = types.Assertion
554

555
// GomegaAssertion is deprecated in favor of Assertion, which does not stutter.
556
type GomegaAssertion = types.Assertion
557

558
// OmegaMatcher is deprecated in favor of the better-named and better-organized types.GomegaMatcher but sticks around to support existing code that uses it
559
type OmegaMatcher = types.GomegaMatcher
560

561