address @jelbourn's comments

Author: mmalerba

src/cdk-experimental/testing/component-harness.ts

@@ -6,61 +6,33 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-/**
- * Test Element interface
- * This is a wrapper of native element
- */
-export interface TestElement {
-  blur(): Promise<void>;
-  clear(): Promise<void>;
-  click(): Promise<void>;
-  focus(): Promise<void>;
-  getCssValue(property: string): Promise<string>;
-  hover(): Promise<void>;
-  sendKeys(keys: string): Promise<void>;
-  text(): Promise<string>;
-  getAttribute(name: string): Promise<string|null>;
-}
+import {TestElement} from './test-element';
 
-/**
- * Extra searching options used by searching functions
- *
- * @param allowNull Optional, whether the found element can be null. If
- * allowNull is set, the searching function will always try to fetch the element
- * at once. When the element cannot be found, the searching function should
- * return null if allowNull is set to true, throw an error if allowNull is set
- * to false. If allowNull is not set, the framework will choose the behaviors
- * that make more sense for each test type (e.g. for unit test, the framework
- * will make sure the element is not null; otherwise throw an error); however,
- * the internal behavior is not guaranteed and user should not rely on it. Note
- * that in most cases, you don't need to care about whether an element is
- * present when loading the element and don't need to set this parameter unless
- * you do want to check whether the element is present when calling the
- * searching function. e.g. you want to make sure some element is not there when
- * loading the element in order to check whether a "ngif" works well.
- *
- * @param global Optional. If global is set to true, the selector will match any
- *     element on the page and is not limited to the root of the harness. If
- * global is unset or set to false, the selector will only find elements under
- * the current root.
- */
-export interface Options {
+/** Options that can be specified when querying for an Element. */
+export interface QueryOptions {
+  /**
+   * Whether the found element can be null. If allowNull is set, the searching function will always
+   * try to fetch the element at once. When the element cannot be found, the searching function
+   * should return null if allowNull is set to true, throw an error if allowNull is set to false.
+   * If allowNull is not set, the framework will choose the behaviors that make more sense for each
+   * test type (e.g. for unit test, the framework will make sure the element is not null; otherwise
+   * throw an error); however, the internal behavior is not guaranteed and user should not rely on
+   * it. Note that in most cases, you don't need to care about whether an element is present when
+   * loading the element and don't need to set this parameter unless you do want to check whether
+   * the element is present when calling the searching function. e.g. you want to make sure some
+   * element is not there when loading the element in order to check whether a "ngif" works well.
+   */
   allowNull?: boolean;
+  /**
+   * If global is set to true, the selector will match any element on the page and is not limited to
+   * the root of the harness. If global is unset or set to false, the selector will only find
+   * elements under the current root.
+   */
   global?: boolean;
 }
 
-/**
- * Type narrowing of Options to allow the overloads of ComponentHarness.find to
- * return null only if allowNull is set to true.
- */
-interface OptionsWithAllowNullSet extends Options {
-  allowNull: true;
-}
-
-/**
- * Locator interface
- */
-export interface Locator {
+/** Interface that is used to find elements in the DOM and create harnesses for them. */
+export interface HarnessLocator {
   /**
    * Get the host element of locator.
    */
@@ -71,7 +43,7 @@ export interface Locator {
    * @param selector The CSS selector of the test elements.
    * @param options Optional, extra searching options
    */
-  querySelector(selector: string, options?: Options): Promise<TestElement|null>;
+  querySelector(selector: string, options?: QueryOptions): Promise<TestElement|null>;
 
   /**
    * Search all matched test elements under current root by CSS selector.
@@ -86,16 +58,16 @@ export interface Locator {
    * @param options Optional, extra searching options
    */
   load<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, root: string,
-    options?: Options): Promise<T|null>;
+    componentHarness: ComponentHarnessConstructor<T>, root: string,
+    options?: QueryOptions): Promise<T|null>;
 
   /**
    * Load all Component Harnesses under current root.
    * @param componentHarness Type of user customized harness.
    * @param root CSS root selector of the new component harnesses.
    */
   loadAll<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, root: string): Promise<T[]>;
+    componentHarness: ComponentHarnessConstructor<T>, root: string): Promise<T[]>;
 }
 
 /**
@@ -104,8 +76,8 @@ export interface Locator {
  * sub-component harness. It should be inherited when defining user's own
  * harness.
  */
-export class ComponentHarness {
-  constructor(private readonly locator: Locator) {}
+export abstract class ComponentHarness {
+  constructor(private readonly locator: HarnessLocator) {}
 
   /**
    * Get the host element of component harness.
@@ -127,7 +99,7 @@ export class ComponentHarness {
    * @param selector The CSS selector of the test element.
    * @param options Extra searching options
    */
-  protected find(selector: string, options: OptionsWithAllowNullSet):
+  protected find(selector: string, options: QueryOptions & {allowNull: true}):
     () => Promise<TestElement|null>;
 
   /**
@@ -136,15 +108,15 @@ export class ComponentHarness {
    * @param selector The CSS selector of the test element.
    * @param options Extra searching options
    */
-  protected find(selector: string, options: Options): () => Promise<TestElement>;
+  protected find(selector: string, options: QueryOptions): () => Promise<TestElement>;
 
   /**
    * Generate a function to find the first matched Component Harness.
    * @param componentHarness Type of user customized harness.
    * @param root CSS root selector of the new component harness.
    */
   protected find<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>,
+    componentHarness: ComponentHarnessConstructor<T>,
     root: string): () => Promise<T>;
 
   /**
@@ -154,8 +126,8 @@ export class ComponentHarness {
    * @param options Extra searching options
    */
   protected find<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, root: string,
-    options: OptionsWithAllowNullSet): () => Promise<T|null>;
+    componentHarness: ComponentHarnessConstructor<T>, root: string,
+    options: QueryOptions & {allowNull: true}): () => Promise<T|null>;
 
   /**
    * Generate a function to find the first matched Component Harness.
@@ -164,16 +136,16 @@ export class ComponentHarness {
    * @param options Extra searching options
    */
   protected find<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, root: string,
-    options: Options): () => Promise<T>;
+    componentHarness: ComponentHarnessConstructor<T>, root: string,
+    options: QueryOptions): () => Promise<T>;
 
   protected find<T extends ComponentHarness>(
-    selectorOrComponentHarness: string|ComponentHarnessType<T>,
-    selectorOrOptions?: string|Options,
-    options?: Options): () => Promise<TestElement|T|null> {
+    selectorOrComponentHarness: string|ComponentHarnessConstructor<T>,
+    selectorOrOptions?: string|QueryOptions,
+    options?: QueryOptions): () => Promise<TestElement|T|null> {
     if (typeof selectorOrComponentHarness === 'string') {
       const selector = selectorOrComponentHarness;
-      return () => this.locator.querySelector(selector, selectorOrOptions as Options);
+      return () => this.locator.querySelector(selector, selectorOrOptions as QueryOptions);
     } else {
       const componentHarness = selectorOrComponentHarness;
       const selector = selectorOrOptions as string;
@@ -196,11 +168,11 @@ export class ComponentHarness {
    * locate harnesses under the current root.
    */
   protected findAll<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>,
+    componentHarness: ComponentHarnessConstructor<T>,
     root: string): () => Promise<T[]>;
 
   protected findAll<T extends ComponentHarness>(
-    selectorOrComponentHarness: string|ComponentHarnessType<T>,
+    selectorOrComponentHarness: string|ComponentHarnessConstructor<T>,
     root?: string): () => Promise<TestElement[]|T[]> {
     if (typeof selectorOrComponentHarness === 'string') {
       const selector = selectorOrComponentHarness;
@@ -212,9 +184,7 @@ export class ComponentHarness {
   }
 }
 
-/**
- * Type of ComponentHarness.
- */
-export interface ComponentHarnessType<T extends ComponentHarness> {
-  new(locator: Locator): T;
+/** Constructor for a ComponentHarness subclass. */
+export interface ComponentHarnessConstructor<T extends ComponentHarness> {
+  new(locator: HarnessLocator): T;
 }

src/cdk-experimental/testing/protractor.ts

@@ -13,11 +13,11 @@ import {browser, by, element as protractorElement, ElementFinder} from 'protract
 
 import {
   ComponentHarness,
-  ComponentHarnessType,
-  Locator,
-  Options,
-  TestElement
+  ComponentHarnessConstructor,
+  HarnessLocator,
+  QueryOptions
 } from './component-harness';
+import {TestElement} from './test-element';
 
 /**
  * Component harness factory for protractor.
@@ -31,7 +31,7 @@ import {
  * Set to 'body' by default
  */
 export async function load<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>,
+    componentHarness: ComponentHarnessConstructor<T>,
     rootSelector: string): Promise<T>;
 
 /**
@@ -42,12 +42,12 @@ export async function load<T extends ComponentHarness>(
  * @param options Optional. Extra searching options
  */
 export async function load<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, rootSelector?: string,
-    options?: Options): Promise<T|null>;
+  componentHarness: ComponentHarnessConstructor<T>, rootSelector?: string,
+  options?: QueryOptions): Promise<T|null>;
 
 export async function load<T extends ComponentHarness>(
-    componentHarness: ComponentHarnessType<T>, rootSelector = 'body',
-    options?: Options): Promise<T|null> {
+  componentHarness: ComponentHarnessConstructor<T>, rootSelector = 'body',
+  options?: QueryOptions): Promise<T|null> {
   const root = await getElement(rootSelector, undefined, options);
   return root && new componentHarness(new ProtractorLocator(root));
 }
@@ -60,10 +60,10 @@ export function getElementFinder(testElement: TestElement): ElementFinder {
     return testElement.element;
   }
 
-  throw new Error('Invalid element provided');
+  throw Error(`Expected an instance of ProtractorElement, got ${testElement}`);
 }
 
-class ProtractorLocator implements Locator {
+class ProtractorLocator implements HarnessLocator {
   private readonly _root: ProtractorElement;
 
   constructor(private _rootFinder: ElementFinder) {
@@ -74,41 +74,34 @@ class ProtractorLocator implements Locator {
     return this._root;
   }
 
-  async querySelector(selector: string, options?: Options): Promise<TestElement|null> {
+  async querySelector(selector: string, options?: QueryOptions): Promise<TestElement|null> {
     const finder = await getElement(selector, this._rootFinder, options);
     return finder && new ProtractorElement(finder);
   }
 
   async querySelectorAll(selector: string): Promise<TestElement[]> {
     const elementFinders = this._rootFinder.all(by.css(selector));
-    const res: TestElement[] = [];
-    await elementFinders.each(el => {
-      if (el) {
-        res.push(new ProtractorElement(el));
-      }
-    });
-    return res;
+    return elementFinders.reduce(
+      (result: TestElement[], el: ElementFinder) =>
+          el ? result.concat([new ProtractorElement(el)]) : result,
+      []);
   }
 
   async load<T extends ComponentHarness>(
-      componentHarness: ComponentHarnessType<T>, selector: string,
-      options?: Options): Promise<T|null> {
+    componentHarness: ComponentHarnessConstructor<T>, selector: string,
+    options?: QueryOptions): Promise<T|null> {
     const root = await getElement(selector, this._rootFinder, options);
     return root && new componentHarness(new ProtractorLocator(root));
   }
 
   async loadAll<T extends ComponentHarness>(
-      componentHarness: ComponentHarnessType<T>,
+      componentHarness: ComponentHarnessConstructor<T>,
       rootSelector: string): Promise<T[]> {
     const roots = this._rootFinder.all(by.css(rootSelector));
-    const res: T[] = [];
-    await roots.each(el => {
-      if (el) {
-        const locator = new ProtractorLocator(el);
-        res.push(new componentHarness(locator));
-      }
-    });
-    return res;
+    return roots.reduce(
+        (result: T[], el: ElementFinder) =>
+            el ? result.concat(new componentHarness(new ProtractorLocator(el))) : result,
+        []);
   }
 }
 
@@ -163,7 +156,7 @@ class ProtractorElement implements TestElement {
  * search element globally. If options.global is set, root is ignored.
  * @param options Optional, extra searching options
  */
-async function getElement(selector: string, root?: ElementFinder, options?: Options):
+async function getElement(selector: string, root?: ElementFinder, options?: QueryOptions):
   Promise<ElementFinder|null> {
   const useGlobalRoot = options && !!options.global;
   const elem = root === undefined || useGlobalRoot ?
@@ -174,7 +167,7 @@ async function getElement(selector: string, root?: ElementFinder, options?: Opti
     if (allowNull) {
       return null;
     }
-    throw new Error('Cannot find element based on the CSS selector: ' + selector);
+    throw Error('Cannot find element based on the CSS selector: ' + selector);
   }
   return elem;
 }

src/cdk-experimental/testing/public-api.ts

@@ -10,4 +10,5 @@ import * as protractor from './protractor';
 import * as testbed from './testbed';
 
 export * from './component-harness';
+export * from './test-element';
 export {protractor, testbed};

src/cdk-experimental/testing/test-element.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * This acts as a common interface for DOM elements across both unit and e2e tests. It is the
+ * interface through which the ComponentHarness interacts with the component's DOM.
+ */
+export interface TestElement {
+  /** Blur the element. */
+  blur(): Promise<void>;
+
+  /** Clear the element's input (for input elements only). */
+  clear(): Promise<void>;
+
+  /** Click the element. */
+  click(): Promise<void>;
+
+  /** Focus the element. */
+  focus(): Promise<void>;
+
+  /** Get the computed value of the given CSS property for the element. */
+  getCssValue(property: string): Promise<string>;
+
+  /** Hovers the mouse over the element. */
+  hover(): Promise<void>;
+
+  /**
+   * Sends the given string to the input as a series of key presses. Also fires input events
+   * and attempts to add the string to the Element's value.
+   */
+  sendKeys(keys: string): Promise<void>;
+
+  /** Gets the text from the element. */
+  text(): Promise<string>;
+
+  /**
+   * Gets the value for the given attribute from the element. If the attribute does not exist,
+   * falls back to reading the property.
+   */
+  getAttribute(name: string): Promise<string | null>;
+}