testing: documentation: testing.T.Parallel resets time

[joshlf]

The testing package's T.Parallel method resets the time of the test so that it's as if the test starts just before the method returns. The reason for doing this is that it's likely the first call made from the testing function. This is reasonable, but I suggest that this behavior be documented. The source is here.

[rsc]

The reason for resetting the time is that the first time t.Parallel does is block the call until all the other non-parallel tests have completed. You don't want to include those in the time.

Perhaps instead it should pause the timer, not reset it.

[joshlf]

That would probably be more reasonable, but would it constitute a backwards-breaking change?

[rsc]

No, I would not consider s/reset/pause/ a backwards-breaking change. Unless you have a specific scenario in mind?

[joshlf]

I was just thinking of any logic that relies on that functionality - technically backwards-breaking, but very unlikely to occur in practice.

[cespare]

@joshlf it's not exposed by the testing API, so the only way to rely on the test durations is if you're parsing go test output.

[cespare]

I sent a CL to change from resetting the timer to pausing it.

If we do the pause instead, is there any point in documenting it, or does it become sufficiently unsurprising in that case?

[gopherbot]

CL https://golang.org/cl/16989 mentions this issue.

[joshlf]

@cespare In that case I agree that it's not an issue.

[rsc]

Fixed by CL 16989.