Date API Proposal

[thiagodp]

Feature Request

Description:
API for Date matchers. Some matchers are inspired by Jasmine Matchers.

Possible solution:

Jasmine-like matchers:

expect(date).toBeDate(); // Matcher added
expect(date).toBeValidDate();  // Matcher added

expect(date).toBeAfter(otherDate); // Matcher added
expect(date).toBeBefore(otherDate); // Matcher added

expect(object).toHaveDate(memberName);
expect(object).toHaveDateAfter(memberName, date);
expect(object).toHaveDateBefore(memberName, date);

Additional matchers:

expect(date).toBeAfterOrEqualTo(otherDate); // or toBeGreaterThanOrEqualTo
expect(date).toBeBeforeOrEqualTo(otherDate); // or toBeLessThanOrEqualTo
expect(date).toBeBetween(startDate, endDate);
expect(date).toDiffInDays(otherDate, days); // e.g., expect( '12/25/2018' ).toDiffInDays( '12/24/2018', 1 );

expect( date ).toHaveDay( day );
expect( date ).toHaveMonth( month );
expect( date ).toHaveYear( year );

[mattphillips]

Nice one @thiagodp I like these a lot! Fancy sending a PR for any of them? 😄

[thiagodp]

Hello @mattphillips ,
added #118 with toBeDate(). It's a first step, but I'll try to add more soon.

[CoreyKovalik]

I believe the following shouldn't pass, since 0 value unix codes are common bugs

This currently passes, but I believe should fail:

expect(new Date(0)).toBeValidDate()

That or add matchers to test valid/recent unix, so we can avoid code like this to test timestamps were created on a resource:

expect(someUnixTimestamp)
    .toBeNumber()
    .toBeLessThan(Date.now())
    .toBeGreaterThan(Date.now() - 5000)
    .not.toEqual(0)

[thiagodp]

Hi @CoreyKovalik, I think I disagree with you about 0 to be an invalid value. The Date API defines that argument as "an integer value that is the number of milliseconds since 1 January 1970 UTC". So, there is nothing wrong with it.

Whether an application could not accept it in order to avoid some kind of problem, a programmer should document that with a test case. However, the (Jest-extended) library should allow it, since it is an acceptable value for a Date.

[CoreyKovalik]

@thiagodp Was thinking along the lines of the same thing. Would be nice to have a similar set of matchers for Unix timestamps

[thiagodp]

@CoreyKovalik yes, it would be useful to have such matchers

[dandv]

I'd like to propose a match for a timestamp being "within the last X ms". This is useful, for example, when testing that files like "createdAt" or "updatedAt" were properly updated within about the timestamp of the text.

I'm currently using

expect(Date.now() - object.updatedAt).toBeLessThan(10 * 1000);

Proposed matcher:

expect(object).toMatchObject({
  // ...
  updatedAt: expect.withinLast('10s'),
});

[RobertFischer]

Anyone working on this? @thiagodp @mattphillips @CoreyKovalik ? If not, my work (@k4connect) is giving me some time to get these in, since they'd be useful for us.

[hansal7014]

Hi All,
I am new to open source development and would like to work on the 'toBeBetween' matcher. I can start working on this feature unless somebody is already working on it.
Thanks.

[CoreyKovalik]

@RobertFischer, @hansal7014,

I'm not working on any of these currently, but I can share what pattern I've been using as a solution in production tests.

const now = Date.now()
const response = fooFunctionToTest()
const nowDelta = Date.now() - now

expect(response.timestamp).toBeGreaterThanOrEqual(now)
expect(response.timestamp).toBeLessThanOrEqual(now + nowDelta)

It's been working for me for testing side effects in integration tests for values such as createdAt and updatedAt

I secure this further with validating timestamps by extending Joi as well.

const joiUnixTimestamp = (joi) => ({
    name: 'unixTimestamp',
    base: joi
        .number()
        .integer()
        .min(0),
})

[thiagodp]

Hi { @RobertFischer , @hansal7014 , @CoreyKovalik }, I'm not working on any of these either.

Suggetion (@hansal7014 ): toBeBetween(startDate, endDate) could be defined as toBeAfterOrEqualTo(startDate) and toBeBeforeOrEqualTo(endDate).

[hansal7014]

Hi @thiagodp @CoreyKovalik,

I'll start working on these matchers. Thanks for the suggestions.

[JamieMason]

Hi @thiagodp,
A newer typescript version of Jasmine Matchers is at expect-more-jasmine and there is also a version for Jest is at expect-more-jest. Some of the date matchers discussed here are featured there, feel free to take them if there is anything useful there.

[thiagodp]

Nice, @JamieMason.
Good work, @SimenB !