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

Adds the ability to right click somewhere within a `TestElement`.

Fixes #20385.

Author: crisbeto

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

@@ -14,7 +14,7 @@ import {
   TestKey,
   TextOptions
 } from '@angular/cdk/testing';
-import {browser, ElementFinder, Key} from 'protractor';
+import {browser, ElementFinder, Key, Button} from 'protractor';
 
 /** Maps the `TestKey` constants to Protractor's `Key` constants. */
 const keyMap = {
@@ -81,15 +81,11 @@ export class ProtractorElement implements TestElement {
   }
 
   async click(...args: number[]): Promise<void> {
-    // 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 ? [{x: args[0], y: args[1]}] : [];
+    await this._dispatchClickEventSequence(args[0], args[1]);
+  }
 
-    await browser.actions()
-      .mouseMove(await this.element.getWebElement(), ...offsetArgs)
-      .click()
-      .perform();
+  async rightClick(...args: number[]): Promise<void> {
+    await this._dispatchClickEventSequence(args[0], args[1], Button.RIGHT);
   }
 
   async focus(): Promise<void> {
@@ -177,4 +173,22 @@ export class ProtractorElement implements TestElement {
   async isFocused(): Promise<boolean> {
     return this.element.equals(browser.driver.switchTo().activeElement());
   }
+
+  /**
+   * Dispatches all the events that are part of a click event sequence.
+   * @param x X coordinate of the event within the element.
+   * @param y Y coordinate of the event within the element.
+   * @param button Mouse button that should be pressed during the event.
+   */
+  private async _dispatchClickEventSequence(x?: number, y?: number, button?: string) {
+    // 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 = (x != null && y != null) ? [{x, y}] : [];
+
+    await browser.actions()
+      .mouseMove(await this.element.getWebElement(), ...offsetArgs)
+      .click(button)
+      .perform();
+  }
 }

src/cdk/testing/test-element.ts

@@ -77,6 +77,14 @@ export interface TestElement {
    */
   click(relativeX: number, relativeY: number): 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.
+   * @breaking-change 11.0.0 To become a required method.
+   */
+  rightClick?(relativeX: number, relativeY: number): Promise<void>;
+
   /** Focus the element. */
   focus(): Promise<void>;
 

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

@@ -47,8 +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): MouseEvent {
-  return dispatchEvent(node, createMouseEvent(type, clientX, clientY));
+export function dispatchMouseEvent(
+  node: Node, type: string, clientX = 0, clientY = 0, button?: number): MouseEvent {
+  return dispatchEvent(node, createMouseEvent(type, clientX, clientY, button));
 }
 
 /**

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

@@ -77,20 +77,12 @@ export class UnitTestElement implements TestElement {
   }
 
   async click(...args: number[]): Promise<void> {
-    const {left, top, width, height} = await this.getDimensions();
-    const relativeX = args.length ? args[0] : width / 2;
-    const relativeY = args.length ? args[1] : height / 2;
-
-    // Round the computed click position as decimal pixels are not
-    // supported by mouse events and could lead to unexpected results.
-    const clientX = Math.round(left + relativeX);
-    const clientY = Math.round(top + relativeY);
+    await this._dispatchMouseEventSequence('click', args[0], args[1]);
+    await this._stabilize();
+  }
 
-    this._dispatchPointerEventIfSupported('pointerdown', clientX, clientY);
-    dispatchMouseEvent(this.element, 'mousedown', clientX, clientY);
-    this._dispatchPointerEventIfSupported('pointerup', clientX, clientY);
-    dispatchMouseEvent(this.element, 'mouseup', clientX, clientY);
-    dispatchMouseEvent(this.element, 'click', clientX, clientY);
+  async rightClick(...args: number[]): Promise<void> {
+    await this._dispatchMouseEventSequence('contextmenu', args[0], args[1], 2);
     await this._stabilize();
   }
 
@@ -176,14 +168,40 @@ export class UnitTestElement implements TestElement {
    * @param name Name of the pointer event to be dispatched.
    * @param clientX Coordinate of the user's pointer along the X axis.
    * @param clientY Coordinate of the user's pointer along the Y axis.
+   * @param button Mouse button that should be pressed when dispatching the event.
    */
-  private _dispatchPointerEventIfSupported(name: string, clientX?: number, clientY?: number) {
+  private _dispatchPointerEventIfSupported(
+    name: string, clientX?: number, clientY?: number, button?: number) {
     // The latest versions of all browsers we support have the new `PointerEvent` API.
     // Though since we capture the two most recent versions of these browsers, we also
     // need to support Safari 12 at time of writing. Safari 12 does not have support for this,
     // so we need to conditionally create and dispatch these events based on feature detection.
     if (typeof PointerEvent !== 'undefined' && PointerEvent) {
-      dispatchPointerEvent(this.element, name, clientX, clientY);
+      dispatchPointerEvent(this.element, name, clientX, clientY, {isPrimary: true, button});
     }
   }
+
+  /**
+   * Dispatches all the events that are part of a mouse event sequence.
+   * @param name Name of the final event in the sequence.
+   * @param x X coordinate of the event within the element.
+   * @param y Y coordinate of the event within the element.
+   * @param button Mouse button that should be pressed during the event.
+   */
+  private async _dispatchMouseEventSequence(name: string, x?: number, y?: number, button?: number) {
+    const {left, top, width, height} = await this.getDimensions();
+    const relativeX = x == null ? width / 2 : x;
+    const relativeY = y == null ? height / 2 : y;
+
+    // Round the computed click position as decimal pixels are not
+    // supported by mouse events and could lead to unexpected results.
+    const clientX = Math.round(left + relativeX);
+    const clientY = Math.round(top + relativeY);
+
+    this._dispatchPointerEventIfSupported('pointerdown', clientX, clientY, button);
+    dispatchMouseEvent(this.element, 'mousedown', clientX, clientY, button);
+    this._dispatchPointerEventIfSupported('pointerup', clientX, clientY, button);
+    dispatchMouseEvent(this.element, 'mouseup', clientX, clientY, button);
+    dispatchMouseEvent(this.element, name, clientX, clientY, button);
+  }
 }

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

@@ -326,6 +326,13 @@ export function crossEnvironmentSpecs(
       expect(await clickTestResult.text()).toBe('50-50');
     });
 
+    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 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 contextmenuTestResult = this.locatorFor('.contextmenu-test-result');
   // Allow null for element
   readonly nullItem = this.locatorForOptional('wrong locator');
   // Allow null for component harness

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

@@ -1,8 +1,9 @@
-<div class="click-test" (click)="onClick($event)"
+<div class="click-test" (click)="onClick($event)" (contextmenu)="onRightClick($event)"
      style="width: 100px; height: 100px; background: grey"
      #clickTestElement>
 </div>
-<div class="click-test-result">{{relativeX}}-{{relativeY}}</div>
+<div class="click-test-result">{{clickResult.x}}-{{clickResult.y}}</div>
+<div class="contextmenu-test-result">{{rightClickResult.x}}-{{rightClickResult.y}}-{{rightClickResult.button}}</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

@@ -41,9 +41,9 @@ export class TestMainComponent implements OnDestroy {
   testMethods: string[];
   _isHovering: boolean;
   specialKey = '';
-  relativeX = 0;
-  relativeY = 0;
   _shadowDomSupported = _supportsShadowDom();
+  clickResult = {x: -1, y: -1};
+  rightClickResult = {x: -1, y: -1, button: -1};
 
   @ViewChild('clickTestElement') clickTestElement: ElementRef<HTMLElement>;
   @ViewChild('taskStateResult') taskStateResultElement: ElementRef<HTMLElement>;
@@ -98,14 +98,23 @@ export class TestMainComponent implements OnDestroy {
   }
 
   onClick(event: MouseEvent) {
-    const {top, left} = this.clickTestElement.nativeElement.getBoundingClientRect();
-    this.relativeX = Math.round(event.clientX - left);
-    this.relativeY = Math.round(event.clientY - top);
+    this._assignRelativeCoordinates(event, this.clickResult);
+  }
+
+  onRightClick(event: MouseEvent) {
+    this.rightClickResult.button = event.button;
+    this._assignRelativeCoordinates(event, this.rightClickResult);
   }
 
   runTaskOutsideZone() {
     this._zone.runOutsideAngular(() => setTimeout(() => {
       this.taskStateResultElement.nativeElement.textContent = 'result';
     }, 100));
   }
+
+  private _assignRelativeCoordinates(event: MouseEvent, obj: {x: number, y: number}) {
+    const {top, left} = this.clickTestElement.nativeElement.getBoundingClientRect();
+    obj.x = Math.round(event.clientX - left);
+    obj.y = Math.round(event.clientY - top);
+  }
 }

tools/public_api_guard/cdk/testing.d.ts

@@ -130,6 +130,7 @@ export interface TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
+    rightClick?(relativeX: number, relativeY: number): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue?(value: string): Promise<void>;

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

@@ -14,6 +14,7 @@ export declare class ProtractorElement implements TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
+    rightClick(...args: number[]): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue(value: string): Promise<void>;

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

@@ -31,6 +31,7 @@ export declare class UnitTestElement implements TestElement {
     isFocused(): Promise<boolean>;
     matchesSelector(selector: string): Promise<boolean>;
     mouseAway(): Promise<void>;
+    rightClick(...args: number[]): Promise<void>;
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue(value: string): Promise<void>;