Skip to content

docs: clarify EventuallyWithT goroutine and FailNow behavior#1919

Open
jfjrh2014 wants to merge 1 commit into
stretchr:masterfrom
jfjrh2014:docs/eventuallywitht-goroutine-behavior
Open

docs: clarify EventuallyWithT goroutine and FailNow behavior#1919
jfjrh2014 wants to merge 1 commit into
stretchr:masterfrom
jfjrh2014:docs/eventuallywitht-goroutine-behavior

Conversation

@jfjrh2014

Copy link
Copy Markdown

Summary

The EventuallyWithT condition function runs in its own goroutine for each tick, but this was not documented. This PR clarifies what that means for users.

Problem

As discussed in #1396, users naturally expect they can call require assertions on the outer *testing.T from within the condition function. This is unsafe because testing.T.FailNow must be called from the goroutine that created the test (t.Run).

Additionally, the behavior of CollectT.FailNow (that it terminates only the current tick and not the test) was not documented on EventuallyWithT itself.

Changes

EventuallyWithT — Added two paragraphs documenting that:

  1. The condition function runs in its own goroutine per tick, so FailNow on the outer *testing.T is unsupported; the provided CollectT should be used instead.
  2. CollectT.FailNow terminates only the current tick's condition function, not EventuallyWithT retries or test execution.

CollectT.FailNow — Expanded the one-line doc to explain it marks CollectT as failed and cross-references EventuallyWithT.

The docs are written in prose first (no inline code snippets) per @brackendawson's feedback, and use Godoc link syntax ([CollectT.FailNow], [testing.T.FailNow]) so they render correctly in both the assert and generated require packages.

No behavioral changes. All existing tests pass.

Closes #1396

The EventuallyWithT condition function runs in its own goroutine per tick,
but this was not documented. Users naturally expect they can call require
assertions on the outer testing.T, but testing.T.FailNow must be called from
the goroutine that created the test. Document this constraint and clarify what
CollectT.FailNow actually terminates (the current tick, not the test).

Also improves FailNow doc to cross-reference EventuallyWithT.

Addresses stretchr#1396
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve the behavior of require assertions when using assert.EventuallyWithT

1 participant