From f550c185aab0d4cd9d9af030a62b1e4354a83ec9 Mon Sep 17 00:00:00 2001
From: rinadavidyuk826-sudo <rinadavidyuk826@gmail.com>
Date: Sun, 22 Mar 2026 10:48:48 +0800
Subject: [PATCH] Expand renderIntoDocument migration guidance

---
 src/content/warnings/react-dom-test-utils.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/content/warnings/react-dom-test-utils.md b/src/content/warnings/react-dom-test-utils.md
index 794bb1d11f4..c86b250cf88 100644
--- a/src/content/warnings/react-dom-test-utils.md
+++ b/src/content/warnings/react-dom-test-utils.md
@@ -27,6 +27,7 @@ The React Team recommends migrating your tests to [@testing-library/react](https
 ### ReactDOMTestUtils.renderIntoDocument {/*reactdomtestutilsrenderintodocument*/}
 
 `renderIntoDocument` can be replaced with `render` from `@testing-library/react`.
+Unlike `renderIntoDocument`, `render` gives you access to the rendered container and explicit cleanup APIs.
 
 Before:
 
@@ -44,6 +45,22 @@ import {render} from '@testing-library/react';
 render(<Component />);
 ```
 
+`renderIntoDocument` rendered into a detached DOM node and returned the component instance instead of the container.
+This made it difficult to inspect the rendered output or reliably clean it up after a test.
+`render` returns helpers for the rendered tree, including `unmount`, and React Testing Library also provides `cleanup` to remove any trees mounted with `render` between tests.
+
+```js
+import {render} from '@testing-library/react';
+
+test('renders a component', () => {
+  const {unmount} = render(<Component />);
+
+  // ...assertions...
+
+  unmount();
+});
+```
+
 ### ReactDOMTestUtils.Simulate {/*reactdomtestutilssimulate*/}
 
 `Simulate` can be replaced with `fireEvent` from `@testing-library/react`.