docs(cdk/testing): add documentation for harness environment authors

Author: mmalerba

src/cdk/testing/test-element.ts

@@ -56,7 +56,7 @@ export interface TestElement {
   /** Blur the element. */
   blur(): Promise<void>;
 
-  /** Clear the element's input (for input elements only). */
+  /** Clear the element's input (for input and textarea elements only). */
   clear(): Promise<void>;
 
   /**

src/cdk/testing/testing.md

@@ -549,4 +549,83 @@ may need to explicitly wait for tasks outside `NgZone`, as this does not happen
 
 ### API for harness environment authors
 
-TODO(mmalerba): Fill in docs for harness environment authors
+Harness environment authors are developers who want to add support for using component harnesses in
+additional testing environments. Out of the box, these harnesses can be used in Protractor E2E tests
+and Karma unit tests. Support for a new testing environment can be added by creating new
+`TestElement` and `HarnessEnvironment` implementations for the environment.
+
+#### Creating a `TestElement` implementation for the environment
+
+The first step in adding support for a new testing environment is to create a `TestElement`
+implementation. `TestElement` is simply an interface that serves as an environment-agnostic
+representation of a DOM element. It provides a way for harnesses to interact with DOM elements
+regardless of the environment they're used in. Because it is not possible to interact with elements
+synchronously in all test environments (e.g. Protractor), all of the methods on this interface are
+asynchronous and return a `Promise` with the result of the operation.
+
+| Method | Description |
+| ------ | ----------- |
+| `blur(): Promise<void>` | Blurs the element. |
+| `clear(): Promise<void>` | Clears the text from an element (only applies for `<input>` and `<textarea>`). |
+| `click(relativeX?: number, relativeY?: number): Promise<void>` | Clicks an element at a point relative to it's top-left corner. |
+| `focus(): Promise<void>` | Focuses the element. |
+| `getCssValue(property: string): Promise<string>` | Gets the computed CSS value of the given property for the element. |
+| `hover(): Promise<void>` | Hovers the mouse over the element. |
+| `sendKeys(...keys: (string \| TestKey)[]): Promise<void>` | Sends a sequence of key events to the element. |
+| `sendKeys(modifiers: ModifierKeys, ...keys: (string \| TestKey)[]): Promise<void>` | Sends a sequence of key events to the element, while holding a set of modifier keys. |
+| `text(): Promise<string>` | Gets the text content of the element. |
+| `getAttribute(name: string): Promise<string \| null>` | Gets the value of the given HTML attribute for the element. |
+| `hasClass(name: string): Promise<boolean>` | Checks whether the element has the given class. |
+| `getDimensions(): Promise<ElementDimensions>` | Gets the dimensions of the element. |
+| `getProperty(name: string): Promise<any>` | Gets the value of the given property for the element. |
+| `matchesSelector(selector: string): Promise<boolean>` | Checks whether the given selector matches the element. |
+
+The `TestElement` interface consists largely of methods that look very similar to the methods
+available on an `HTMLElement`; because of this, similar methods likely exist in most test
+environments, which makes implementing the methods fairly straightforward. However, one important
+difference to note when implementing the `sendKeys` method, is that the key codes in the `TestKey`
+enum likely differ from the key codes used in the test environment. It is recommended to maintain a
+mapping from `TestKey` codes to the codes used in the particular testing environment.
+
+Note: the 
+[`UnitTestElement`](https://github.com/angular/components/blob/master/src/cdk/testing/testbed/unit-test-element.ts#L57)
+and 
+[`ProtractorElement`](https://github.com/angular/components/blob/master/src/cdk/testing/protractor/protractor-element.ts#L67)
+implementations that come with the CDK serve as good examples of implementations of this interface.
+
+#### Creating a `HarnessEnvironemnt` implementation for the environment
+
+`HarnessEnvironment` is an abstract class that needs to be extended to create a concrete subclass to
+be used with the new environment. This is the class that test authors will use to actually create
+component harness instances for use in their tests. 
+
+The first step in creating a `HarnessEnvironment` implementation for a new testing environment is to
+extend `HarnessEnvironment` and fill in implementations for the abstract methods. The
+`HarnessEnvironment` is generic on the raw element type of the environment, `E`. When extending the
+class, it is recommended to fix this generic parameter to the correct type for the environment
+(e.g. `Element` for the `TestbedHarnessEnvironment`, `ElementFinder` for the
+`ProtractorHarnessEnvironment`). The following are the abstract methods that must be implemented:
+
+| Method | Description |
+| ------ | ----------- |
+| `abstract getDocumentRoot(): E` | Gets the root element for the environment (e.g. `document.body`). |
+| `abstract createTestElement(element: E): TestElement` | Creates a `TestElement` for the given raw element. |
+| `abstract createEnvironment(element: E): HarnessEnvironment` | Creates a `HarnessEnvironment` rooted at the given raw element. |
+| `abstract getAllRawElements(selector: string): Promise<E[]>` | Gets all of the raw elements under the root element of the environment matching the given selector. |
+| `abstract forceStabilize(): Promise<void>` | Gets a `Promise` that resolves when the `NgZone` is stable. Additionally, if applicable, tells `NgZone` to stabilize (e.g. calling `flush()` in a `fakeAsync` test). |
+| `abstract waitForTasksOutsideAngular(): Promise<void>` | Gets a `Promise` that resolves when the parent zone of `NgZone` is stable. |
+
+In addition to implementing the missing methods, this class should provide a way for test authors to
+get `ComponentHarness` instances. The recommended approach is to have a protected constructor and
+provide a static method called `loader` that returns a `HarnessLoader` instance. This allows test
+authors to write code like: `SomeHarnessEnvironment.loader().getHarness(...)`. Depending on the
+needs of the particular environment, the class may provide several different static methods or
+require arguments to be passed. (e.g. the `loader` method on `TestbedHarnessEnvironment` takes a
+`ComponentFixture`, and the class provides additional static methods called `documentRootLoader` and
+`harnessForFixture`).
+
+Note: the 
+[`TestbedHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/testbed/testbed-harness-environment.ts#L20)
+and 
+[`ProtractorHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/protractor/protractor-harness-environment.ts#L16)
+implementations that come with the CDK serve as good examples of implementations of this interface.