feat(cdk/testing): support modifiers for clicking on a TestElement (#20758)

* feat(cdk/testing): support modifiers for clicking on a TestElement

Adds the ability to provide modifier keys when clicking on a TestElement

* feat(cdk/testing): update cdk/testing public API

Update API golden files for cdk/testing.

* feat(cdk/testing): update cdk/testing public API

Update API golden files for ProtractorElement and UnitTestElement.

* feat(cdk/testing): support modifiers for right clicking on a TestElement

Adds the ability to provide modifier keys when right clicking on a TestElement

* feat(cdk/testing): update cdk/testing public API

Update API golden files

* feat(cdk/testing): chore: fix spacing

Indentation and space changes based on review.

* feat(cdk/testing): re-add stabilize call

The call to _stabilize should not be needed since the callers will
already do that themselves. Nevertheless it breaks some tests in g3
without it. It needs to be investigated why removing breaks those
tests.

Author: wwjhu

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

@@ -81,11 +81,13 @@ export class ProtractorElement implements TestElement {
     return this.element.clear();
   }
 
-  async click(...args: [] | ['center'] | [number, number]): Promise<void> {
-    await this._dispatchClickEventSequence(args);
+  async click(...args: [ModifierKeys?] | ['center', ModifierKeys?] |
+    [number, number, ModifierKeys?]): Promise<void> {
+    await this._dispatchClickEventSequence(args, Button.LEFT);
   }
 
-  async rightClick(...args: [] | ['center'] | [number, number]): Promise<void> {
+  async rightClick(...args: [ModifierKeys?] | ['center', ModifierKeys?] |
+    [number, number, ModifierKeys?]): Promise<void> {
     await this._dispatchClickEventSequence(args, Button.RIGHT);
   }
 
@@ -202,17 +204,33 @@ export class ProtractorElement implements TestElement {
 
   /** Dispatches all the events that are part of a click event sequence. */
   private async _dispatchClickEventSequence(
-    args: [] | ['center'] | [number, number],
-    button?: string) {
+    args: [ModifierKeys?] | ['center', ModifierKeys?] |
+      [number, number, ModifierKeys?],
+    button: string) {
+    let modifiers: ModifierKeys = {};
+    if (args.length && typeof args[args.length - 1] === 'object') {
+      modifiers = args.pop() as ModifierKeys;
+    }
+    const modifierKeys = toProtractorModifierKeys(modifiers);
+
     // Omitting the offset argument to mouseMove results in clicking the center.
-    // This is the default behavior we want, so we use an empty array of offsetArgs if no args are
-    // passed to this method.
-    const offsetArgs = args.length === 2 ? [{x: args[0], y: args[1]}] : [];
-
-    await browser.actions()
-      .mouseMove(await this.element.getWebElement(), ...offsetArgs)
-      .click(button)
-      .perform();
+    // This is the default behavior we want, so we use an empty array of offsetArgs if
+    // no args remain after popping the modifiers from the args passed to this function.
+    const offsetArgs = (args.length === 2 ?
+      [{x: args[0], y: args[1]}] : []) as [{x: number, y: number}];
+
+    let actions = browser.actions()
+      .mouseMove(await this.element.getWebElement(), ...offsetArgs);
+
+    for (const modifierKey of modifierKeys) {
+      actions = actions.keyDown(modifierKey);
+    }
+    actions = actions.click(button);
+    for (const modifierKey of modifierKeys) {
+      actions = actions.keyUp(modifierKey);
+    }
+
+    await actions.perform();
   }
 }
 

src/cdk/testing/test-element.ts

@@ -76,25 +76,27 @@ export interface TestElement {
    * the element is clicked at a specific location, consider using `click('center')` or
    * `click(x, y)` instead.
    */
-  click(): Promise<void>;
+  click(modifiers?: ModifierKeys): Promise<void>;
 
   /** Click the element at the element's center. */
-  click(location: 'center'): Promise<void>;
+  click(location: 'center', modifiers?: ModifierKeys): Promise<void>;
 
   /**
    * Click the element at the specified coordinates relative to the top-left of the element.
    * @param relativeX Coordinate within the element, along the X-axis at which to click.
    * @param relativeY Coordinate within the element, along the Y-axis at which to click.
+   * @param modifiers Modifier keys held while clicking
    */
-  click(relativeX: number, relativeY: number): Promise<void>;
+  click(relativeX: number, relativeY: number, modifiers?: ModifierKeys): Promise<void>;
 
   /**
    * Right clicks on the element at the specified coordinates relative to the top-left of it.
    * @param relativeX Coordinate within the element, along the X-axis at which to click.
    * @param relativeY Coordinate within the element, along the Y-axis at which to click.
+   * @param modifiers Modifier keys held while clicking
    * @breaking-change 11.0.0 To become a required method.
    */
-  rightClick?(relativeX: number, relativeY: number): Promise<void>;
+  rightClick?(relativeX: number, relativeY: number, modifiers?: ModifierKeys): Promise<void>;
 
   /** Focus the element. */
   focus(): Promise<void>;

src/cdk/testing/testbed/fake-events/dispatch-events.ts

@@ -47,9 +47,9 @@ export function dispatchKeyboardEvent(node: Node, type: string, keyCode?: number
  * Shorthand to dispatch a mouse event on the specified coordinates.
  * @docs-private
  */
-export function dispatchMouseEvent(
-  node: Node, type: string, clientX = 0, clientY = 0, button?: number): MouseEvent {
-  return dispatchEvent(node, createMouseEvent(type, clientX, clientY, button));
+export function dispatchMouseEvent( node: Node, type: string, clientX = 0, clientY = 0,
+  button?: number, modifiers?: ModifierKeys): MouseEvent {
+  return dispatchEvent(node, createMouseEvent(type, clientX, clientY, button, modifiers));
 }
 
 /**

src/cdk/testing/testbed/fake-events/event-objects.ts

@@ -12,7 +12,8 @@ import {ModifierKeys} from '@angular/cdk/testing';
  * Creates a browser MouseEvent with the specified options.
  * @docs-private
  */
-export function createMouseEvent(type: string, clientX = 0, clientY = 0, button = 0) {
+export function createMouseEvent(
+  type: string, clientX = 0, clientY = 0, button = 0, modifiers: ModifierKeys = {}) {
   const event = document.createEvent('MouseEvent');
   const originalPreventDefault = event.preventDefault.bind(event);
 
@@ -32,10 +33,10 @@ export function createMouseEvent(type: string, clientX = 0, clientY = 0, button
     /* screenY */ screenY,
     /* clientX */ clientX,
     /* clientY */ clientY,
-    /* ctrlKey */ false,
-    /* altKey */ false,
-    /* shiftKey */ false,
-    /* metaKey */ false,
+    /* ctrlKey */ !!modifiers.control,
+    /* altKey */ !!modifiers.alt,
+    /* shiftKey */ !!modifiers.shift,
+    /* metaKey */ !!modifiers.meta,
     /* button */ button,
     /* relatedTarget */ null);
 

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

@@ -80,12 +80,14 @@ export class UnitTestElement implements TestElement {
     await this._stabilize();
   }
 
-  async click(...args: [] | ['center'] | [number, number]): Promise<void> {
-    await this._dispatchMouseEventSequence('click', args);
+  async click(...args: [ModifierKeys?] | ['center', ModifierKeys?] |
+    [number, number, ModifierKeys?]): Promise<void> {
+    await this._dispatchMouseEventSequence('click', args, 0);
     await this._stabilize();
   }
 
-  async rightClick(...args: [] | ['center'] | [number, number]): Promise<void> {
+  async rightClick(...args: [ModifierKeys?] | ['center', ModifierKeys?] |
+    [number, number, ModifierKeys?]): Promise<void> {
     await this._dispatchMouseEventSequence('contextmenu', args, 2);
     await this._stabilize();
   }
@@ -224,15 +226,20 @@ export class UnitTestElement implements TestElement {
   /** Dispatches all the events that are part of a mouse event sequence. */
   private async _dispatchMouseEventSequence(
     name: string,
-    args: [] | ['center'] | [number, number],
+    args: [ModifierKeys?] | ['center', ModifierKeys?] | [number, number, ModifierKeys?],
     button?: number) {
     let clientX: number | undefined = undefined;
     let clientY: number | undefined = undefined;
+    let modifiers: ModifierKeys = {};
+
+    if (args.length && typeof args[args.length - 1] === 'object') {
+      modifiers = args.pop() as ModifierKeys;
+    }
 
     if (args.length) {
       const {left, top, width, height} = await this.getDimensions();
-      const relativeX = args[0] === 'center' ? width / 2 : args[0];
-      const relativeY = args[0] === 'center' ? height / 2 : args[1];
+      const relativeX = args[0] === 'center' ? width / 2 : args[0] as number;
+      const relativeY = args[0] === 'center' ? height / 2 : args[1] as number;
 
       // Round the computed click position as decimal pixels are not
       // supported by mouse events and could lead to unexpected results.
@@ -241,10 +248,14 @@ export class UnitTestElement implements TestElement {
     }
 
     this._dispatchPointerEventIfSupported('pointerdown', clientX, clientY, button);
-    dispatchMouseEvent(this.element, 'mousedown', clientX, clientY, button);
+    dispatchMouseEvent(this.element, 'mousedown', clientX, clientY, button, modifiers);
     this._dispatchPointerEventIfSupported('pointerup', clientX, clientY, button);
-    dispatchMouseEvent(this.element, 'mouseup', clientX, clientY, button);
-    dispatchMouseEvent(this.element, name, clientX, clientY, button);
+    dispatchMouseEvent(this.element, 'mouseup', clientX, clientY, button, modifiers);
+    dispatchMouseEvent(this.element, name, clientX, clientY, button, modifiers);
+
+    // This call to _stabilize should not be needed since the callers will already do that them-
+    // selves. Nevertheless it breaks some tests in g3 without it. It needs to be investigated
+    // why removing breaks those tests.
     await this._stabilize();
   }
 }

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

@@ -320,27 +320,66 @@ export function crossEnvironmentSpecs(
       expect(await counter.text()).toBe('3');
     });
 
+    it('should be able to click with no modifiers', async () => {
+      const clickTest = await harness.clickTest();
+      const modifiersResult = await harness.clickModifiersResult();
+
+      await clickTest.click();
+      expect(await modifiersResult.text()).toBe('---');
+    });
+
+    it('should be able to click with shift and meta modifiers', async () => {
+      const clickTest = await harness.clickTest();
+      const modifiersResult = await harness.clickModifiersResult();
+
+      await clickTest.click({shift: true, meta: true});
+      expect(await modifiersResult.text()).toBe('shift---meta');
+    });
+
     it('should be able to click at a specific position within an element', async () => {
       const clickTest = await harness.clickTest();
       const clickTestResult = await harness.clickTestResult();
       await clickTest.click(10, 10);
       expect(await clickTestResult.text()).toBe('10-10');
     });
 
+    it('should be able to click at a specific position with shift and meta modifiers', async () => {
+      const clickTest = await harness.clickTest();
+      const modifiersResult = await harness.clickModifiersResult();
+
+      await clickTest.click(10, 10, {shift: true, meta: true});
+      expect(await modifiersResult.text()).toBe('shift---meta');
+    });
+
     it('should be able to click the center of an element', async () => {
       const clickTest = await harness.clickTest();
       const clickTestResult = await harness.clickTestResult();
       await clickTest.click('center');
       expect(await clickTestResult.text()).toBe('50-50');
     });
 
+    it('should be able to click the center of an element with shift meta modifiers', async () => {
+      const clickTest = await harness.clickTest();
+      const modifiersResult = await harness.clickModifiersResult();
+
+      await clickTest.click('center', {shift: true, meta: true});
+      expect(await modifiersResult.text()).toBe('shift---meta');
+    });
+
     it('should be able to right click at a specific position within an element', async () => {
       const clickTest = await harness.clickTest();
       const contextmenuTestResult = await harness.contextmenuTestResult();
       await clickTest.rightClick!(50, 50);
       expect(await contextmenuTestResult.text()).toBe('50-50-2');
     });
 
+    it('should be able to right click with modifiers', async () => {
+      const clickTest = await harness.clickTest();
+      const modifiersResult = await harness.clickModifiersResult();
+      await clickTest.rightClick!(50, 50, {alt: true, control: true});
+      expect(await modifiersResult.text()).toBe('-alt-control-');
+    });
+
     it('should be able to send key', async () => {
       const input = await harness.input();
       const value = await harness.value();

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

@@ -28,6 +28,7 @@ export class MainComponentHarness extends ComponentHarness {
   readonly memo = this.locatorFor('textarea');
   readonly clickTest = this.locatorFor('.click-test');
   readonly clickTestResult = this.locatorFor('.click-test-result');
+  readonly clickModifiersResult = this.locatorFor('.click-modifiers-test-result');
   readonly singleSelect = this.locatorFor('#single-select');
   readonly singleSelectValue = this.locatorFor('#single-select-value');
   readonly singleSelectChangeEventCounter = this.locatorFor('#single-select-change-counter');

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

@@ -4,6 +4,7 @@
 </div>
 <div class="click-test-result">{{clickResult.x}}-{{clickResult.y}}</div>
 <div class="contextmenu-test-result">{{rightClickResult.x}}-{{rightClickResult.y}}-{{rightClickResult.button}}</div>
+<div class="click-modifiers-test-result">{{modifiers}}</div>
 <h1 style="height: 100px; width: 200px;">Main Component</h1>
 <div id="username">Hello {{username}} from Angular 2!</div>
 <div class="counters">

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

@@ -35,6 +35,7 @@ export class TestMainComponent implements OnDestroy {
   testMethods: string[];
   isHovering = false;
   specialKey = '';
+  modifiers: string;
   singleSelect: string;
   singleSelectChangeEventCount = 0;
   multiSelect: string[] = [];
@@ -91,11 +92,17 @@ export class TestMainComponent implements OnDestroy {
 
   onClick(event: MouseEvent) {
     this._assignRelativeCoordinates(event, this.clickResult);
+
+    this.modifiers = ['Shift', 'Alt', 'Control', 'Meta']
+      .map(key => event.getModifierState(key) ? key.toLowerCase() : '').join('-');
   }
 
   onRightClick(event: MouseEvent) {
     this.rightClickResult.button = event.button;
     this._assignRelativeCoordinates(event, this.rightClickResult);
+
+    this.modifiers = ['Shift', 'Alt', 'Control', 'Meta']
+    .map(key => event.getModifierState(key) ? key.toLowerCase() : '').join('-');
   }
 
   onCustomEvent(event: any) {

tools/public_api_guard/cdk/testing.d.ts

@@ -151,9 +151,9 @@ export declare function stopHandlingAutoChangeDetectionStatus(): void;
 export interface TestElement {
     blur(): Promise<void>;
     clear(): Promise<void>;
-    click(): Promise<void>;
-    click(location: 'center'): Promise<void>;
-    click(relativeX: number, relativeY: number): Promise<void>;
+    click(modifiers?: ModifierKeys): Promise<void>;
+    click(location: 'center', modifiers?: ModifierKeys): Promise<void>;
+    click(relativeX: number, relativeY: number, modifiers?: ModifierKeys): Promise<void>;
     dispatchEvent?(name: string, data?: Record<string, EventData>): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
@@ -165,7 +165,7 @@ export interface TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
-    rightClick?(relativeX: number, relativeY: number): Promise<void>;
+    rightClick?(relativeX: number, relativeY: number, modifiers?: ModifierKeys): Promise<void>;
     selectOptions?(...optionIndexes: number[]): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;

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

@@ -3,7 +3,11 @@ export declare class ProtractorElement implements TestElement {
     constructor(element: ElementFinder);
     blur(): Promise<void>;
     clear(): Promise<void>;
-    click(...args: [] | ['center'] | [number, number]): Promise<void>;
+    click(...args: [ModifierKeys?] | ['center', ModifierKeys?] | [
+        number,
+        number,
+        ModifierKeys?
+    ]): Promise<void>;
     dispatchEvent(name: string, data?: Record<string, EventData>): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
@@ -15,7 +19,11 @@ export declare class ProtractorElement implements TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
-    rightClick(...args: [] | ['center'] | [number, number]): Promise<void>;
+    rightClick(...args: [ModifierKeys?] | ['center', ModifierKeys?] | [
+        number,
+        number,
+        ModifierKeys?
+    ]): Promise<void>;
     selectOptions(...optionIndexes: number[]): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;

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

@@ -21,7 +21,11 @@ export declare class UnitTestElement implements TestElement {
     constructor(element: Element, _stabilize: () => Promise<void>);
     blur(): Promise<void>;
     clear(): Promise<void>;
-    click(...args: [] | ['center'] | [number, number]): Promise<void>;
+    click(...args: [ModifierKeys?] | ['center', ModifierKeys?] | [
+        number,
+        number,
+        ModifierKeys?
+    ]): Promise<void>;
     dispatchEvent(name: string, data?: Record<string, EventData>): Promise<void>;
     focus(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
@@ -33,7 +37,11 @@ export declare class UnitTestElement implements TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
-    rightClick(...args: [] | ['center'] | [number, number]): Promise<void>;
+    rightClick(...args: [ModifierKeys?] | ['center', ModifierKeys?] | [
+        number,
+        number,
+        ModifierKeys?
+    ]): Promise<void>;
     selectOptions(...optionIndexes: number[]): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;