Fest Date assertions proposals

[Joel Costigliola]

Hi guys,

I'm working on the Date assertions, Tomasz Nurkiewicz gave us a lot of
assertions ideas I want to review with you to get the most expressive
assertions names.
As english is not my native langage, I'm not always sure that
assertions methods names are intuitive even if it sounds good to me.

Here's a list of assertion methods with different options, feel free
to comment and suggest new ideas !

A) assert that the actual date is on a given year
- A1 : assertThat(myDate).isOn(year)
- A2 : assertThat(myDate).isWithin(year)
- A3 : assertThat(myDate).isIn(year)

My preference : A1 - A2 - A3
This assertion will be declined with mon, day, hour, ....


B) assert that the actual date is on same year than the given date
- B1 : assertThat(myDate).isOnSameYearThan(otherDate)
- B2 : assertThat(myDate).isOnSameYear(otherDate)
- B3 : assertThat(myDate).isInSameYearThan(otherDate)
- B4 : assertThat(myDate).isInSameYear(otherDate)

My preference : B1 - B2 - B3 - B4
This assertion will be declined with mon, day, hour, ....


C) assert that the actual date is equal to another with a tolerance
- C1 : assertThat(myDate).isCloseTo(otherDate, delta) // delat in ms
- C2 : assertThat(myDate).isEqualTo(otherDate, delta) // delat in ms

I have a little preference for C1 as I find it more expressive than C2
but C2 has the advantage of following Fest standard (see FloatAssert)
- no strong opinion here.

Regards,

Joel

[Ansgar Konermann]

Hi Joel, hi all,

great news the date assertions are making progress.

Do you plan to implement these assertions based on standard
java.util.Date or will they also work for Joda Time? Plus, will we also
get isBefore() and isAfter()?

Other comments inline:

On 07.02.2011 21:23, Joel Costigliola wrote:
> A) assert that the actual date is on a given year
> - A1 : assertThat(myDate).isOn(year)
> - A2 : assertThat(myDate).isWithin(year)
> - A3 : assertThat(myDate).isIn(year)
>
> My preference : A1 - A2 - A3
>

My vote: A2

> This assertion will be declined with mon, day, hour, ....
>

Does this mean we will have...

* assertThat(myDate).isWithin(month)
* assertThat(myDate).isWithin(day)
* assertThat(myDate).isWithin(hour)

...or am I getting you wrong?

How can these work without a dedicated type for month, day and hour? If
we use type int for month day and hour here, we'll get compilation errors.

> B) assert that the actual date is on same year than the given date
> - B1 : assertThat(myDate).isOnSameYearThan(otherDate)
> - B2 : assertThat(myDate).isOnSameYear(otherDate)
> - B3 : assertThat(myDate).isInSameYearThan(otherDate)
> - B4 : assertThat(myDate).isInSameYear(otherDate)
>

My suggestion here: isInSameYearAs(otherDate)

> C) assert that the actual date is equal to another with a tolerance
> - C1 : assertThat(myDate).isCloseTo(otherDate, delta) // delat in ms
> - C2 : assertThat(myDate).isEqualTo(otherDate, delta) // delat in ms
>
> I have a little preference for C1 as I find it more expressive than C2
> but C2 has the advantage of following Fest standard (see FloatAssert)
> - no strong opinion here.
>

Some more suggestions:

assertThat(myDate).isCloserTo(otherDate).than(delta)
assertThat(myDate).isAtMost(delta).awayFrom(otherDate)

If this is deemed too complicated, I'd also vote for C2 (for consistency
with FloatAssert).

The definition of "delta" to be in milliseconds seems to be a bit random
to me. I'm quite sure a user will come up with a lot of use cases where
he wants to check for deltas in the hour / days range. Speaking purely
about API design (implementation later), what do you think about:

assertThat(myDate).isAtMost(2, months()).awayFrom(otherDate) or even
assertThat(myDate).isAtMost(2).months().awayFrom(otherDate)

I'm not sure if "awayFrom" is the best term here, as it has a more
spatial meaning (at least to me), whereas in our example, we should
preferr terms with a strong temporal association.

Looking forward to your comments.

Best regards

Ansgar

[Alex Ruiz]

Hey Joel & all,

I'd like to propose to wait a little bit on assertions for dates.
AFAIK, Ted had a patch ready for this functionality. I know he is
pretty busy lately, so let's wait to sync with him.

In addition, I'm almost done with FEST-Assert 2.x prototype. It took
some time because the more I was adding functionality, the better I
understood what IMHO I think is quite ugly in 1.x :D ...I'd like to
kindly ask you to please wait for 2.x too. If we all agree that the
2.x is good to move forward, we can start adding new stuff to this
branch (actually is a completely separate project.)

One last thing, I think we are 100% ready for FEST-Assert 1.4 release.
If everybody is OK with it, I think we can release on Feb 15th.

WDYT?

Thanks!
-Alex

> --
> You received this message because you are subscribed to the Google Groups
> "easytesting-dev" group.
> To post to this group, send email to easytes...@googlegroups.com.
> To unsubscribe from this group, send email to
> easytesting-d...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/easytesting-dev?hl=en.
>
>

[Joel Costigliola]

I was planning to implement these assertions based on standard
java.util.Date, including basic assertions I haven't mentionned :
- isAfter/isBefore
- isAfterOrEquals/isBeforeOrEquals
- isBetween/isNotBetween

> > A) assert that the actual date is on a given year
> > - A1 : assertThat(myDate).isOn(year)
> > - A2 : assertThat(myDate).isWithin(year)
> > - A3 : assertThat(myDate).isIn(year)
>
> > My preference : A1 - A2 - A3
>
> My vote: A2
> > This assertion will be declined with mon, day, hour, ....
>
> Does this mean we will have...
>
> * assertThat(myDate).isWithin(month)
> * assertThat(myDate).isWithin(day)
> * assertThat(myDate).isWithin(hour)
>
> ...or am I getting you wrong?
>
> How can these work without a dedicated type for month, day and hour? If
> we use type int for month day and hour here, we'll get compilation errors.

Good point, I actually made a little mistake writing this post,
following your preference, the code would look like :
- assertThat(myDate).isWithinMonth(month)
- assertThat(myDate).isWithinDay(day)
- assertThat(myDate).isWithinHour(hour)

> > B) assert that the actual date is on same year than the given date
> > - B1 : assertThat(myDate).isOnSameYearThan(otherDate)
> > - B2 : assertThat(myDate).isOnSameYear(otherDate)
> > - B3 : assertThat(myDate).isInSameYearThan(otherDate)
> > - B4 : assertThat(myDate).isInSameYear(otherDate)
>
> My suggestion here: isInSameYearAs(otherDate)

that sounds good to me.

> > C) assert that the actual date is equal to another with a tolerance
> > - C1 : assertThat(myDate).isCloseTo(otherDate, delta) // delat in ms
> > - C2 : assertThat(myDate).isEqualTo(otherDate, delta) // delat in ms
>

> Some more suggestions:
>
> assertThat(myDate).isCloserTo(otherDate).than(delta)
> assertThat(myDate).isAtMost(delta).awayFrom(otherDate)
>
> If this is deemed too complicated, I'd also vote for C2 (for consistency
> with FloatAssert).

"isCloserTo" does not sound natural to me, I prefer "isAtMost"
suggestion.

> The definition of "delta" to be in milliseconds seems to be a bit random
> to me. I'm quite sure a user will come up with a lot of use cases where
> he wants to check for deltas in the hour / days range. Speaking purely

I was thinking that user could rely on TimeUnit, for example, to
express 10 seconds in milliseconds one can write :
TimeUnit.SECONDS.toMillis(10)
With a static import, we can make this assertion :
assertThat(myDate).isEqualTo(otherDate, SECONDS.toMillis(10))

But TimeUnit is not a really known API, we can overcome this problem
by giving examples in the javadoc.

> about API design (implementation later), what do you think about:
>
> assertThat(myDate).isAtMost(2, months()).awayFrom(otherDate) or even
> assertThat(myDate).isAtMost(2).months().awayFrom(otherDate)
>
> I'm not sure if "awayFrom" is the best term here, as it has a more
> spatial meaning (at least to me), whereas in our example, we should
> preferr terms with a strong temporal association.

I like the idea, it is human readable even for my poor english
level ;-)
I find "isEqualTo(otherDate, delta)" more straightforward - direct
method call is sufficient
We could offer both so that users can choose the version they prefer.

[Joel Costigliola]

On Feb 8, 10:54 pm, Alex Ruiz <alex.ruiz...@gmail.com> wrote:
> Hey Joel & all,
>
> I'd like to propose to wait a little bit on assertions for dates.
> AFAIK, Ted had a patch ready for this functionality. I know he is
> pretty busy lately, so let's wait to sync with him.

I didn't know there was a patch from Ted, let's sync with him.
We could then complete his work based on Tomasz Nurkiewicz
suggestions.

When do you think Ted could share his patch with us ?

>
> In addition, I'm almost done with FEST-Assert 2.x prototype. It took
> some time because the more I was adding functionality, the better I
> understood what IMHO I think is quite ugly in 1.x :D ...I'd like to
> kindly ask you to please wait for 2.x too. If we all agree that the
> 2.x is good to move forward, we can start adding new stuff to this
> branch (actually is a completely separate project.)

that is ok to me, can we contribute to 2.x right now ?

>
> One last thing, I think we are 100% ready for FEST-Assert 1.4 release.
> If everybody is OK with it, I think we can release on Feb 15th.
>
> WDYT?

Good news ! :)
I'm really waiting for this release at work because it will be much
easier to implements custom assertions !

>
> Thanks!
> -Alex
>
> On Tue, Feb 8, 2011 at 1:25 PM, Ansgar Konermann
>