From: Sean Liao <sean@liao.dev>
Date: Sun, 17 Aug 2025 11:29:48 +0000 (+0100)
Subject: testing/synctest: call out common issues with tests
X-Git-Tag: go1.26rc1~998
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=38204e0872;p=gostls13.git

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 ff88c3ec42..707383f9c7 100644
--- 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.