separate out offsets and timeouts (#478)

Author: thediveo

gomega_dsl.go

@@ -204,7 +204,8 @@ func Expect(actual interface{}, extra ...interface{}) Assertion {
 //    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.
+// that is used to modify the call-stack offset when computing line numbers. It is
+// the same as `Expect(...).WithOffset`.
 //
 // This is most useful in helper functions that make assertions.  If you want Gomega's
 // error message to refer to the calling line in the test (as opposed to the line in the helper function)
@@ -300,6 +301,9 @@ For example:
     }).Should(Succeed())
 
 will rerun the function until all assertions pass.
+
+`Eventually` specifying a timeout interval (and an optional polling interval) are
+the same as `Eventually(...).WithTimeout` or `Eventually(...).WithTimeout(...).WithPolling`.
 */
 func Eventually(actual interface{}, intervals ...interface{}) AsyncAssertion {
 	ensureDefaultGomegaIsConfigured()
@@ -309,6 +313,12 @@ func Eventually(actual interface{}, intervals ...interface{}) AsyncAssertion {
 // EventuallyWithOffset operates like Eventually but takes an additional
 // initial argument to indicate an offset in the call stack.  This is useful when building helper
 // functions that contain matchers.  To learn more, read about `ExpectWithOffset`.
+//
+// `EventuallyWithOffset` is the same as `Eventually(...).WithOffset`.
+//
+// `EventuallyWithOffset` specifying a timeout interval (and an optional polling interval) are
+// the same as `Eventually(...).WithOffset(...).WithTimeout` or
+// `Eventually(...).WithOffset(...).WithTimeout(...).WithPolling`.
 func EventuallyWithOffset(offset int, actual interface{}, intervals ...interface{}) AsyncAssertion {
 	ensureDefaultGomegaIsConfigured()
 	return Default.EventuallyWithOffset(offset, actual, intervals...)
@@ -337,6 +347,9 @@ func Consistently(actual interface{}, intervals ...interface{}) AsyncAssertion {
 // ConsistentlyWithOffset operates like Consistently but takes an additional
 // initial argument to indicate an offset in the call stack. This is useful when building helper
 // functions that contain matchers. To learn more, read about `ExpectWithOffset`.
+//
+// `ConsistentlyWithOffset` is the same as `Consistently(...).WithOffset` and
+// optional `WithTimeout` and `WithPolling`.
 func ConsistentlyWithOffset(offset int, actual interface{}, intervals ...interface{}) AsyncAssertion {
 	ensureDefaultGomegaIsConfigured()
 	return Default.ConsistentlyWithOffset(offset, actual, intervals...)

internal/assertion.go

@@ -23,6 +23,11 @@ func NewAssertion(actualInput interface{}, g *Gomega, offset int, extra ...inter
 	}
 }
 
+func (assertion *Assertion) WithOffset(offset int) types.Assertion {
+	assertion.offset = offset
+	return assertion
+}
+
 func (assertion *Assertion) Should(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
 	assertion.g.THelper()
 	return assertion.vetExtras(optionalDescription...) && assertion.match(matcher, true, optionalDescription...)

internal/async_assertion.go

@@ -87,6 +87,21 @@ func NewAsyncAssertion(asyncType AsyncAssertionType, actualInput interface{}, g
 	return out
 }
 
+func (assertion *AsyncAssertion) WithOffset(offset int) types.AsyncAssertion {
+	assertion.offset = offset
+	return assertion
+}
+
+func (assertion *AsyncAssertion) WithTimeout(interval time.Duration) types.AsyncAssertion {
+	assertion.timeoutInterval = interval
+	return assertion
+}
+
+func (assertion *AsyncAssertion) WithPolling(interval time.Duration) types.AsyncAssertion {
+	assertion.pollingInterval = interval
+	return assertion
+}
+
 func (assertion *AsyncAssertion) Should(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
 	assertion.g.THelper()
 	return assertion.match(matcher, true, optionalDescription...)

internal/async_assertion_test.go

@@ -215,9 +215,9 @@ var _ = Describe("Gomega DSL", func() {
 			doubleNested := func(eventually bool) {
 				func() {
 					if eventually {
-						EventuallyWithOffset(2, true, "10ms", "5ms").Should(BeFalse())
+						Eventually(true, "10ms", "5ms").WithOffset(2).Should(BeFalse())
 					} else {
-						ExpectWithOffset(2, true).To(BeFalse())
+						Expect(true).WithOffset(2).To(BeFalse())
 					}
 				}()
 			}

internal/dsl_test.go

@@ -61,9 +61,9 @@ var _ = Describe("Gomega", func() {
 			doubleNested := func(g Gomega, eventually bool) {
 				func() {
 					if eventually {
-						g.EventuallyWithOffset(2, true, "10ms", "5ms").Should(BeFalse())
+						g.Eventually(true, "10ms", "5ms").WithOffset(2).Should(BeFalse())
 					} else {
-						g.ExpectWithOffset(2, true).To(BeFalse())
+						g.Expect(true).WithOffset(2).To(BeFalse())
 					}
 				}()
 			}

internal/gomega_test.go

@@ -13,7 +13,7 @@ var _ = Describe("SatisfyMatcher", func() {
 
 	Context("Panic if predicate is invalid", func() {
 		panicsWithPredicate := func(predicate interface{}) {
-			ExpectWithOffset(1, func() { Satisfy(predicate) }).To(Panic())
+			Expect(func() { Satisfy(predicate) }).WithOffset(1).To(Panic())
 		}
 		It("nil", func() {
 			panicsWithPredicate(nil)

matchers/satisfy_matcher_test.go

@@ -14,7 +14,7 @@ var _ = Describe("WithTransformMatcher", func() {
 
 	Context("Panic if transform function invalid", func() {
 		panicsWithTransformer := func(transform interface{}) {
-			ExpectWithOffset(1, func() { WithTransform(transform, nil) }).To(Panic())
+			Expect(func() { WithTransform(transform, nil) }).WithOffset(1).To(Panic())
 		}
 		It("nil", func() {
 			panicsWithTransformer(nil)

matchers/with_transform_test.go

@@ -66,6 +66,10 @@ func MatchMayChangeInTheFuture(matcher GomegaMatcher, value interface{}) bool {
 type AsyncAssertion interface {
 	Should(matcher GomegaMatcher, optionalDescription ...interface{}) bool
 	ShouldNot(matcher GomegaMatcher, optionalDescription ...interface{}) bool
+
+	WithOffset(offset int) AsyncAssertion
+	WithTimeout(interval time.Duration) AsyncAssertion
+	WithPolling(interval time.Duration) AsyncAssertion
 }
 
 // Assertions are returned by Ω and Expect and enable assertions against Gomega matchers
@@ -76,4 +80,6 @@ type Assertion interface {
 	To(matcher GomegaMatcher, optionalDescription ...interface{}) bool
 	ToNot(matcher GomegaMatcher, optionalDescription ...interface{}) bool
 	NotTo(matcher GomegaMatcher, optionalDescription ...interface{}) bool
+
+	WithOffset(offset int) Assertion
 }