feat(cdk/testing): allow for data to be attached to custom event (#20764)

Allows for data to be attached to an event that is triggered through `TestElement.dispatchEvent`.
This is required in order to simulate some events like `animationend`.
It is limited to primitive data types, because the data has to be JSON-serializeable for Protractor.

Author: crisbeto

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

@@ -12,7 +12,8 @@ import {
   ModifierKeys,
   TestElement,
   TestKey,
-  TextOptions
+  TextOptions,
+  EventData,
 } from '@angular/cdk/testing';
 import {browser, Button, by, ElementFinder, Key} from 'protractor';
 
@@ -195,8 +196,8 @@ export class ProtractorElement implements TestElement {
     return this.element.equals(browser.driver.switchTo().activeElement());
   }
 
-  async dispatchEvent(name: string): Promise<void> {
-    return browser.executeScript(_dispatchEvent, name, this.element);
+  async dispatchEvent(name: string, data?: Record<string, EventData>): Promise<void> {
+    return browser.executeScript(_dispatchEvent, name, this.element, data);
   }
 
   /** Dispatches all the events that are part of a click event sequence. */
@@ -220,9 +221,15 @@ export class ProtractorElement implements TestElement {
  * 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) {
+function _dispatchEvent(name: string, element: ElementFinder, data?: Record<string, EventData>) {
   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, data);
+  }
+
   // This type has a string index signature, so we cannot access it using a dotted property access.
   element['dispatchEvent'](event);
 }

src/cdk/testing/test-element.ts

@@ -16,6 +16,10 @@ export interface ModifierKeys {
   meta?: boolean;
 }
 
+/** Data that can be attached to a custom event dispatched from a `TestElement`. */
+export type EventData =
+    string | number | boolean | undefined | null | EventData[] | {[key: string]: EventData};
+
 /** An enum of non-text keys that can be used with the `sendKeys` method. */
 // NOTE: This is a separate enum from `@angular/cdk/keycodes` because we don't necessarily want to
 // support every possible keyCode. We also can't rely on Protractor's `Key` because we don't want a
@@ -161,7 +165,7 @@ export interface TestElement {
    * @param name Name of the event to be dispatched.
    * @breaking-change 12.0.0 To be a required method.
    */
-  dispatchEvent?(name: string): Promise<void>;
+  dispatchEvent?(name: string, data?: Record<string, EventData>): Promise<void>;
 }
 
 export interface TextOptions {

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

@@ -13,17 +13,20 @@ import {
   ModifierKeys,
   TestElement,
   TestKey,
-  TextOptions
+  TextOptions,
+  EventData,
 } from '@angular/cdk/testing';
 import {
   clearElement,
+  createFakeEvent,
   dispatchFakeEvent,
   dispatchMouseEvent,
   dispatchPointerEvent,
   isTextInput,
   triggerBlur,
   triggerFocus,
   typeInElement,
+  dispatchEvent,
 } from './fake-events';
 
 /** Maps `TestKey` constants to the `keyCode` and `key` values used by native browser events. */
@@ -188,8 +191,15 @@ export class UnitTestElement implements TestElement {
     return document.activeElement === this.element;
   }
 
-  async dispatchEvent(name: string): Promise<void> {
-    dispatchFakeEvent(this.element, name);
+  async dispatchEvent(name: string, data?: Record<string, EventData>): 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();
   }
 

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

@@ -468,6 +468,14 @@ export function crossEnvironmentSpecs(
       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

@@ -93,6 +93,7 @@ export class MainComponentHarness extends ComponentHarness {
       '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

@@ -43,6 +43,7 @@ <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

@@ -40,6 +40,7 @@ export class TestMainComponent implements OnDestroy {
   multiSelect: string[] = [];
   multiSelectChangeEventCount = 0;
   basicEvent = 0;
+  customEventData: string | null = null;
   _shadowDomSupported = _supportsShadowDom();
   clickResult = {x: -1, y: -1};
   rightClickResult = {x: -1, y: -1, button: -1};
@@ -97,6 +98,10 @@ export class TestMainComponent implements OnDestroy {
     this._assignRelativeCoordinates(event, this.rightClickResult);
   }
 
+  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

@@ -48,6 +48,10 @@ export interface ElementDimensions {
     width: number;
 }
 
+export declare type EventData = string | number | boolean | undefined | null | EventData[] | {
+    [key: string]: EventData;
+};
+
 export declare function handleAutoChangeDetectionStatus(handler: (status: AutoChangeDetectionStatus) => void): void;
 
 export declare abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFactory {
@@ -135,7 +139,7 @@ export interface TestElement {
     click(): Promise<void>;
     click(location: 'center'): Promise<void>;
     click(relativeX: number, relativeY: number): Promise<void>;
-    dispatchEvent?(name: string): Promise<void>;
+    dispatchEvent?(name: string, data?: Record<string, EventData>): 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,7 +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>;
+    dispatchEvent(name: string, data?: Record<string, EventData>): 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,7 +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>;
+    dispatchEvent(name: string, data?: Record<string, EventData>): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;