Add WithinTimeRange method

[moolmanruan]

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

#689

[boyan-soubachov]

I'm of the opinion that this example isn't the most intuitive. Would it make more sense if we changed it to something like:

assert.WithinTimeRange(t, time.Now(), time.Now().Sub(time.Second()), time.Now().Add(time.Second()))

If you can think of a simpler example that would explicitly demonstrate the differences between start and end, that would be awesome :)

[moolmanruan]

Yeah, I'll think about it a bit and have a look at other examples to see if there's a better way to present it.

[moolmanruan]

Changed to assert.WithinTimeRange(t, time.Now(), time.Now().Add(-time.Second), time.Now().Add(time.Second)).

[boyan-soubachov]

1. For consistency with WithinDuration, should this function not be named WithinRange, the time.Time arguments explicitly state that the range being tested is a time range?
2. Semantically, the 2nd argument should be called actual, not expected since it's the value we're testing

[moolmanruan]

1. Sure. I added the Time to be more specific (since duration is a time related word, but range is not), but if it's not required I'm more than happy to change the naming to WithinRange.
2. You are right, will make the change.

[boyan-soubachov]

Looks great! Thank you for your contribution.

I hope you're enjoying your time at Luno, I had a blast there :)