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

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,24 @@ export class ProtractorElement implements TestElement {
   async isFocused(): Promise<boolean> {
     return this.element.equals(browser.driver.switchTo().activeElement());
   }
+
+  async dispatchEvent(name: string, data?: Record<string | number, any>): Promise<void> {
+    return browser.executeScript(_dispatchEvent, name, data ? JSON.stringify(data) : null,
+                                 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, data: string | null, element: ElementFinder) {
+  const event = document.createEvent('Event');
+  event.initEvent(name);
+  if (data) {
+    // tslint:disable-next-line:ban Have to use `Object.assign` to preserve the original object.
+    Object.assign(event, JSON.parse(data));
+  }
+  element.dispatchEvent(event);
 }

src/cdk/testing/test-element.ts

@@ -147,6 +147,14 @@ 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. Optionally attaches data to the event object.
+   * @param name Name of the event to be dispatched.
+   * @param data Data to be attached to the event object.
+   * @breaking-change 12.0.0 To be a required method.
+   */
+  dispatchEvent?(name: string, data?: Record<string | number, any>): Promise<void>;
 }
 
 export interface TextOptions {

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

@@ -24,6 +24,8 @@ import {
   triggerBlur,
   triggerFocus,
   typeInElement,
+  dispatchEvent,
+  createFakeEvent
 } from './fake-events';
 
 /** Maps `TestKey` constants to the `keyCode` and `key` values used by native browser events. */
@@ -200,6 +202,18 @@ export class UnitTestElement implements TestElement {
     return document.activeElement === this.element;
   }
 
+  async dispatchEvent(name: string, data?: Record<string | number, any>): Promise<void> {
+    const event = createFakeEvent(name);
+
+    if (data) {
+      // tslint:disable-next-line:ban Have to use `Object.assign` to preserve the original object.
+      Object.assign(event, data);
+    }
+
+    dispatchEvent(this.element, event);
+    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,22 @@ 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 dispatch a custom event with attached data', async () => {
+      const target = await harness.customEventObject();
+
+      // @breaking-change 12.0.0 Remove non-null assertion once `dispatchEvent` is required.
+      await target.dispatchEvent!('myCustomEvent', {message: 'Hello', value: 1337});
+      expect(await target.text()).toBe('Event with object: {"message":"Hello","value":1337}');
+    });
+
     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,8 @@ 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');
+  readonly customEventObject = this.locatorFor('#custom-event-object');
 
   private _testTools = this.locatorFor(SubComponentHarness);
 

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

@@ -42,6 +42,8 @@ <h1 style="height: 100px; width: 200px;">Main Component</h1>
   <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 (myCustomEvent)="onCustomEvent($event)" id="custom-event-object">Event with object: {{customEventData}}</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,8 @@ export class TestMainComponent implements OnDestroy {
   singleSelectChangeEventCount = 0;
   multiSelect: string[] = [];
   multiSelectChangeEventCount = 0;
+  basicEvent = 0;
+  customEventData: string | null = null;
   _shadowDomSupported = _supportsShadowDom();
 
   @ViewChild('clickTestElement') clickTestElement: ElementRef<HTMLElement>;
@@ -94,6 +95,10 @@ export class TestMainComponent implements OnDestroy {
     this.relativeY = Math.round(event.clientY - top);
   }
 
+  onCustomEvent(event: any) {
+    this.customEventData = JSON.stringify({message: event.message, value: event.value});
+  }
+
   runTaskOutsideZone() {
     this._zone.runOutsideAngular(() => setTimeout(() => {
       this.taskStateResultElement.nativeElement.textContent = 'result';

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, data?: Record<string | number, any>): 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, data?: Record<string | number, any>): 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, data?: Record<string | number, any>): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;