setSystemTime and getRealSystemTime type and doc update

[liamfd]

Summary

This PR does two (related) things.

Update setSystemTime now param types to allow Date

The internal types for setSystemTime are currently now?: number, but in using jest I found passing a Date also worked and was a bit more ergonomic in some cases. For example:

    // if Date is not in the union, this errors:
    jest.setSystemTime(new Date('2020-06-15T00:00:00.933Z'));
    
    // you'd have to do:
    jest.setSystemTime(new Date('2020-06-15T00:00:00.933Z').getTime());

The types for the underlying this._clock.setSystemTime call in jest-fake-timers/src/modernFakeTimers.ts support Date, so echoing that in setSystemTime seemed reasonable. I was looking into this while working on a PR to add types for setSystemTime and getRealSystemTime to DefinitelyTyped, and wanted to make sure that those types matched jest's codebase's types and the intended usage.

Update setSystemTime and getRealSystemTime docs

1. The documentation for setSystemTime did not directly document its params, so they took me as a user a bit of time to figure out. I wasn't sure what the format for these should be. advanceTimersToNextTimer just has jest.advanceTimersToNextTimer(steps) (no types), whereas useFakeTimers has jest.useFakeTimers(implementation?: 'modern' | 'legacy'). I erred on the side of adding a type to the param, the union members are native and I think the types would be useful to both js and ts folks.
2. The documentation for setSystemTime and getRealSystemTime both have a preceding . char, which I removed. I'm not sure if this was intentional, but the other functions/headers in that doc do not have one and I didn't see any reference to them being experimental or anything (aside from requiring the "modern" timers).

Test plan

For the new type, I added test cases for setSystemTime(now: Date) wherever I saw test cases for setSystemTime(now: number). I ran the tests locally (albeit without mercurial installed, which didn't seem to affect these particular files).

I took a look at the doc changes to make sure they looked alright. They look like:

Whereas on the live site, they look like:

[liamfd]

I wasn't sure if Date not being present in the types or the preceding periods were intentional, but I figured I'd err on the side of updating them just in case.

I'm happy to do any cleanup necessary on changes in this PR that aren't desirable.

Also, thanks for these new functions!

[SimenB]

this doesn't use a Date, but a number like above

[liamfd]

🤦 it does indeed, thank you.

[SimenB]

same here

[SimenB]

Thanks! I think this only needs a tweak to the tests and it's good to go 👍

[liamfd]

@SimenB thanks for you review, I've pushed an update to those tests!

[SimenB]

could you update https://github.com/facebook/jest/blob/master/website/versioned_docs/version-26.0/JestObjectAPI.md as well?

[liamfd]

I think I have (or at least, I intended to) here: https://github.com/facebook/jest/pull/10169/files#diff-82d75bb4a1a86113540ea33c2bd6f24d

[SimenB]

Oh, seems I'm blind 😅 Thanks!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.