feat(cdk/testing): add the ability to dispatch arbitrary events (#20714)

Allows for arbitrary events to be dispatched through a `TestElement`. This covers the following use cases:
1. Some events can't be simulated easily without a user interaction (e.g. `change` event on an `input`).
2. Allows for custom DOM event handlers to be triggered.

Author: crisbeto

src/cdk/testing/protractor/protractor-element.ts

@@ -198,4 +198,19 @@ export class ProtractorElement implements TestElement {
   async isFocused(): Promise<boolean> {
     return this.element.equals(browser.driver.switchTo().activeElement());
   }
+
+  async dispatchEvent(name: string): Promise<void> {
+    return browser.executeScript(_dispatchEvent, name, this.element);
+  }
+}
+
+/**
+ * Dispatches an event with a particular name and data to an element.
+ * Note that this needs to be a pure function, because it gets stringified by
+ * Protractor and is executed inside the browser.
+ */
+function _dispatchEvent(name: string, element: ElementFinder) {
+  const event = document.createEvent('Event');
+  event.initEvent(name);
+  element.dispatchEvent(event);
 }

src/cdk/testing/test-element.ts

@@ -147,6 +147,13 @@ export interface TestElement {
    * @breaking-change 12.0.0 To become a required method.
    */
   selectOptions?(...optionIndexes: number[]): Promise<void>;
+
+  /**
+   * Dispatches an event with a particular name.
+   * @param name Name of the event to be dispatched.
+   * @breaking-change 12.0.0 To be a required method.
+   */
+  dispatchEvent?(name: string): Promise<void>;
 }
 
 export interface TextOptions {

src/cdk/testing/testbed/unit-test-element.ts

@@ -200,6 +200,11 @@ export class UnitTestElement implements TestElement {
     return document.activeElement === this.element;
   }
 
+  async dispatchEvent(name: string): Promise<void> {
+    dispatchFakeEvent(this.element, name);
+    await this._stabilize();
+  }
+
   /**
    * Dispatches a pointer event on the current element if the browser supports it.
    * @param name Name of the pointer event to be dispatched.

src/cdk/testing/tests/cross-environment.spec.ts

@@ -445,7 +445,6 @@ export function crossEnvironmentSpecs(
       expect(await button.matchesSelector('button:disabled')).toBe(false);
     });
 
-
     it('should get correct text excluding certain selectors', async () => {
       const results = await harness.subcomponentAndSpecialHarnesses();
       const subHarnessHost = await results[0].host();
@@ -454,6 +453,14 @@ export function crossEnvironmentSpecs(
       expect(await subHarnessHost.text({exclude: 'li'})).toBe('List of test tools');
     });
 
+    it('should dispatch a basic custom event', async () => {
+      const target = await harness.customEventBasic();
+
+      // @breaking-change 12.0.0 Remove non-null assertion once `dispatchEvent` is required.
+      await target.dispatchEvent!('myCustomEvent');
+      expect(await target.text()).toBe('Basic event: 1');
+    });
+
     it('should get TestElements and ComponentHarnesses', async () => {
       const results = await harness.subcomponentHarnessesAndElements();
       expect(results.length).toBe(5);

src/cdk/testing/tests/harnesses/main-component-harness.ts

@@ -91,6 +91,7 @@ export class MainComponentHarness extends ComponentHarness {
   readonly deepShadow = this.locatorFor(
       'test-shadow-boundary test-sub-shadow-boundary > .in-the-shadows');
   readonly hoverTest = this.locatorFor('#hover-box');
+  readonly customEventBasic = this.locatorFor('#custom-event-basic');
 
   private _testTools = this.locatorFor(SubComponentHarness);
 

src/cdk/testing/tests/test-main-component.html

@@ -41,7 +41,7 @@ <h1 style="height: 100px; width: 200px;">Main Component</h1>
   </select>
   <div id="multi-select-value">Multi-select: {{multiSelect}}</div>
   <div id="multi-select-change-counter">Change events: {{multiSelectChangeEventCount}}</div>
-
+  <div (myCustomEvent)="basicEvent = basicEvent + 1" id="custom-event-basic">Basic event: {{basicEvent}}</div>
 </div>
 <div class="subcomponents">
   <test-sub class="test-special" title="test tools" [items]="testTools"></test-sub>

src/cdk/testing/tests/test-main-component.ts

@@ -25,7 +25,6 @@ import {
   encapsulation: ViewEncapsulation.None,
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
-
 export class TestMainComponent implements OnDestroy {
   username: string;
   counter: number;
@@ -42,6 +41,7 @@ export class TestMainComponent implements OnDestroy {
   singleSelectChangeEventCount = 0;
   multiSelect: string[] = [];
   multiSelectChangeEventCount = 0;
+  basicEvent = 0;
   _shadowDomSupported = _supportsShadowDom();
 
   @ViewChild('clickTestElement') clickTestElement: ElementRef<HTMLElement>;

tools/public_api_guard/cdk/testing.d.ts

@@ -135,6 +135,7 @@ export interface TestElement {
     click(): Promise<void>;
     click(location: 'center'): Promise<void>;
     click(relativeX: number, relativeY: number): Promise<void>;
+    dispatchEvent?(name: string): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;

tools/public_api_guard/cdk/testing/protractor.d.ts

@@ -4,6 +4,7 @@ export declare class ProtractorElement implements TestElement {
     blur(): Promise<void>;
     clear(): Promise<void>;
     click(...args: [] | ['center'] | [number, number]): Promise<void>;
+    dispatchEvent(name: string): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;

tools/public_api_guard/cdk/testing/testbed.d.ts

@@ -22,6 +22,7 @@ export declare class UnitTestElement implements TestElement {
     blur(): Promise<void>;
     clear(): Promise<void>;
     click(...args: [] | ['center'] | [number, number]): Promise<void>;
+    dispatchEvent(name: string): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;