Implement 'runTest' that waits for asynchronous completion

[dkhalanskyjb]

Implement a multiplatform runTest as an initial implementation of #1996.

The new runTest also waits for asynchronous completion, which makes this a fix for a long-standing issue.
Fixes #1204
Fixes #1222
Fixes #1395
Fixes #1881
Fixes #1910
Fixes #1365 (though there may be some other use cases that this solution doesn't cover)
Fixes #1772

[qwwdfsad]

Do we still need this one if #3006 gets merged?

[dkhalanskyjb]

It has its uses. People also create dispatchers in advance to perform DI.

In any case, this method looks fairly benign and doesn't hurt anything, so a more important question is whether we need TestCoroutineScope.runTest, which presupposes that we provide ways to create TestCoroutineScope. If we don't, then this convenience method can also go.

[qwwdfsad]

Let's make this decision in the final branch along with the migration guide.

I still believe TestCoroutineScope.runTest may be useful for the examples like this one:

@Before 
fun before() {
    myScope = TestCoroutineScope(...)
    myEntity = MyEntity(..., myScope)
}

@Test
fun scenario1() = myScope.runTest {
    myEntity.foo()
    testScheduler.advanceUntilIdle()
    verifyFoo()
}

@Test
fun scenario2() = myScope.runTest {
    myEntity.bar()
    testScheduler.advanceUntilIdle()
    verifyBar()
}

Maybe TestDispatcher.runTest has the same uses, I was thinking of removing it for the sake of keeping API compact -- it's easily emulated with runTest(dispatcher) and only provides one more method to be aware of/to study.

[dkhalanskyjb]

I should note that the scope inside myScope.runTest { ... } is not the same thing as myScope, which may reduce the usefulness of the pattern.

Also, this code is missing a

@AfterTest
fun after() {
  myScope.cleanupTestCoroutines()
}

I think this is a major point. According to the comments at the bottom of https://youtrack.jetbrains.com/issue/KT-19813, AfterTest and BeforeTest don't properly allow returning a Promise, which means that either

• the cleanup procedure also can't return a TestResult, or
• we shouldn't promote cleaning up in AfterTest, but then we'll also have to avoid promoting initializing scopes in BeforeTest for symmetry.

[qwwdfsad]

Mentioning the scope/dispatcher and the ability to wait until all tasks are executed is valuable for this API and worth mentioning:

@Test
fun exampleTest() = runTest {
    val myComponent = MyComponent(this) // TODO: can't extract dispatcher here
    myComponent.executeAsyncOp()
    testScheduler.advanceUntilIdle()
    verifyAsyncOpCompleted()
}

I do not insist though, but it seems pretty important, WDYT?

[dkhalanskyjb]

Ok, added a mention of this.