Skip to content

Commit

Permalink
docs: Receive(POINTER, MATCHER)
Browse files Browse the repository at this point in the history
Signed-off-by: thediveo <[email protected]>
  • Loading branch information
thediveo authored and onsi committed Apr 18, 2024
1 parent ec1f186 commit 02e8706
Showing 1 changed file with 9 additions and 1 deletion.
10 changes: 9 additions & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -877,7 +877,7 @@ Finally, as a corollary: it is an error to check whether or not a send-only chan
#### Receive()

```go
Ω(ACTUAL).Should(Receive(<optionalPointer>))
Ω(ACTUAL).Should(Receive(<optionalPointer>, <optionalMatcher>))
```

succeeds if there is a message to be received on actual. Actual must be a channel (and cannot be a send-only channel) -- anything else is an error.
Expand Down Expand Up @@ -930,6 +930,14 @@ Eventually(bagelChan).Should(Receive(&receivedBagel))

Of course, this could have been written as `receivedBagel := <-bagelChan` - however using `Receive` makes it easy to avoid hanging the test suite should nothing ever come down the channel. The pointer can point to any variable whose type is assignable from the channel element type, or if the channel type is an interface and the underlying type is assignable to the pointer.

Sometimes, you might need to *grab* the object that *matches* certain criteria:

```go
var receivedBagel Bagel
Eventually(bagelChan).Should(Receive(&receivedBagel, HaveField("Kind", "sesame")))
Ω(receivedBagel.Contents()).Should(ContainElement("cream cheese"))
```

Finally, `Receive` *never* blocks. `Eventually(c).Should(Receive())` repeatedly polls `c` in a non-blocking fashion. That means that you cannot use this pattern to verify that a *non-blocking send* has occurred on the channel - [more details at this GitHub issue](https://github.com/onsi/gomega/issues/82).

#### BeSent(value interface{})
Expand Down

0 comments on commit 02e8706

Please sign in to comment.