[docs] Include recommendations of what to use instead of timeouts

[zcorpan]

https://web-platform-tests.org/writing-tests/testharness-api.html#timeouts-in-tests should say what to use instead of timeouts

• events where possible (and the event should ideally be using the same task source as the thing being tested)
• two requestAnimationFrame for things that need a spin of update the rendering steps.

See #20712

[zcorpan]

Also update the reviewer checklist, which currently includes

The test avoids patterns that make it less likely to be stable. In particular, tests should avoid setting internal timeouts, since the time taken to run it may vary on different devices; events should be used instead (if at all possible).

https://web-platform-tests.org/reviewing-tests/checklist.html#script-tests-only

[emilio]

Thanks for filing this!

[svgeesus]

So, what is the recommended way to make a reftest with a delay, without using setTimeout. The tests are not using the testharness, they are just reftests.

Context: I'm porting an animated PNG testsuite to WPT. Most tests just need a 3 to 7 second delay, and the reference includes a static PNG (such as the last frame of the animation, in simple cases). So it doesn't matter exactly when the comparison happens, just that it is after the duration of the animation.

Currently I have

    const el = document.querySelector(".reftest-wait");
    setTimeout(() => {
        el.classList.remove('reftest-wait');
        }, "3000");

Please tell me what I should be doing instead. I'm happy to make a documentation PR to improve this for others, too.

[svgeesus]

Amusingly the one existing APNG test in WPT uses setTimeout.

[svgeesus]

Ah, I see the advice is just to lne whitelist it, for reftests:

• Can step_timeout be used in reftests? #5547

[zcorpan]

@svgeesus yep.