v1.23.0

CHANGELOG.md

@@ -1,3 +1,23 @@
+## 1.23.0
+
+### Features
+- Custom formatting on a per-type basis can be provided using `format.RegisterCustomFormatter()` -- see the docs [here](https://onsi.github.io/gomega/#adjusting-output)
+
+- Substantial improvement have been made to `StopTrying()`:
+  - Users can now use `StopTrying().Wrap(err)` to wrap errors and `StopTrying().Attach(description, object)` to attach arbitrary objects to the `StopTrying()` error
+  - `StopTrying()` is now always interpreted as a failure.  If you are an early adopter of `StopTrying()` you may need to change your code as the prior version would match against the returned value even if `StopTrying()` was returned.  Going forward the `StopTrying()` api should remain stable.
+  - `StopTrying()` and `StopTrying().Now()` can both be used in matchers - not just polled functions.
+
+- `TryAgainAfter(duration)` is used like `StopTrying()` but instructs `Eventually` and `Consistently` that the poll should be tried again after the specified duration.  This allows you to dynamically adjust the polling duration.
+
+- `ctx` can now be passed-in as the first argument to `Eventually` and `Consistently`.
+
+## Maintenance
+
+- Bump github.com/onsi/ginkgo/v2 from 2.3.0 to 2.3.1 (#597) [afed901]
+- Bump nokogiri from 1.13.8 to 1.13.9 in /docs (#599) [7c691b3]
+- Bump github.com/google/go-cmp from 0.5.8 to 0.5.9 (#587) [ff22665]
+
 ## 1.22.1
 
 ## Fixes

gomega_dsl.go

@@ -22,7 +22,7 @@ import (
 	"github.com/onsi/gomega/types"
 )
 
-const GOMEGA_VERSION = "1.22.1"
+const GOMEGA_VERSION = "1.23.0"
 
 const nilGomegaPanic = `You are trying to make an assertion, but haven't registered Gomega's fail handler.
 If you're using Ginkgo then you probably forgot to put your assertion in an It().
@@ -86,12 +86,12 @@ func internalGomega(g Gomega) *internal.Gomega {
 // NewWithT takes a *testing.T and returns a `gomega.WithT` allowing you to use `Expect`, `Eventually`, and `Consistently` along with
 // Gomega's rich ecosystem of matchers in standard `testing` test suits.
 //
-//    func TestFarmHasCow(t *testing.T) {
-//        g := gomega.NewWithT(t)
+//	func TestFarmHasCow(t *testing.T) {
+//	    g := gomega.NewWithT(t)
 //
-//        f := farm.New([]string{"Cow", "Horse"})
-//        g.Expect(f.HasCow()).To(BeTrue(), "Farm should have cow")
-//     }
+//	    f := farm.New([]string{"Cow", "Horse"})
+//	    g.Expect(f.HasCow()).To(BeTrue(), "Farm should have cow")
+//	 }
 func NewWithT(t types.GomegaTestingT) *WithT {
 	return internal.NewGomega(internalGomega(Default).DurationBundle).ConfigureWithT(t)
 }
@@ -171,7 +171,8 @@ func ensureDefaultGomegaIsConfigured() {
 }
 
 // Ω wraps an actual value allowing assertions to be made on it:
-//    Ω("foo").Should(Equal("foo"))
+//
+//	Ω("foo").Should(Equal("foo"))
 //
 // If Ω is passed more than one argument it will pass the *first* argument to the matcher.
 // All subsequent arguments will be required to be nil/zero.
@@ -180,10 +181,13 @@ func ensureDefaultGomegaIsConfigured() {
 // a value and an error - a common patter in Go.
 //
 // For example, given a function with signature:
-//    func MyAmazingThing() (int, error)
+//
+//	func MyAmazingThing() (int, error)
 //
 // Then:
-//    Ω(MyAmazingThing()).Should(Equal(3))
+//
+//	Ω(MyAmazingThing()).Should(Equal(3))
+//
 // Will succeed only if `MyAmazingThing()` returns `(3, nil)`
 //
 // Ω and Expect are identical
@@ -193,7 +197,8 @@ func Ω(actual interface{}, extra ...interface{}) Assertion {
 }
 
 // Expect wraps an actual value allowing assertions to be made on it:
-//    Expect("foo").To(Equal("foo"))
+//
+//	Expect("foo").To(Equal("foo"))
 //
 // If Expect is passed more than one argument it will pass the *first* argument to the matcher.
 // All subsequent arguments will be required to be nil/zero.
@@ -202,10 +207,13 @@ func Ω(actual interface{}, extra ...interface{}) Assertion {
 // a value and an error - a common patter in Go.
 //
 // For example, given a function with signature:
-//    func MyAmazingThing() (int, error)
+//
+//	func MyAmazingThing() (int, error)
 //
 // Then:
-//    Expect(MyAmazingThing()).Should(Equal(3))
+//
+//	Expect(MyAmazingThing()).Should(Equal(3))
+//
 // Will succeed only if `MyAmazingThing()` returns `(3, nil)`
 //
 // Expect and Ω are identical
@@ -215,7 +223,8 @@ func Expect(actual interface{}, extra ...interface{}) Assertion {
 }
 
 // ExpectWithOffset wraps an actual value allowing assertions to be made on it:
-//    ExpectWithOffset(1, "foo").To(Equal("foo"))
+//
+//	ExpectWithOffset(1, "foo").To(Equal("foo"))
 //
 // Unlike `Expect` and `Ω`, `ExpectWithOffset` takes an additional integer argument
 // that is used to modify the call-stack offset when computing line numbers. It is
@@ -241,15 +250,15 @@ Eventually works with any Gomega compatible matcher and supports making assertio
 
 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:
 
-    c := make(chan bool)
-    go DoStuff(c)
-    Eventually(c, "50ms").Should(BeClosed())
+	c := make(chan bool)
+	go DoStuff(c)
+	Eventually(c, "50ms").Should(BeClosed())
 
 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.
 
 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:
 
-    Eventually(session).Should(gexec.Exit(0))
+	Eventually(session).Should(gexec.Exit(0))
 
 And the gomega/gbytes package allows you to monitor a streaming *gbytes.Buffer until a given string is seen:
 
@@ -270,26 +279,30 @@ Eventually can be passed functions that **return at least one value**.  When con
 
 For example:
 
-    Eventually(func() int {
-    	return client.FetchCount()
-    }).Should(BeNumerically(">=", 17))
+	   Eventually(func() int {
+	   	return client.FetchCount()
+	   }).Should(BeNumerically(">=", 17))
 
- 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)))
+	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)))
 
 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.
 
 For example, consider a method that returns a value and an error:
-    func FetchFromDB() (string, error)
+
+	func FetchFromDB() (string, error)
 
 Then
-    Eventually(FetchFromDB).Should(Equal("got it"))
+
+	Eventually(FetchFromDB).Should(Equal("got it"))
 
 will pass only if and when the returned error is nil *and* the returned string satisfies the matcher.
 
 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:
+
 	func FetchFullName(userId int) (string, error)
 
 You can poll this function like so:
+
 	Eventually(FetchFullName).WithArguments(1138).Should(Equal("Wookie"))
 
 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:
@@ -326,13 +339,13 @@ will pass only if all the assertions in the polled function pass and the return
 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.
 For example:
 
-    Eventually(func(g Gomega) {
-    	model, err := client.Find(1138)
-    	g.Expect(err).NotTo(HaveOccurred())
-    	g.Expect(model.Reticulate()).To(Succeed())
-    	g.Expect(model.IsReticulated()).To(BeTrue())
-    	g.Expect(model.Save()).To(Succeed())
-    }).Should(Succeed())
+	Eventually(func(g Gomega) {
+		model, err := client.Find(1138)
+		g.Expect(err).NotTo(HaveOccurred())
+		g.Expect(model.Reticulate()).To(Succeed())
+		g.Expect(model.IsReticulated()).To(BeTrue())
+		g.Expect(model.Save()).To(Succeed())
+	}).Should(Succeed())
 
 will rerun the function until all assertions pass.
 
@@ -353,7 +366,7 @@ Finally, in addition to passing timeouts and a context to Eventually you can be
 
 is equivalent to
 
-    Eventually(...).WithTimeout(time.Second).WithPolling(2*time.Second).WithContext(ctx).Should(...)
+	Eventually(...).WithTimeout(time.Second).WithPolling(2*time.Second).WithContext(ctx).Should(...)
 */
 func Eventually(args ...interface{}) AsyncAssertion {
 	ensureDefaultGomegaIsConfigured()
@@ -385,7 +398,7 @@ Consistently accepts the same three categories of actual as Eventually, check th
 
 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:
 
-    Consistently(channel, "200ms").ShouldNot(Receive())
+	Consistently(channel, "200ms").ShouldNot(Receive())
 
 This will block for 200 milliseconds and repeatedly check the channel and ensure nothing has been received.
 */
@@ -481,8 +494,8 @@ func SetDefaultConsistentlyPollingInterval(t time.Duration) {
 //
 // Example:
 //
-//   Eventually(myChannel).Should(Receive(), "Something should have come down the pipe.")
-//   Consistently(myChannel).ShouldNot(Receive(), func() string { return "Nothing should have come down the pipe." })
+//	Eventually(myChannel).Should(Receive(), "Something should have come down the pipe.")
+//	Consistently(myChannel).ShouldNot(Receive(), func() string { return "Nothing should have come down the pipe." })
 type AsyncAssertion = types.AsyncAssertion
 
 // GomegaAsyncAssertion is deprecated in favor of AsyncAssertion, which does not stutter.
@@ -504,7 +517,7 @@ type GomegaAsyncAssertion = types.AsyncAssertion
 //
 // Example:
 //
-//    Ω(farm.HasCow()).Should(BeTrue(), "Farm %v should have a cow", farm)
+//	Ω(farm.HasCow()).Should(BeTrue(), "Farm %v should have a cow", farm)
 type Assertion = types.Assertion
 
 // GomegaAssertion is deprecated in favor of Assertion, which does not stutter.