testing/synctest: add Sleep

Add a convenience function which combines time.Sleep and synctest.Wait.

Fixes #77169

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

diff --git a/api/next/77169.txt b/api/next/77169.txt
new file mode 100644 (file)
index 0000000..0d4ed86
--- /dev/null
+++ b/api/next/77169.txt
@@ -0,0 +1 @@
+pkg testing/synctest, func Sleep(time.Duration) #77169

diff --git a/doc/next/6-stdlib/99-minor/testing/synctest/77169.md b/doc/next/6-stdlib/99-minor/testing/synctest/77169.md
new file mode 100644 (file)
index 0000000..b214a5d
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/testing/synctest/77169.md
@@ -0,0 +1 @@
+The new [Sleep] helper function combines [time.Sleep] and [testing/synctest.Wait].

diff --git a/src/testing/synctest/synctest.go b/src/testing/synctest/synctest.go
index 9f499515b8881ad2c17704be4a4cda508485f0a2..f254d561c7b51f1f709cd19435f109871a421201 100644 (file)
--- a/src/testing/synctest/synctest.go
+++ b/src/testing/synctest/synctest.go
@@ -268,6 +268,7 @@ package synctest
 import (
        "internal/synctest"
        "testing"
+       "time"
        _ "unsafe" // for linkname
 )
 
@@ -309,3 +310,23 @@ func testingSynctestTest(t *testing.T, f func(*testing.T)) bool
 func Wait() {
        synctest.Wait()
 }
+
+// Sleep blocks until the current bubble's clock has advanced
+// by the duration of d and every goroutine within the current bubble,
+// other than the current goroutine, is durably blocked.
+//
+// This is exactly equivalent to
+//
+//     time.Sleep(d)
+//     synctest.Wait()
+//
+// In tests, this is often preferable to calling only [time.Sleep].
+// If the test itself and another goroutine running the system under test
+// sleeps for the exact same amount of time, it's unpredictable which
+// of the two goroutines will run first. The test itself usually wants
+// to wait for the system under test to "settle" after sleeping.
+// This is what Sleep accomplishes.
+func Sleep(d time.Duration) {
+       time.Sleep(d)
+       Wait()
+}