Repository: stretchr/testify
Pull request #1188 (2022-05-23 20:13:24)

Add WithinTimeRange method
## Summary
Add `WithinTimeRange` and `WithinTimeRangef` assertion methods.

## Changes
Adds the `WithinTimeRange` assertion function that checks whether the _expected_ time is on or after the _start_ time and on or before the _end_ time. If _end_ is before _start_ the function also fails.

Adds `WithinTimeRange` and `WithTimeRangef` methods on `*Assertions` that calls the `WithinTimeRange` function internally. 

## Motivation
There are cases where one would like to test that a time value is within a certain range, for example when the code being tested updates a timestamp:
```
before := time.Now()
actual := Foo()
after := time.Now()

assert.WithinTimeRange(t, actual.timeStamp, before, after)
```

Currently, the only time-related assertion method is `WithinDuration`, but in the above mentioned situation it leads to one of the following solutions:
- Using two `assert.True` checks against the `before` and `after` times.
 ```
before := time.Now()
actual := Foo()
after := time.Now()

assert.True(t, actual.timeStamp.After(before))
assert.True(t, actual.timeStamp.Before(after))
```
- Deriving a _duration_ from the `before` and `after` times to use in the `WithDuration` assertion.
```
before := time.Now()
actual := Foo()
after := time.Now()
halfDur := after.Sub(before) / 2

assert.WithinDuration(t, actual.timeStamp, before.Add(halfDur), halfDur)
```
- Using `WithDuration` to assert against `time.Now()` with an arbitrary duration, leading to flaky tests.
```
before := time.Now()
actual := Foo()
after := time.Now()

assert.WithinDuration(t, actual.timeStamp, time.Now(), time.Second)
```

## Related issues
https://github.com/stretchr/testify/pull/689



Patch:
diff --git a/assert/assertion_format.go b/assert/assertion_format.go
index 27e2420..7880b8f 100644
--- a/assert/assertion_format.go
+++ b/assert/assertion_format.go
@@ -736,6 +736,16 @@ func WithinDurationf(t TestingT, expected time.Time, actual time.Time, delta tim
 	return WithinDuration(t, expected, actual, delta, append([]interface{}{msg}, args...)...)
 }
 
+// WithinRangef asserts that a time is within a time range (inclusive).
+//
+//   assert.WithinRangef(t, time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second), "error message %s", "formatted")
+func WithinRangef(t TestingT, actual time.Time, start time.Time, end time.Time, msg string, args ...interface{}) bool {
+	if h, ok := t.(tHelper); ok {
+		h.Helper()
+	}
+	return WithinRange(t, actual, start, end, append([]interface{}{msg}, args...)...)
+}
+
 // YAMLEqf asserts that two YAML strings are equivalent.
 func YAMLEqf(t TestingT, expected string, actual string, msg string, args ...interface{}) bool {
 	if h, ok := t.(tHelper); ok {
diff --git a/assert/assertion_forward.go b/assert/assertion_forward.go
index d9ea368..339515b 100644
--- a/assert/assertion_forward.go
+++ b/assert/assertion_forward.go
@@ -1461,6 +1461,26 @@ func (a *Assertions) WithinDurationf(expected time.Time, actual time.Time, delta
 	return WithinDurationf(a.t, expected, actual, delta, msg, args...)
 }
 
+// WithinRange asserts that a time is within a time range (inclusive).
+//
+//   a.WithinRange(time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second))
+func (a *Assertions) WithinRange(actual time.Time, start time.Time, end time.Time, msgAndArgs ...interface{}) bool {
+	if h, ok := a.t.(tHelper); ok {
+		h.Helper()
+	}
+	return WithinRange(a.t, actual, start, end, msgAndArgs...)
+}
+
+// WithinRangef asserts that a time is within a time range (inclusive).
+//
+//   a.WithinRangef(time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second), "error message %s", "formatted")
+func (a *Assertions) WithinRangef(actual time.Time, start time.Time, end time.Time, msg string, args ...interface{}) bool {
+	if h, ok := a.t.(tHelper); ok {
+		h.Helper()
+	}
+	return WithinRangef(a.t, actual, start, end, msg, args...)
+}
+
 // YAMLEq asserts that two YAML strings are equivalent.
 func (a *Assertions) YAMLEq(expected string, actual string, msgAndArgs ...interface{}) bool {
 	if h, ok := a.t.(tHelper); ok {
diff --git a/assert/assertions.go b/assert/assertions.go
index 580fdea..1fcb980 100644
--- a/assert/assertions.go
+++ b/assert/assertions.go
@@ -1110,6 +1110,27 @@ func WithinDuration(t TestingT, expected, actual time.Time, delta time.Duration,
 	return true
 }
 
+// WithinRange asserts that a time is within a time range (inclusive).
+//
+//   assert.WithinRange(t, time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second))
+func WithinRange(t TestingT, actual, start, end time.Time, msgAndArgs ...interface{}) bool {
+	if h, ok := t.(tHelper); ok {
+		h.Helper()
+	}
+
+	if end.Before(start) {
+		return Fail(t, "Start should be before end", msgAndArgs...)
+	}
+
+	if actual.Before(start) {
+		return Fail(t, fmt.Sprintf("Time %v expected to be in time range %v to %v, but is before the range", actual, start, end), msgAndArgs...)
+	} else if actual.After(end) {
+		return Fail(t, fmt.Sprintf("Time %v expected to be in time range %v to %v, but is after the range", actual, start, end), msgAndArgs...)
+	}
+
+	return true
+}
+
 func toFloat(x interface{}) (float64, bool) {
 	var xf float64
 	xok := true
diff --git a/require/require.go b/require/require.go
index 59c4827..880853f 100644
--- a/require/require.go
+++ b/require/require.go
@@ -1864,6 +1864,32 @@ func WithinDurationf(t TestingT, expected time.Time, actual time.Time, delta tim
 	t.FailNow()
 }
 
+// WithinRange asserts that a time is within a time range (inclusive).
+//
+//   assert.WithinRange(t, time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second))
+func WithinRange(t TestingT, actual time.Time, start time.Time, end time.Time, msgAndArgs ...interface{}) {
+	if h, ok := t.(tHelper); ok {
+		h.Helper()
+	}
+	if assert.WithinRange(t, actual, start, end, msgAndArgs...) {
+		return
+	}
+	t.FailNow()
+}
+
+// WithinRangef asserts that a time is within a time range (inclusive).
+//
+//   assert.WithinRangef(t, time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second), "error message %s", "formatted")
+func WithinRangef(t TestingT, actual time.Time, start time.Time, end time.Time, msg string, args ...interface{}) {
+	if h, ok := t.(tHelper); ok {
+		h.Helper()
+	}
+	if assert.WithinRangef(t, actual, start, end, msg, args...) {
+		return
+	}
+	t.FailNow()
+}
+
 // YAMLEq asserts that two YAML strings are equivalent.
 func YAMLEq(t TestingT, expected string, actual string, msgAndArgs ...interface{}) {
 	if h, ok := t.(tHelper); ok {
diff --git a/require/require_forward.go b/require/require_forward.go
index 5bb07c8..960bf6f 100644
--- a/require/require_forward.go
+++ b/require/require_forward.go
@@ -1462,6 +1462,26 @@ func (a *Assertions) WithinDurationf(expected time.Time, actual time.Time, delta
 	WithinDurationf(a.t, expected, actual, delta, msg, args...)
 }
 
+// WithinRange asserts that a time is within a time range (inclusive).
+//
+//   a.WithinRange(time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second))
+func (a *Assertions) WithinRange(actual time.Time, start time.Time, end time.Time, msgAndArgs ...interface{}) {
+	if h, ok := a.t.(tHelper); ok {
+		h.Helper()
+	}
+	WithinRange(a.t, actual, start, end, msgAndArgs...)
+}
+
+// WithinRangef asserts that a time is within a time range (inclusive).
+//
+//   a.WithinRangef(time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second), "error message %s", "formatted")
+func (a *Assertions) WithinRangef(actual time.Time, start time.Time, end time.Time, msg string, args ...interface{}) {
+	if h, ok := a.t.(tHelper); ok {
+		h.Helper()
+	}
+	WithinRangef(a.t, actual, start, end, msg, args...)
+}
+
 // YAMLEq asserts that two YAML strings are equivalent.
 func (a *Assertions) YAMLEq(expected string, actual string, msgAndArgs ...interface{}) {
 	if h, ok := a.t.(tHelper); ok {


Test patch:
diff --git a/assert/assertions_test.go b/assert/assertions_test.go
index 7a35a64..f407422 100644
--- a/assert/assertions_test.go
+++ b/assert/assertions_test.go
@@ -1350,6 +1350,25 @@ func TestWithinDuration(t *testing.T) {
 	False(t, WithinDuration(mockT, b, a, -11*time.Second), "A 10s difference is not within a 9s time difference")
 }
 
+func TestWithinRange(t *testing.T) {
+
+	mockT := new(testing.T)
+	n := time.Now()
+	s := n.Add(-time.Second)
+	e := n.Add(time.Second)
+
+	True(t, WithinRange(mockT, n, n, n), "Exact same actual, start, and end values return true")
+
+	True(t, WithinRange(mockT, n, s, e), "Time in range is within the time range")
+	True(t, WithinRange(mockT, s, s, e), "The start time is within the time range")
+	True(t, WithinRange(mockT, e, s, e), "The end time is within the time range")
+
+	False(t, WithinRange(mockT, s.Add(-time.Nanosecond), s, e, "Just before the start time is not within the time range"))
+	False(t, WithinRange(mockT, e.Add(time.Nanosecond), s, e, "Just after the end time is not within the time range"))
+
+	False(t, WithinRange(mockT, n, e, s, "Just after the end time is not within the time range"))
+}
+
 func TestInDelta(t *testing.T) {
 	mockT := new(testing.T)