docs: testing - highlight dispatchEvent (#22726)

PR Close #22726

aio/content/examples/testing/src/app/hero/hero-detail.component.spec.ts

@@ -197,20 +197,21 @@ function heroModuleSetup() {
 
     // #docregion title-case-pipe
     it('should convert hero name to Title Case', () => {
-      const inputName = 'quick BROWN  fox';
-      const titleCaseName = 'Quick Brown  Fox';
-      const { nameInput, nameDisplay } = page;
+      // get the name's input and display elements from the DOM
+      const hostElement = fixture.nativeElement;
+      const nameInput: HTMLInputElement = hostElement.querySelector('input');
+      const nameDisplay: HTMLElement = hostElement.querySelector('span');
 
-      // simulate user entering new name into the input box
-      nameInput.value = inputName;
+      // simulate user entering a new name into the input box
+      nameInput.value = 'quick BROWN  fOx';
 
       // dispatch a DOM event so that Angular learns of input value change.
       nameInput.dispatchEvent(newEvent('input'));
 
-      // Tell Angular to update the output span through the title pipe
+      // Tell Angular to update the display binding through the title pipe
       fixture.detectChanges();
 
-      expect(nameDisplay.textContent).toBe(titleCaseName);
+      expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
     });
     // #enddocregion title-case-pipe
   // #enddocregion selected-tests

aio/content/guide/testing.md

@@ -785,6 +785,25 @@ There is no harm in calling `detectChanges()` more often than is strictly necess
 
 <hr>
 
+{@a dispatch-event}
+
+#### Change an input value with _dispatchEvent()_
+
+To simulate user input, you can find the input element and set its `value` property.
+
+You will call `fixture.detectChanges()` to trigger Angular's change detection.
+But there is an essential, intermediate step.
+
+Angular doesn't know that you set the input element's `value` property.
+It won't read that property until you raise the element's `input` event by calling `dispatchEvent()`. 
+_Then_ you call `detectChanges()`.
+
+The following example demonstrates the proper sequence.
+
+<code-example path="testing/src/app/hero/hero-detail.component.spec.ts" region="title-case-pipe" title="app/hero/hero-detail.component.spec.ts (pipe test)"></code-example>
+
+<hr>
+
 ### Component with external files
 
 The `BannerComponent` above is defined with an _inline template_ and _inline css_, specified in the `@Component.template` and `@Component.styles` properties respectively.