From 2d3822ad5ee344dc9d177e130e1339b08a03c948 Mon Sep 17 00:00:00 2001
From: Lenz Weber-Tronic <lorenz.weber-tronic@apollographql.com>
Date: Fri, 11 Oct 2024 16:39:49 +0200
Subject: [PATCH] document matchers

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 6a3c018c5..b97a181bc 100644
--- a/README.md
+++ b/README.md
@@ -241,6 +241,47 @@ test('assertions in `onRender`', async () => {
 > passed into `onRender` of React's `Profiler` component, as well as `snapshot`,
 > `replaceSnapshot` and `mergeSnapshot`
 
+### `expect(...)[.not].toRerender()` and `expect(...)[.not].toRenderExactlyTimes(n)`
+
+This library adds to matchers to `expect` that can be used like
+
+```tsx
+test('basic functionality', async () => {
+  const {takeRender} = renderToRenderStream(<RerenderingComponent />)
+
+  await expect(takeRender).toRerender()
+  await takeRender()
+
+  // trigger a rerender somehow
+  await expect(takeRender).toRerender()
+  await takeRender()
+
+  // ensure at the end of a test that no more renders will happen
+  await expect(takeRender).not.toRerender()
+  await expect(takeRender).toRenderExactlyTimes(2)
+})
+```
+
+These matchers can be used on multiple different objects:
+
+```ts
+await expect(takeRender).toRerender()
+await expect(renderStream).toRerender()
+await expect(takeSnapshot).toRerender()
+await expect(snapshotStream).toRerender()
+```
+
+> [!NOTE]
+>
+> By default, `.toRerender` and `toRenderExactlyTimes` will wait 100ms for
+> renders or to ensure no more renders happens.
+>
+> You can modify that with the `timeout` option:
+>
+> ```js
+> await expect(takeRender).not.toRerender({timeout: 300})
+> ```
+
 ## A note on `act`.
 
 You might want to avoid using this library with `act`, as `act`