Improve TestCoroutineScope

[dkhalanskyjb]

• Add more detailed documentation;
• Move most verification logic from runBlockingTest to
  cleanupTestCoroutines
  Fixes cleanupTestCoroutines does not detect awaiting CompletableDeferred #1749

[qwwdfsad]

I'm okay with the changes in general.
What puzzles me is the overall sense of passing your own job to TestCoroutineScope that does not complete when the scope semantically completes.

Let's not prevent my comment from merging it though, I'll return to it later (it's much easier to review the whole picture again when one has all the details incorporated)

[dkhalanskyjb]

The point of this approach was to avoid breakage with an unclear migration path. It's possible that someone shared a Job among several TestCoroutineScope instances, which would break if we were to complete the passed job on each cleanup.

However, I did not encounter such usage in the wild—in fact, the only instances of someone passing a Job to TestCoroutineScope that I observed were to work around the bug where, before, TestCoroutineScope was constructed without one.

Another approach to fix this particular problem would be to treat the passed job as the parent. However, it could also break some code.

Not much depends on this particular choice, so maybe we can reach a resolution right in this PR.

[qwwdfsad]

Let's keep the things consistent then:

• TestCoroutineScope provides its own job when it's missing from the context or uses the existing ones. It's perfectly consistent with our CoroutineScope() builder (and MainScope())
• runTest coroutine uses the job from the scope as a parent, no matter whether it is the default one or a user-defined one. Also consistent with our builders (e.g. runBlocking or withContext)

[dkhalanskyjb]

Do you mean that, given how unlikely breakage would be, we need to avoid discerning between a user-supplied Job and the one TestCoroutineScope creates on its own?

[qwwdfsad]

Otherwise looks good and is good to go