doc: define use case of common.platformTimeout

[notarseniy]

Define use case of common.platformTimeout method in general recommendations on timers. As proposed in #11368.

Feel free to offer grammar fixes :)

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

[Trott]

@nodejs/testing

[mhdawson]

I'm not sure this make sense to me. I can see guidance that says avoid timers but if you have to use one then consider common.platformTimeout. But I don't think its only if the test fails intermittently. We may have tests that just need more time on some platforms (ex arm) and if there is no other way than using a timer then even if the test fails 100% common.platformTimeout() may be the right advice

[notarseniy]

@mhdawson, thanks for reply! Probably i haven't used term 'flaky tests' correctly here (i'm not native speaker :( ). I meant the same thing as you: we should use common.platformTimeout() only in situations when we should use timers and tests are fails on slow platforms (like you said: arm).

You can help me, if you suggest more correct term for this sentence :)

[mhdawson]

Sorry for the late reply, I think the original wording is not too far off, possibly just update to stress only to use timers when necessary:

In the event that there is no reasonable alternative to using a timer, consider using the

[silverwind]

platformTimeout was originally introduced to give ARMv6/v7 buildbots more breathing room on CPU-intensive tests. For example, a full build on a ARMv6 Rasperry Pi 1 takes north of 6 hours to complete, which lead to us estimating those factors.

Related to this is that ARM tests also get a lot more time to complete.

[Trott]

This issue has been inactive for sufficiently long that it seems like perhaps it should be closed. Feel free to re-open (or leave a comment requesting that it be re-opened) if you disagree. I'm just tidying up and not acting on a super-strong opinion or anything like that.