From 428e670b4900b405bda0bf5acacffc06d905f91e Mon Sep 17 00:00:00 2001
From: natasha <5155395+murfel@users.noreply.github.com>
Date: Mon, 21 Apr 2025 18:34:11 +0100
Subject: [PATCH 1/3] docs: add example for runTest to reiterate that
 structured concurrency rules apply

---
 .../common/src/TestBuilders.kt                | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/kotlinx-coroutines-test/common/src/TestBuilders.kt b/kotlinx-coroutines-test/common/src/TestBuilders.kt
index 57ae3e1150..ac740f7d6c 100644
--- a/kotlinx-coroutines-test/common/src/TestBuilders.kt
+++ b/kotlinx-coroutines-test/common/src/TestBuilders.kt
@@ -69,6 +69,7 @@ public expect class TestResult
  *     // 2
  *     job.join() // the main test coroutine suspends here, so the child is executed
  *     // 4
+ *     // use the results here
  * }
  *
  * @Test
@@ -80,9 +81,32 @@ public expect class TestResult
  *     // 2
  *     testScheduler.advanceUntilIdle() // runs the tasks until their queue is empty
  *     // 4
+ *     // use the results here
  * }
  * ```
  *
+ *
+ * If the results of children coroutines computations are not needed in the runTest scope,
+ * there is no need to wait for children coroutines to finish, they are awaited for automatically
+ * by runTest parent coroutine.
+ * ```
+ * @Test
+ * fun exampleWaitingForAsyncTasks3() = runTest {
+ *     val x = 0
+ *     val y = 1
+ *     // 1
+ *     launch {
+ *         // 3
+ *         assertEquals(0, x)
+ *     }
+ *     launch {
+ *         // 4
+ *         assertEquals(1, y)
+ *     }
+ *     // 2
+ * }  // 5
+ * ```
+ *
  * ### Task scheduling
  *
  * Delay skipping is achieved by using virtual time.

From 6811e6d2a217b93c163c6acd1d3caffccf1ef13d Mon Sep 17 00:00:00 2001
From: natasha <5155395+murfel@users.noreply.github.com>
Date: Tue, 8 Jul 2025 10:10:11 +0100
Subject: [PATCH 2/3] add the same text to the other overload

---
 .../common/src/TestBuilders.kt                | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/kotlinx-coroutines-test/common/src/TestBuilders.kt b/kotlinx-coroutines-test/common/src/TestBuilders.kt
index ac740f7d6c..8b3e2504f0 100644
--- a/kotlinx-coroutines-test/common/src/TestBuilders.kt
+++ b/kotlinx-coroutines-test/common/src/TestBuilders.kt
@@ -85,7 +85,6 @@ public expect class TestResult
  * }
  * ```
  *
- *
  * If the results of children coroutines computations are not needed in the runTest scope,
  * there is no need to wait for children coroutines to finish, they are awaited for automatically
  * by runTest parent coroutine.
@@ -231,6 +230,7 @@ public fun runTest(
  *     // 2
  *     job.join() // the main test coroutine suspends here, so the child is executed
  *     // 4
+ *     // use the results here
  * }
  *
  * @Test
@@ -242,9 +242,31 @@ public fun runTest(
  *     // 2
  *     advanceUntilIdle() // runs the tasks until their queue is empty
  *     // 4
+ *     // use the results here
  * }
  * ```
  *
+ * If the results of children coroutines computations are not needed in the runTest scope,
+ * there is no need to wait for children coroutines to finish, they are awaited for automatically
+ * by runTest parent coroutine.
+ * ```
+ * @Test
+ * fun exampleWaitingForAsyncTasks3() = runTest {
+ *     val x = 0
+ *     val y = 1
+ *     // 1
+ *     launch {
+ *         // 3
+ *         assertEquals(0, x)
+ *     }
+ *     launch {
+ *         // 4
+ *         assertEquals(1, y)
+ *     }
+ *     // 2
+ * }  // 5
+ * ```
+ *
  * ### Task scheduling
  *
  * Delay-skipping is achieved by using virtual time.

From 0f9c45a758e4c9c1dcad9addc8f6c24d55d56192 Mon Sep 17 00:00:00 2001
From: natasha <5155395+murfel@users.noreply.github.com>
Date: Tue, 8 Jul 2025 10:11:39 +0100
Subject: [PATCH 3/3] minor: apply IDE's wording suggestions

---
 kotlinx-coroutines-test/common/src/TestBuilders.kt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/kotlinx-coroutines-test/common/src/TestBuilders.kt b/kotlinx-coroutines-test/common/src/TestBuilders.kt
index 8b3e2504f0..4870ba7f49 100644
--- a/kotlinx-coroutines-test/common/src/TestBuilders.kt
+++ b/kotlinx-coroutines-test/common/src/TestBuilders.kt
@@ -50,8 +50,8 @@ public expect class TestResult
  * }
  * ```
  *
- * The platform difference entails that, in order to use this function correctly in common code, one must always
- * immediately return the produced [TestResult] from the test method, without doing anything else afterwards. See
+ * The platform difference entails that, to use this function correctly in common code, one must always
+ * immediately return the produced [TestResult] from the test method, without doing anything else afterward. See
  * [TestResult] for details on this.
  *
  * The test is run on a single thread, unless other [CoroutineDispatcher] are used for child coroutines.
@@ -211,8 +211,8 @@ public fun runTest(
  * }
  * ```
  *
- * The platform difference entails that, in order to use this function correctly in common code, one must always
- * immediately return the produced [TestResult] from the test method, without doing anything else afterwards. See
+ * The platform difference entails that, to use this function correctly in common code, one must always
+ * immediately return the produced [TestResult] from the test method, without doing anything else afterward. See
  * [TestResult] for details on this.
  *
  * The test is run in a single thread, unless other [CoroutineDispatcher] are used for child coroutines.