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] 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.