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

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

Author: wwjhu

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

@@ -81,8 +81,9 @@ 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> {
@@ -202,17 +203,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,17 +76,17 @@ 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.
    */
-  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.

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,8 +80,9 @@ 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();
   }
 
@@ -224,15 +225,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 +247,9 @@ 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);
-    await this._stabilize();
+    dispatchMouseEvent(this.element, 'mouseup', clientX, clientY, button, modifiers);
+    dispatchMouseEvent(this.element, name, clientX, clientY, button, modifiers);
   }
 }

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

@@ -319,20 +319,52 @@ 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();

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,6 +92,9 @@ 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) {