From 82f97e54923d8bee928bd6691de005844e859929 Mon Sep 17 00:00:00 2001
From: Geordan Neukum <gneukum1@gmail.com>
Date: Sun, 23 Oct 2022 20:09:24 -0400
Subject: [PATCH 1/2] DOCS: API: add routing helper examples

Let's add an example usage of all of the routing helpers (visit,
currentRouteName, currentURL) to the API docs.

(cherry picked from commit fa068a080f5f842e103ba47f983f43f1af0cf713)
---
 API.md                                        | 22 +++++++++++++++----
 .../test-helpers/setup-application-context.ts | 12 ++++++++++
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/API.md b/API.md
index a73e61339..275b2e99b 100644
--- a/API.md
+++ b/API.md
@@ -551,6 +551,20 @@ Navigate the application to the provided URL.
 *   `url` **[string][64]** The URL to visit (e.g. `/posts`)
 *   `options` **[object][72]** app boot options
 
+#### Examples
+
+Visiting the route for post 1.
+
+```javascript
+await visit('/posts/1');
+```
+
+Visiting the route for post 1 while also providing the `rootElement` app boot option.
+
+```javascript
+await visit('/', { rootElement: '#container' });
+```
+
 Returns **[Promise][66]\<void>** resolves when settled
 
 ### currentRouteName
@@ -1241,23 +1255,23 @@ Returns **([Array][70]\<Warning> | [Promise][66]<[Array][70]\<Warning>>)** An ar
 
 [54]: #getdeprecations
 
-[55]: #examples-22
+[55]: #examples-23
 
 [56]: #getdeprecationsduringcallback
 
 [57]: #parameters-29
 
-[58]: #examples-23
+[58]: #examples-24
 
 [59]: #getwarnings
 
-[60]: #examples-24
+[60]: #examples-25
 
 [61]: #getwarningsduringcallback
 
 [62]: #parameters-30
 
-[63]: #examples-25
+[63]: #examples-26
 
 [64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
diff --git a/addon-test-support/@ember/test-helpers/setup-application-context.ts b/addon-test-support/@ember/test-helpers/setup-application-context.ts
index ae47232fb..35c96b08e 100644
--- a/addon-test-support/@ember/test-helpers/setup-application-context.ts
+++ b/addon-test-support/@ember/test-helpers/setup-application-context.ts
@@ -130,6 +130,18 @@ export function setupRouterSettlednessTracking() {
   @param {string} url The URL to visit (e.g. `/posts`)
   @param {object} options app boot options
   @returns {Promise<void>} resolves when settled
+
+  @example
+  <caption>
+    Visiting the route for post 1.
+  </caption>
+  await visit('/posts/1');
+
+  @example
+  <caption>
+    Visiting the route for post 1 while also providing the `rootElement` app boot option.
+  </caption>
+  await visit('/', { rootElement: '#container' });
 */
 export function visit(
   url: string,

From 0dfb1dc0cdb328e8437f92924fd3930723cca72a Mon Sep 17 00:00:00 2001
From: Geordan Neukum <gneukum1@gmail.com>
Date: Sun, 23 Oct 2022 20:20:30 -0400
Subject: [PATCH 2/2] DOC: API: add render helper examples

Let's add an example usage of all of the render helpers (render, clearRender)
to the API docs.

(cherry picked from commit fb7d29383002833728f6b327ba1b4893ef855c27)

# Conflicts:
#	API.md
#	addon-test-support/@ember/test-helpers/setup-rendering-context.ts
---
 API.md                                        | 29 +++++++++++++++----
 .../test-helpers/setup-rendering-context.ts   | 16 ++++++++++
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/API.md b/API.md
index 275b2e99b..cf297c044 100644
--- a/API.md
+++ b/API.md
@@ -501,7 +501,7 @@ Find all of the elements matching '.my-selector'.
 findAll('.my-selector');
 ```
 
-Returns **[Element][65]** matched element or null
+Returns **([Element][65] | null)** matched element or null
 
 ### findAll
 
@@ -588,6 +588,14 @@ Renders the provided template and appends it to the DOM.
 *   `templateOrComponent` **(Template | Component)** the component (or template) to render
 *   `options` **RenderOptions** options hash containing engine owner ({ owner: engineOwner })
 
+#### Examples
+
+Render a div element with the class 'container'.
+
+```javascript
+await render(hbs`<div class="container"></div>`);
+```
+
 Returns **[Promise][66]\<void>** resolves when settled
 
 ### clearRender
@@ -897,6 +905,17 @@ element).
 
 *   `context` **TestContext** the context to setup for rendering
 
+#### Examples
+
+Rendering out a paragraph element containing the content 'hello', and then clearing that content via clearRender.
+
+```javascript
+await render(hbs`<p>Hello!</p>`);
+assert.equal(this.element.textContent, 'Hello!', 'has rendered content');
+await clearRender();
+assert.equal(this.element.textContent, '', 'has rendered content');
+```
+
 Returns **[Promise][66]\<RenderingTestContext>** resolves with the context that was setup
 
 ### getApplication
@@ -1255,23 +1274,23 @@ Returns **([Array][70]\<Warning> | [Promise][66]<[Array][70]\<Warning>>)** An ar
 
 [54]: #getdeprecations
 
-[55]: #examples-23
+[55]: #examples-25
 
 [56]: #getdeprecationsduringcallback
 
 [57]: #parameters-29
 
-[58]: #examples-24
+[58]: #examples-26
 
 [59]: #getwarnings
 
-[60]: #examples-25
+[60]: #examples-27
 
 [61]: #getwarningsduringcallback
 
 [62]: #parameters-30
 
-[63]: #examples-26
+[63]: #examples-28
 
 [64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
diff --git a/addon-test-support/@ember/test-helpers/setup-rendering-context.ts b/addon-test-support/@ember/test-helpers/setup-rendering-context.ts
index 00d0a526f..c5a84c0ea 100644
--- a/addon-test-support/@ember/test-helpers/setup-rendering-context.ts
+++ b/addon-test-support/@ember/test-helpers/setup-rendering-context.ts
@@ -91,6 +91,12 @@ export interface RenderOptions {
   @param {Template|Component} templateOrComponent the component (or template) to render
   @param {RenderOptions} options options hash containing engine owner ({ owner: engineOwner })
   @returns {Promise<void>} resolves when settled
+
+  @example
+  <caption>
+    Render a div element with the class 'container'.
+  </caption>
+  await render(hbs`<div class="container"></div>`);
 */
 export function render(
   templateOrComponent: TemplateFactory | ComponentInstance,
@@ -270,6 +276,16 @@ export function clearRender(): Promise<void> {
   @public
   @param {TestContext} context the context to setup for rendering
   @returns {Promise<RenderingTestContext>} resolves with the context that was setup
+
+  @example
+  <caption>
+    Rendering out a paragraph element containing the content 'hello', and then clearing that content via clearRender.
+  </caption>
+
+  await render(hbs`<p>Hello!</p>`);
+  assert.equal(this.element.textContent, 'Hello!', 'has rendered content');
+  await clearRender();
+  assert.equal(this.element.textContent, '', 'has rendered content');
 */
 export default function setupRenderingContext(
   context: TestContext