feat(TestScheduler): add an animate "run mode" helper

[cartant]

Description:

This PR:

• Adds a Date timestamp provider.

• Adds a performance timestamp provider.

• Adds a requestAnimationFrame provider.

• All providers have delegate properties that are undefined by default but are used - by TestScheduler#run - to override the default behaviour. This mirrors the delegate implementation detail that's used with the schedulers.

• Removes the arrow function from the static Scheduler.now - it's unnecessary, as the Date.now call now occurs within the dateTimestampProvider.

• The animationFrames observable now uses the requestAnimationFramesProvider.

• TestScheduler#run sets the delegates for the providers, with the requestAnimationFramesProvider's delegate working in conjunction with a animate() marble that's added to the run helpers:

  testScheduler.run(({ animate }) => {
    animate('---x---x---x---x---x');
    /* ... */
  });

  Each time an animation/repaint occurs, all queued rAF callbacks will be executed - in the order in which they were scheduled - and each will be passed the same timestamp - the TestScheduler's now value - which is also what will be returned from the timestamp providers - as the TestScheduler itself is the delegate.

• Adds tests for the animate run helper.

• Updates API guardian for the inclusion of the animate run helper.

• Reimplements the animationFrames tests to use the run helper and the provider - which is spied upon - and removes the rAF mock.

• Fixes the rAF provider so that cancellation of already fulfilled requests (upon unsubscription) is not attempted.

Related issue (if exists): #5438 and #5475

[benlesh]

FIRST: I've rarely been as excited about a change to this part of the code. This is pretty much the best addition since "run mode".

Just a few very minor things.

[cartant]

@benlesh I'll make those changes and will then add some docs - I was holding off on documenting it until it had been reviewed.

[cartant]

@benlesh I've made some changes:

• I've changed the name of the repaints run helper to animate.
• I've moved the delegate and the run helper implementation into a createAnimator method. This is more consistent with the current implementation. FWIW, I'm not keen on making animate a method that needs to be bound to this and needs member properties, etc.
• I've added a TSDoc comment to run - there was no existing comment/documentation - and I've linked it to an updated marble testing guide.

ATM, the documentation in the guide is a little light, but I think it's enough, for now. Once this PR is merged, I am going to:

• rebase and fix up the PR that adds the timestamp and elapsed properties to the animationFrames observable's value.
• look at removing/refactoring the delegate that's in AsyncScheduler, as I think it ought to be possible to add setInterval and setImmediate providers (and delegates). Doing that would allow for tests to actually use all of the schedulers within 'run mode'. ATM, they are bypassed and there is no way to write a test in which AsyncScheduler tasks are executed after subsequently-scheduled AsapScheduler tasks - i.e. there is no differentiation between virtual micro and macro tasks in the TestScheduler. The change would also mean that the AnimationFrameScheduler would work with the animate run helper.

If the docs need more work, I can look at them after I've done the above. Or someone else can do it.

[benlesh]

Nice work, @cartant! I'm very pleased to see this land!