testing/synctest: call out common issues with tests

While each point is explained their respective sections for Time,
Blocking, and Isolation, these appear to be the most common
issues worth calling out up front.

Fixes #75052

Change-Id: I916b559075ee4d1d23810a08459e037e21690193
Reviewed-on: https://go-review.googlesource.com/c/go/+/696736
Auto-Submit: Damien Neil <dneil@google.com>
Reviewed-by: Damien Neil <dneil@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>

diff --git a/src/testing/synctest/synctest.go b/src/testing/synctest/synctest.go
index ff88c3ec42a98107631c0f9cec50cd8be45fff55..707383f9c754990c4e77dd9ac52dd09ff8439034 100644 (file)
--- a/src/testing/synctest/synctest.go
+++ b/src/testing/synctest/synctest.go
@@ -7,6 +7,14 @@
 // The [Test] function runs a function in an isolated "bubble".
 // Any goroutines started within the bubble are also part of the bubble.
 //
+// Each test should be entirely self-contained:
+// The following guidelines should apply to most tests:
+//
+//   - Avoid interacting with goroutines not started from within the test.
+//   - Avoid using the network. Use a fake network implementation as needed.
+//   - Avoid interacting with external processes.
+//   - Avoid leaking goroutines in background tasks.
+//
 // # Time
 //
 // Within a bubble, the [time] package uses a fake clock.