add tsdoc comments

Author: mmalerba

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

@@ -8,65 +8,254 @@
 
 import {TestElement} from './test-element';
 
-/** An async function that returns a promise of the given type when called. */
+/** An async function that returns a promise when called. */
 export type AsyncFn<T> = () => Promise<T>;
 
+/**
+ * Interface used to load ComponentHarness objects. This interface is used by test authors to
+ * instantiate `ComponentHarness`es.
+ */
 export interface HarnessLoader {
+  /**
+   * Searches for an element with the given selector under the current instances's root element,
+   * and returns a `HarnessLoader` rooted at the matching element. If multiple elements match the
+   * selector, the first is used. If no elements match, an error is thrown.
+   * @param selector The selector for the root element of the new `HarnessLoader`
+   * @return A `HarnessLoader` rooted at the element matching the given selector.
+   * @throws If a matching element can't be found.
+   */
   findRequired(selector: string): Promise<HarnessLoader>;
+
+  /**
+   * Searches for an element with the given selector under the current instances's root element,
+   * and returns a `HarnessLoader` rooted at the matching element. If multiple elements match the
+   * selector, the first is used. If no elements match, null is returned.
+   * @param selector The selector for the root element of the new `HarnessLoader`
+   * @return A `HarnessLoader` rooted at the element matching the given selector, or null if no
+   *     matching element was found.
+   */
   findOptional(selector: string): Promise<HarnessLoader | null>;
+
+  /**
+   * Searches for all elements with the given selector under the current instances's root element,
+   * and returns an array of `HarnessLoader`s, one for each matching element, rooted at that
+   * element.
+   * @param selector The selector for the root element of the new `HarnessLoader`
+   * @return A list of `HarnessLoader`s, one for each matching element, rooted at that element.
+   */
   findAll(selector: string): Promise<HarnessLoader[]>;
-  requiredHarness<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): Promise<T>;
-  optionalHarness<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
+
+  /**
+   * Searches for an instance of the component corresponding to the given harness type under the
+   * `HarnessLoader`'s root element, and returns a `ComponentHarness` for that instance. If multiple
+   * matching components are found, a harness for the first one is returned. If no matching
+   * component is found, an error is thrown.
+   * @param harnessType The type of harness to create
+   * @return An instance of the given harness type
+   * @throws If a matching component instance can't be found.
+   */
+  requiredHarness<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
+      Promise<T>;
+
+  /**
+   * Searches for an instance of the component corresponding to the given harness type under the
+   * `HarnessLoader`'s root element, and returns a `ComponentHarness` for that instance. If multiple
+   * matching components are found, a harness for the first one is returned. If no matching
+   * component is found, null is returned.
+   * @param harnessType The type of harness to create
+   * @return An instance of the given harness type, or null if none is found.
+   */
+  optionalHarness<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
       Promise<T | null>;
-  allHarnesses<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): Promise<T[]>;
+
+  /**
+   * Searches for all instances of the component corresponding to the given harness type under the
+   * `HarnessLoader`'s root element, and returns a list `ComponentHarness` for each instance.
+   * @param harnessType The type of harness to create
+   * @return A list instances of the given harness type.
+   */
+  allHarnesses<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
+      Promise<T[]>;
 }
 
+/**
+ * Interface used to create asynchronous locator functions used find elements and component
+ * harnesses. This interface is used by `ComponentHarness` authors to create locator functions for
+ * their `ComponentHarenss` subclass.
+ */
 export interface LocatorFactory {
+  /** Gets a locator factory rooted at the document root. */
   documentRootLocatorFactory(): LocatorFactory;
+
+  /** Gets the root element of this `LocatorFactory` as a `TestElement`. */
   rootElement(): TestElement;
+
+  /**
+   * Creates an asynchronous locator function that can be used to search for elements with the given
+   * selector under the root element of this `LocatorFactory`. When the resulting locator function
+   * is invoked, if multiple matching elements are found, the first element is returned. If no
+   * elements are found, an error is thrown.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or throws an error
+   */
   requiredLocator(selector: string): AsyncFn<TestElement>;
-  requiredLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): AsyncFn<T>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a `ComponentHarness` for a
+   * component matching the given harness type under the root element of this `LocatorFactory`.
+   * When the resulting locator function is invoked, if multiple matching components are found, a
+   * harness for the first one is returned. If no components are found, an error is thrown.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and either returns a `ComponentHarness` for the component, or throws an error.
+   */
+  requiredLocator<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
+      AsyncFn<T>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to search for elements with the given
+   * selector under the root element of this `LocatorFactory`. When the resulting locator function
+   * is invoked, if multiple matching elements are found, the first element is returned. If no
+   * elements are found, null is returned.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or returns null.
+   */
   optionalLocator(selector: string): AsyncFn<TestElement | null>;
-  optionalLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a `ComponentHarness` for a
+   * component matching the given harness type under the root element of this `LocatorFactory`.
+   * When the resulting locator function is invoked, if multiple matching components are found, a
+   * harness for the first one is returned. If no components are found, null is returned.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and either returns a `ComponentHarness` for the component, or null if none is found.
+   */
+  optionalLocator<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
       AsyncFn<T | null>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to search for a list of elements with
+   * the given selector under the root element of this `LocatorFactory`. When the resulting locator
+   * function is invoked, a list of matching elements is returned.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or throws an error
+   */
   allLocator(selector: string): AsyncFn<TestElement[]>;
-  allLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): AsyncFn<T[]>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a list of
+   * `ComponentHarness`es for all components matching the given harness type under the root element
+   * of this `LocatorFactory`. When the resulting locator function is invoked, a list of
+   * `ComponentHarness`es for the matching components is returned.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and returns a list of `ComponentHarness`es.
+   */
+  allLocator<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>): AsyncFn<T[]>;
 }
 
 /**
- * Base Component Harness
- * This base component harness provides the basic ability to locate element and
- * sub-component harness. It should be inherited when defining user's own
- * harness.
+ * Base class for component harnesses that all component harness authors should extend. This base
+ * component harness provides the basic ability to locate element and sub-component harness. It
+ * should be inherited when defining user's own harness.
  */
 export abstract class ComponentHarness {
   constructor(private readonly locatorFacotry: LocatorFactory) {}
 
-  async host() {
+  /** Gets a `Promise` for the `TestElement` representing the host element of the component. */
+  async host(): Promise<TestElement> {
     return this.locatorFacotry.rootElement();
   }
 
+  /**
+   * Gets a `LocatorFactory` for the document root element. This factory can be used to create
+   * locators for elements that a component creates outside of its own root element. (e.g. by
+   * appending to document.body).
+   */
   protected documentRootLocatorFactory(): LocatorFactory {
     return this.locatorFacotry.documentRootLocatorFactory();
   }
 
+  /**
+   * Creates an asynchronous locator function that can be used to search for elements with the given
+   * selector under the host element of this `ComponentHarness`. When the resulting locator function
+   * is invoked, if multiple matching elements are found, the first element is returned. If no
+   * elements are found, an error is thrown.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or throws an error
+   */
   protected requiredLocator(selector: string): AsyncFn<TestElement>;
-  protected requiredLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
-      AsyncFn<T>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a `ComponentHarness` for a
+   * component matching the given harness type under the host element of this `ComponentHarness`.
+   * When the resulting locator function is invoked, if multiple matching components are found, a
+   * harness for the first one is returned. If no components are found, an error is thrown.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and either returns a `ComponentHarness` for the component, or throws an error.
+   */
+  protected requiredLocator<T extends ComponentHarness>(
+      harnessType: ComponentHarnessConstructor<T>): AsyncFn<T>;
+
   protected requiredLocator(arg: any): any {
     return this.locatorFacotry.requiredLocator(arg);
   }
 
+  /**
+   * Creates an asynchronous locator function that can be used to search for elements with the given
+   * selector under the host element of this `ComponentHarness`. When the resulting locator function
+   * is invoked, if multiple matching elements are found, the first element is returned. If no
+   * elements are found, null is returned.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or returns null.
+   */
   protected optionalLocator(selector: string): AsyncFn<TestElement | null>;
-  protected optionalLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
-      AsyncFn<T | null>;
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a `ComponentHarness` for a
+   * component matching the given harness type under the host element of this `ComponentHarness`.
+   * When the resulting locator function is invoked, if multiple matching components are found, a
+   * harness for the first one is returned. If no components are found, null is returned.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and either returns a `ComponentHarness` for the component, or null if none is found.
+   */
+  protected optionalLocator<T extends ComponentHarness>(
+      harnessType: ComponentHarnessConstructor<T>): AsyncFn<T | null>;
+
   protected optionalLocator(arg: any): any {
     return this.locatorFacotry.optionalLocator(arg);
   }
 
+  /**
+   * Creates an asynchronous locator function that can be used to search for a list of elements with
+   * the given selector under the host element of this `ComponentHarness`. When the resulting
+   * locator function is invoked, a list of matching elements is returned.
+   * @param selector The selector for the element that the locator function should search for.
+   * @return An asynchronous locator function that searches for elements with the given selector,
+   *     and either finds one or throws an error
+   */
   protected allLocator(selector: string): AsyncFn<TestElement[]>;
-  protected allLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
+
+  /**
+   * Creates an asynchronous locator function that can be used to find a list of
+   * `ComponentHarness`es for all components matching the given harness type under the host element
+   * of this `ComponentHarness`. When the resulting locator function is invoked, a list of
+   * `ComponentHarness`es for the matching components is returned.
+   * @param harnessType The type of harness to search for.
+   * @return An asynchronous locator function that searches components matching the given harness
+   *     type, and returns a list of `ComponentHarness`es.
+   */
+  protected allLocator<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>):
       AsyncFn<T[]>;
+
   protected allLocator(arg: any): any {
     return this.locatorFacotry.allLocator(arg);
   }
@@ -76,5 +265,10 @@ export abstract class ComponentHarness {
 export interface ComponentHarnessConstructor<T extends ComponentHarness> {
   new(locatorFactory: LocatorFactory): T;
 
+  /**
+   * `ComponentHarness` subclasses must specify a static `hostSelector` property that is used to
+   * find the host element for the corresponding component. This property should match the selector
+   * for the Angular component.
+   */
   hostSelector: string;
 }

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

@@ -15,16 +15,24 @@ import {
 } from './component-harness';
 import {TestElement} from './test-element';
 
-/** Interface that is used to find elements in the DOM and create harnesses for them. */
-export abstract class AbstractHarnessEnvironment<E> implements HarnessLoader, LocatorFactory {
+/**
+ * Base harness environment class that can be extended to allow `ComponentHarness`es to be used in
+ * different test environments (e.g. testbed, protractor, etc.). This class implements the
+ * functionality of both a `HarnessLoader` and `LocatorFactory`. This class is generic on the raw
+ * element type, `E`, used by the particular test environment.
+ */
+export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFactory {
   protected constructor(protected rawRootElement: E) {}
 
+  // Part of the `HarnessLoader` interface, delegated to concrete implementation.
   abstract documentRootLocatorFactory(): LocatorFactory;
 
+  // Implemented as part of the `LocatorFactory` interface.
   rootElement(): TestElement {
     return this.createTestElement(this.rawRootElement);
   }
 
+  // Implemented as part of the `LocatorFactory` interface.
   requiredLocator(selector: string): AsyncFn<TestElement>;
   requiredLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): AsyncFn<T>;
   requiredLocator<T extends ComponentHarness>(
@@ -46,6 +54,7 @@ export abstract class AbstractHarnessEnvironment<E> implements HarnessLoader, Lo
     };
   }
 
+  // Implemented as part of the `LocatorFactory` interface.
   optionalLocator(selector: string): AsyncFn<TestElement | null>;
   optionalLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
       AsyncFn<T | null>;
@@ -62,6 +71,7 @@ export abstract class AbstractHarnessEnvironment<E> implements HarnessLoader, Lo
     };
   }
 
+  // Implemented as part of the `LocatorFactory` interface.
   allLocator(selector: string): AsyncFn<TestElement[]>;
   allLocator<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): AsyncFn<T[]>;
   allLocator<T extends ComponentHarness>(
@@ -76,19 +86,23 @@ export abstract class AbstractHarnessEnvironment<E> implements HarnessLoader, Lo
     };
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   requiredHarness<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): Promise<T> {
     return this.requiredLocator(harness)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   optionalHarness<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>):
     Promise<T | null> {
     return this.optionalLocator(harness)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   allHarnesses<T extends ComponentHarness>(harness: ComponentHarnessConstructor<T>): Promise<T[]> {
     return this.allLocator(harness)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   async findRequired(selector: string): Promise<HarnessLoader> {
     const element = await this.getRawElement(selector);
     if (element) {
@@ -97,23 +111,35 @@ export abstract class AbstractHarnessEnvironment<E> implements HarnessLoader, Lo
     throw Error(`Expected to find element matching selector: "${selector}", but none was found`);
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   async findOptional(selector: string): Promise<HarnessLoader | null> {
     const element = await this.getRawElement(selector);
     return element ? this.createHarnessLoader(element) : null;
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
   async findAll(selector: string): Promise<HarnessLoader[]> {
     return (await this.getAllRawElements(selector)).map(e => this.createHarnessLoader(e));
   }
 
+  /** Creates a `TestElement` from a raw element. */
   protected abstract createTestElement(element: E): TestElement;
 
+  /** Creates a `ComponentHarness` for the given harness type with the given raw host element. */
   protected abstract createComponentHarness<T extends ComponentHarness>(
     harnessType: ComponentHarnessConstructor<T>, element: E): T;
 
+  /** Creates a `HarnessLoader` rooted at the given raw element. */
   protected abstract createHarnessLoader(element: E): HarnessLoader;
 
+  /**
+   * Gets the first element matching the given selector under this environment's root element, or
+   * null if no elements match.
+   */
   protected abstract getRawElement(selector: string): Promise<E | null>;
 
+  /**
+   * Gets a list of all elements matching the given selector under this environment's root element.
+   */
   protected abstract getAllRawElements(selector: string): Promise<E[]>;
 }

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

@@ -9,6 +9,7 @@
 import {browser, ElementFinder} from 'protractor';
 import {TestElement} from '../test-element';
 
+/** A `TestElement` implementation for Protractor. */
 export class ProtractorElement implements TestElement {
   constructor(readonly element: ElementFinder) {}