[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 https://github.com/web-platform-tests/wpt/pull/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:

• https://github.com/web-platform-tests/wpt/issues/5547

[zcorpan]

@svgeesus yep.

[rajanarahul93]

Hi @zcorpan ,

I'd like to take on this issue and help improve the documentation to include recommendations for alternatives to timeouts. I plan to address the following:

Explain Alternatives Clearly:

Use event-driven approaches wherever possible, such as leveraging the event tied to the task being tested (e.g., onload, DOMContentLoaded, or custom events). Recommend using requestAnimationFrame for scenarios requiring a spin of rendering steps, ideally using two frames for reliable results. Specific Use Case for Reftests: For cases like reftests with animations (e.g., APNGs), I will:

Highlight when it is acceptable to use step_timeout and include examples. Provide documentation to clarify when to whitelist timeouts, as referenced in #5547. Update Reviewer Checklist: Modify the checklist to guide reviewers on identifying and encouraging stable test patterns.

I'll make sure the examples are easy to understand and align with the current WPT practices. Let me know if you have additional input or preferences before I proceed.

Thanks!

[zcorpan]

@rajanarahul93 sounds good, thanks!

[NAYAMATVISION]

I’d like to work on this issue. Is it still available? Any guidance would be helpful!