add `await.Require` and `await.RequireTrue` by stephanos · Pull Request #9490 · temporalio/temporal

stephanos · 2026-03-12T00:07:21Z

What changed?

Introduces common/testing/await, a polling-based test helper that replaces testify's Eventually / EventuallyWithT.

Why?

From the package doc:

Improvements over testify's eventually functions:

   - Misuse detection: accidentally using the real *testing.T (e.g. s.T() or
     suite assertion methods) instead of the callback's collect T is a
     common mistake. This package detects it and fails with a clear message.

   - Safer bool predicates: unlike testify's Eventually, [RequireTrue] only
     accepts func() bool, so returning false is the sole retry signal. If the
     predicate accidentally marks the real test failed, it reports that
     immediately instead of polling until timeout.

   - Timeout-aware callbacks: callbacks receive a context derived from the
     parent context and canceled when the await timeout or test deadline is
     reached, so RPCs and blocking waits can exit instead of continuing after
     the retry window has expired.

   - Panic propagation: if the condition panics (e.g. nil dereference), the
     panic is propagated immediately rather than being silently swallowed
     or retried until timeout.
     See https:github.com/stretchr/testify/issues/1810

   - Bounded goroutine lifetime: each attempt completes before the next
     starts, avoiding the overlapping-attempt data races and "panic: Fail
     in goroutine after Test has completed" crashes seen with testify's
     Eventually.
     See https:github.com/stretchr/testify/issues/1611

   - Deadlock detection: a condition that ignores t.Context() is abandoned
     after a grace period, producing a clear "does it honor t.Context()?"
     failure instead of hanging until go test -timeout.

   - Condition always runs: testify's Eventually can fail without ever
     running the condition due to a timer/ticker race with short timeouts.
     This package runs the condition immediately on the first iteration.
     See https://github.com/stretchr/testify/issues/1652

The upstream fix (testify#1657) aims to address several of these but has been open since Oct 2024 without merging.

How did you test it?

Potential risks

The biggest downside is that it adds more code that we own. But apart from any unknown bugs, this package should rarely/never change.

stephanos · 2026-05-03T21:45:35Z

+		s.NoError(descErr)
+		s.NotNil(desc)
+		s.NotNil(desc.GetPendingWorkflowTask())
 	}, 5*time.Second, 250*time.Millisecond, "speculative WFT should be scheduled after sending update")


^ Await example

stephanos · 2026-05-11T17:38:43Z

+        - pattern: '(^|\.)(Eventually|Eventuallyf|EventuallyWithT|EventuallyWithTf)(\(|$)'
+          msg: "Use await.Require / s.Await for assertion conditions, or await.RequireTrue / s.AwaitTrue for bool predicates, instead of testify Eventually helpers"


Require new code to use new Await

stephanos · 2026-05-11T18:04:16Z

+	s.AwaitTrue(func() bool {
 		// wait for workflow task to fail 3 times
 		return atomic.LoadInt32(&failures) >= 3
 	}, 10*time.Second, 50*time.Millisecond)


^ AwaitTrue example

stephanos · 2026-05-11T22:55:45Z

+```go
+s.Await(func(s *MySuite) {
+    resp, err := client.GetStatus(s.Context())


This is the sleekest way I can imagine doing this.

stephanos · 2026-05-11T22:58:45Z

 				Execution: wfExecution,
 			})
-		return descErr == nil && desc.GetPendingWorkflowTask() != nil
+		s.NoError(descErr)


I think this will completely eliminate a lot of "using the wrong t" issues.

stephanos · 2026-05-11T22:59:35Z

-	s.Eventually(func() bool {
-		desc, descErr := env.FrontendClient().DescribeWorkflowExecution(testcore.NewContext(),
+	s.Awaitf(func(s *PrematureEosTestSuite) {
+		desc, descErr := env.FrontendClient().DescribeWorkflowExecution(s.Context(),


What I like about this is that s.Context() is the same in and outside the block; but it will resolve to the right context.

stephanos · 2026-05-12T16:50:09Z

+	Errorf(string, ...any)
+	Fatal(...any)
+	Fatalf(string, ...any)
 }


^ using interface so it doesn't require concrete testing.T

type TB interface { testing.TB }

To simplify

spkane31 · 2026-05-12T22:51:03Z

+	Errorf(string, ...any)
+	Fatal(...any)
+	Fatalf(string, ...any)
 }


type TB interface { testing.TB }

To simplify

spkane31 · 2026-05-12T22:56:02Z

@@ -0,0 +1,39 @@
+// Package await provides polling-based test assertions as a replacement


This should be in a doc.go file

I've seen both approaches (doc.go and same name as package), but happy to move it to doc.go

spkane31 · 2026-05-14T16:04:52Z

+	initSuite(t *testing.T, assertT require.TestingT, ctx contextOverride)
+}
+
+type contextOverride struct {


Is this necessary? I only see it used in initSuite to set the passed in ctx.

spkane31 · 2026-05-14T16:06:31Z

+	tb.Helper()
+	run(testcontext.New(tb), tb, func(t *T) {
+		if !condition() {
+			t.failed = true


There is a t.Failed() func, could use that or remove that func.

spkane31 · 2026-05-14T16:31:45Z

+		if !condition() {
+			t.failed = true
+		}
+	}, timeout, pollInterval, "", "await.RequireTrue", requireTrueMisuseHint, false)


The name "await.RequireTrue" is not piped in by the functions that call RequireTrue so it will always show up as await.RequireTrue

spkane31 · 2026-05-14T16:32:44Z

+	if s.ctx != nil {
+		return s.ctx
+	}
+	return testcontext.New(s.T())


This should set s.ctx so we can avoid the mutex lock/unlock on every call to s.Context()

There could be a race between the test and a await/regular goroutine, though, both calling s.Context() which would likely create a data race warning and fail the test. But I can add a sync.Once to only call testcontext.New at most once.

stephanos changed the title ~~use require over assert~~ better eventually Mar 12, 2026

stephanos force-pushed the stephanos/all-require branch 29 times, most recently from 7d3afac to 4e042ac Compare March 12, 2026 16:39

stephanos force-pushed the stephanos/all-require branch 8 times, most recently from 7624541 to 1814d82 Compare May 3, 2026 21:44

temporalio deleted a comment from semgrep-managed-scans Bot May 3, 2026

stephanos commented May 3, 2026

View reviewed changes

stephanos force-pushed the stephanos/all-require branch 4 times, most recently from 3343e44 to 96a2172 Compare May 5, 2026 15:15

stephanos commented May 11, 2026

View reviewed changes

stephanos commented May 12, 2026

View reviewed changes

better eventually

9968cd8

spkane31 approved these changes May 14, 2026

View reviewed changes

stephanos added 7 commits May 15, 2026 11:44

doc.go

ff8a0e3

use testing.TB

70dcafe

use t.Fail()

fc8fe76

drop prefix

7898741

drop contextOverride

d44c410

fix lint

d048057

sync.Once

0cde661

		- pattern: '(^\|\.)(Eventually\|Eventuallyf\|EventuallyWithT\|EventuallyWithTf)(\(\|$)'
		msg: "Use await.Require / s.Await for assertion conditions, or await.RequireTrue / s.AwaitTrue for bool predicates, instead of testify Eventually helpers"

		@@ -0,0 +1,39 @@
		// Package await provides polling-based test assertions as a replacement

Conversation

stephanos commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed?

Why?

How did you test it?

Potential risks

Uh oh!

stephanos May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanos May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stephanos commented Mar 12, 2026 •

edited

Loading

stephanos May 3, 2026 •

edited

Loading

stephanos May 11, 2026 •

edited

Loading