From cf0270c0c0feea70a55faf55ac09da4179e35766 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Tue, 22 Oct 2019 13:55:30 -0700
Subject: [PATCH 1/3] docs(cdk/testing): Add documentation for harness authors

---
 src/cdk/testing/testing.md | 393 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 383 insertions(+), 10 deletions(-)

diff --git a/src/cdk/testing/testing.md b/src/cdk/testing/testing.md
index bde9d78f4fec..860b5678d497 100644
--- a/src/cdk/testing/testing.md
+++ b/src/cdk/testing/testing.md
@@ -36,15 +36,15 @@ Test authors are developers using component harnesses written by someone else to
 application. For example, this could be an app developer who uses a third-party menu component and
 needs to interact with the menu in a unit test.
 
-#### `ComponentHarness`
+#### Working with `ComponentHarness` classes
 
-This is the abstract base class for all component harnesses. Every harness extends
-`ComponentHarness`. All `ComponentHarness` subclasses have a static property, `hostSelector`, that
+`ComponentHarness` is the abstract base class for all component harnesses. Every harness extends
+this class. All `ComponentHarness` subclasses have a static property, `hostSelector`, that
 matches the harness class to instances of the component in the DOM. Beyond that, the API of any
 given harness is specific to its corresponding component; refer to the component's documentation to
 learn how to use a specific harness.
 
-#### `TestbedHarnessEnvironment` and `ProtractorHarnessEnvironment`
+#### Using `TestbedHarnessEnvironment` and `ProtractorHarnessEnvironment`
 
 These classes correspond to different implementations of the component harness system with bindings
 for specific test environments. Any given test must only import _one_ of these classes. Karma-based
@@ -117,7 +117,7 @@ Since Protractor does not deal with fixtures, the API in this environment is sim
 `HarnessLoader` returned by the `loader()` method should be sufficient for loading all necessary
 `ComponentHarness` instances.
 
-#### `HarnessLoader`
+#### Creating harnesses with `HarnessLoader`
 
 Instances of this class correspond to a specific DOM element (the "root element" of the loader) and
 are used to create `ComponentHarness` instances for elements under this root element.
@@ -134,8 +134,8 @@ are used to create `ComponentHarness` instances for elements under this root ele
 Calls to `getHarness` and `getAllHarnesses` can either take `ComponentHarness` subclass or a 
 `HarnessPredicate`. `HarnessPredicate` applies additional restrictions to the search (e.g. searching
 for a button that has some particular text, etc). The
-[details of `HarnessPredicate`](#harnesspredicate) are discussed in the
-[API for component harness authors](#api-for-component-harness-authors); harness authors should
+[details of `HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) are discussed in
+the [API for component harness authors](#api-for-component-harness-authors); harness authors should
 provide convenience methods on their `ComponentHarness` subclass to facilitate creation of
 `HarnessPredicate` instances. However, if the harness author's API is not sufficient, they can be
 created manually.
@@ -169,11 +169,384 @@ it('reads properties in parallel', async () => {
 
 ### API for component harness authors
 
-TODO(mmalerba): Fill in docs for harness authors
+Component harness authors are developers who maintain some reusable Angular component, and want to
+create a test harness for it, that users of the component can use in their tests. For example, this
+could be an author of a third party Angular component library or a developer who maintains a set of
+common components for a large Angular application.
 
-#### `HarnessPredicate`
+#### Extending `ComponentHarness`
 
-TODO(mmalerba): Fill in docs for `HarnessPredicate`
+The abstract `ComponentHarness` class is the base class for all component harnesses. To work with
+the CDK's component harness infrastructure, a class must extend `ComponentHarness` and implement a
+static property `hostSelector`.  The `hostSelector` property is used to identify elements in the DOM
+that match this harness subclass. In most cases the `hostSelector` should be the same as the
+`selector` of the `Component` or `Directive` that the harness corresponds to. For example, consider
+a simple popup component with a helper directive to manage some accessibility attributes:
+
+```ts
+@Component({
+  selector: 'my-popup',
+  template: `
+    <button (click)="toggle()">{{triggerText}}</button>
+    <div *ngIf="open" class="my-popup-content"><ng-content></ng-content></div>
+  `
+})
+class MyPopup {
+  @Input() triggerText: string;
+
+  open = false;
+
+  toggle() {
+    this.open = !this.open;
+  }
+}
+```
+
+In this case, a minimal harness for the component would look like the following:
+
+```ts
+class MyPopupHarness extends ComponentHarness {
+  static hostSelector = 'my-popup';
+}
+```
+
+Other than the `hostSelector` property, there are no other properties or methods that are required
+to implement on a `ComponentHarness` subclass, though it is highly recommended to add a static
+`with` method that can be used to generate `HarnessPredicate` instances. This is discussed in more
+detail in the [`HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) section
+below.
+
+#### Finding elements in the component's DOM
+
+Each instance of the `ComponentHarness` subclass represents a particular instance of the
+corresponding component. The corresponding component instance's host element can be accessed via the
+`host` method on the `ComponentHarness` base class.
+
+In addition to being able to access the component's host element, `ComponentHarness` has several
+methods that can be used to locate elements under the host element; that is, elements that are part
+of the component's template or content. These methods are `locatorFor`, `locatorForOptional`, and
+`locatorForAll`. One important caveat to understand about these methods is that they do not find
+elements, they _create functions_ that can be used to find elements. This avoids caching references
+to elements that later turn stale (for example when an `ngIf` binding updates).
+
+| Method | Description |
+| ------ | ----------- |
+| `host(): Promise<TestElement>` | Returns a `Promise` for the host element of the corresponding component instance. |
+| `locatorFor(selector: string): () => Promise<TestElement>` | Creates a function that returns a `Promise` for the first element matching the given selector when called. If no matching element is found, the `Promise` rejects. |
+| `locatorForOptional(selector: string): () => Promise<TestElement \| null>` | Creates a function that returns a `Promise` for the first element matching the given selector when called. If no matching element is found, the `Promise` is resolved with `null`. |
+| `locatorForAll(selector: string): () => Promise<TestElement[]>` | Creates a function that returns a `Promise` for a list of all elements matching the given selector when called. |
+
+For example, the `MyPopupHarness` class discussed above could provide methods to get the trigger
+and content elements as follows:
+
+```ts
+class MyPopupHarness extends ComponentHarness {
+  static hostSelector = 'my-popup';
+
+  /** Gets the trigger element */
+  getTriggerElement = this.locatorFor('button');
+
+  /** Gets the content element. */
+  getContentElement = this.locatorForOptional('.my-popup-content');
+}
+```
+
+#### Working with `TestElement` instances
+
+The various methods described above for finding elements all return a `TestElement` class.
+`TestElement` offers a number of methods to interact with the underlying DOM:
+
+| Method | Description |
+| ------ | ----------- |
+| `blur(): Promise<void>` | Blurs the element. |
+| `clear(): Promise<void>` | Clears the text in the element (intended for `<input>` and `<textarea>` only). |
+| `click(relativeX?: number, relativeY?: number): Promise<void>` | Clicks the element (at the given position relative to the element's top-left corner). |
+| `focus(): Promise<void>` | Focuses the element. |
+| `getCssValue(property: string): Promise<string>` | Gets the computed value of the given CSS property for the element. |
+| `hover(): Promise<void>` | Hovers over the element. |
+| `sendKeys(modifiers?: ModifierKeys, ...keys: (string \| TestKey)[]): Promise<void>` | Sends the given list of key presses to the element (with optional 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 applied. |
+| `getDimensions(): Promise<ElementDimensions>` | Gets the dimensions of the element. |
+| `getProperty(name: string): Promise<any>` | Gets the value of the given JS property for the element. |
+| `matchesSelector(selector: string): Promise<boolean>` | Checks whether the element matches the given CSS selector. |
+
+`TestElement` is an abstraction designed to work across different test environments (Karma,
+Protractor, etc); therefore, it is important that all DOM interaction inside harness classes happens
+via this interface. `ComponentHarness` subclasses must _not_ use other means of accessing DOM
+elements (e.g. `document.querySelector`), otherwise it will not work in all test environments.
+
+As a best practice, it is recommended not to expose `TestElement` instances to users of a harness,
+unless its an element the user has some control over (e.g. the host element). Exposing `TestElement`
+instances for internal elements may lead users to depend on implementation details (e.g. assertions
+against particular attributes or classes in your component's template that may change later).
+
+Instead, consider providing more narrow-focused methods for particular actions the user may want to
+take or particular state they may want to check. For example, `MyPopupHarness` could provide methods
+like:
+
+```ts
+class MyPopupHarness extends ComponentHarness {
+  static hostSelector = 'my-popup';
+
+  protected getTriggerElement = this.locatorFor('button');
+  protected getContentElement = this.locatorForOptional('.my-popup-content');
+
+  /** Toggles the open state of the popup. */
+  async toggle() {
+    const trigger = await this.getTriggerElement();
+    return trigger.click();
+  }
+
+  /** Checks if the popup us open. */
+  async isOpen() {
+    const content = await this.getContentElement();
+    return !!content;
+  }
+}
+```
+
+#### Loading harnesses for subcomponents
+
+Often times larger components are made up of a composition of smaller components, and it can be
+useful to have this structure reflected in a component's harness as well. Each of the `locatorFor`
+methods on `ComponentHarness` discussed earlier has an alternate signature that can be used for
+locating sub-harnesses rather than elements.
+
+| Method | Description |
+| ------ | ----------- |
+| `locatorFor<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>): () => Promise<T>` | Creates a function that returns a `Promise` for the first harness matching the given harness type when called. If no matching harness is found, the `Promise` rejects. |
+| `locatorForOptional<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>): () => Promise<T \| null>` | Creates a function that returns a `Promise` for the first harness matching the given harness type when called. If no matching harness is found, the `Promise` is resolved with `null`. |
+| `locatorForAll<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T>): () => Promise<T[]>` | Creates a function that returns a `Promise` for a list of all harnesses matching the given harness type when called. |
+
+For example consider a menu build using the popup shown above:
+
+```ts
+@Component({
+  selector: 'my-menu',
+  template: `
+    <my-popup>
+      <ng-content></ng-content>
+    </my-popup>
+  `
+})
+class MyMenu {
+  @Input() triggerText: string;
+
+  @ContentChildren(MyMenuItem) items: QueryList<MyMenuItem>;
+}
+
+@Directive({
+  selector: 'my-menu-item'
+})
+class MyMenuItem {}
+```
+
+The harness for `MyMenu` can then take advantage of other harnesses for `MyPopup` and `MyMenuItem`:
+
+```ts
+class MyMenuHarness extends ComponentHarness {
+  static hostSelector = 'my-menu';
+
+  protected getPopupHarness = this.locatorFor(MyPopupHarness);
+
+  /** Gets the currently shown menu items (empty list if menu is closed). */
+  getItems = this.locatorForAll(MyMenuItemHarness);
+
+  /** Toggles open state of the menu. */
+  async toggle() {
+    const popupHarness = await this.getPopupHarness();
+    return popupHarness.toggle();
+  }
+}
+
+class MyMenuItemHarness extends ComponentHarness {
+  static hostSelector = 'my-menu-item';
+}
+```
+
+#### Filtering harness instances with `HarnessPredicate`
+
+When there are multiple instances of a particular component on a page, it is often necessary to
+filter based on some property of the component to determine the correct one to instantiate a harness
+for (e.g. a button with some specific text, a menu with a specific ID, etc). The `HarnessPredicate`
+class can be used to attach certain criteria like this to a `ComponentHarness` subclass. While the
+test author is able to construct `HarnessPredicate` instances manually, its much nicer if the
+`ComponentHarness` subclass provides a helper method to construct predicates for things that will
+need to be commonly filtered on.
+
+The recommended approach to providing this helper is to create a static `with` method on each
+`ComponentHarness` subclass that returns a `HarnessPredicate` for that class. This allows test
+authors to write easily understandable code, e.g.
+`loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. In addition to the standard
+`selector` and `ancestor` options, the `with` method should add any other options that make sense
+for the particular subclass.
+
+Harnesses that need to add additional options should extend the `BaseHarnessFilters` interface and
+additional optional properties as needed. `HarnessPredicate` provides several convenience methods
+for adding options.
+
+| Method | Description |
+| ------ | ----------- |
+| `static stringMatches(s: string \| Promise<string>, pattern: string \| RegExp): Promise<boolean>` | Compares a string or `Promise` of a string against a `string` or `RegExp` and returns a boolean `Promise` indicating whether it matches. |
+| `addOption<O>(name: string, option: O \| undefined, predicate: (harness: T, option: O) => Promise<boolean>): HarnessPredicate<T>` | Creates a new `HarnessPredicate` that enforces all of the conditions of the current one, plus the new constraint specified by the `predicate` parameter. If the `option` parameter is `undefined` the `predicate` is considered to be always true. |
+| `add(description: string, predicate: (harness: T) => Promise<boolean>): HarnessPredicate<T>` | Creates a new `HarnessPredicate` that enforces all of the conditions of the current one, plus the new constraint specified by the `predicate` parameter. |
+
+For example, when working with a menu it would likely be useful to add a way to filter based on
+trigger text and to filter menu items based on their text: 
+
+```ts
+interface MyMenuHarnessFilters extends BaseHarnessFilters {
+  /** Filters based on the trigger text for the menu. */
+  triggerText?: string | RegExp;
+}
+
+interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
+  /** Filters based on the text of the menu item. */
+  text?: string | RegExp;
+}
+
+class MyMenuHarness extends ComponentHarness {
+  static hostSelector = 'my-menu';
+
+  /** Creates a `HarnessPredicate` used to locatr a particular `MyMenuHarness`. */
+  static with(options: MyMenuHarnessFilters): HarnessPredicate<MyMenuHarness> {
+    return new HarnessPredicate(MyMenuHarness, options)
+        .addOption('trigger text', options.triggerText,
+            (harness, text) => HarnessPredicate.stringMatches(harness.getTriggerText(), text));
+  }
+
+  protected getPopupHarness = this.locatorFor(MyPopupHarness);
+
+  /** Gets the text of the menu trigger. */
+  getTriggerText(): Promise<string> {
+    const popupHarness = await this.getPopupHarness();
+    return popupHarness.getTriggerText();
+  }
+
+  ...
+}
+
+class MyMenuItemHarness extends ComponentHarness {
+  static hostSelector = 'my-menu-item';
+
+  /** Creates a `HarnessPredicate` used to locatr a particular `MyMenuItemHarness`. */
+  static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
+    return new HarnessPredicate(MyMenuItemHarness, options)
+        .addOption('text', options.text,
+            (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text));
+  }
+
+  /** Gets the text of the menu item. */
+  async getText(): Promise<string> {
+    const host = await this.host();
+    return host.text();
+  }
+}
+```
+
+A `HarnessPredicate` can be passed in place of a `ComponentHarness` class to any of the APIs on
+`HarnessLoader`, `LocatorFactory`, or `ComponentHarness`. This allows test authors to easily target
+the particular component instance they're interested in when creating a harness instance. It also
+allows the harness author to leverage the same `HarnessPredicate` to enable more powerful APIs on
+their harness class. For example, consider the `getItems` method on the `MyMenuHarness` shown above.
+This can now easily be expanded to allow users of the harness to search for particular menu items:
+
+```ts
+class MyMenuHarness extends ComponentHarness {
+  static hostSelector = 'my-menu';
+
+  /** Gets a list of items in the menu, optionally filtered based on the given criteria. */
+  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
+    const getFilteredItems = this.locatorFor(MyMenuItemHarness.with(filters));
+    return getFilteredItems();
+  }
+
+  ...
+}
+```
+
+#### Creating a `HarnessLoader` for an element
+
+Some components use `<ng-content>` allow the user of the component to pass in whatever content they
+like, and have that content inserted in a particular place in the component's template. When
+creating a harness for a component like this, it is nice to be able to give the harness user a
+`HarnessLoader` instance scoped to the element containing the `<ng-content>`. This allows the user
+of the harness to load additional harnesses for whatever components were passed in as content.
+`ComponentHarness` has several APIs that can be used to create `HarnessLoader` instances for cases
+like this.
+
+| Method | Description |
+| ------ | ----------- |
+| `harnessLoaderFor(selector: string): Promise<HarnessLoader>` | Gets a `Promise` for a `HarnessLoader` rooted at the first element matching the given selector, if no element is found the `Promise` rejects. |
+| `harnessLoaderForOptional(selector: string): Promise<HarnessLoader \| null>` | Gets a `Promise` for a `HarnessLoader` rooted at the first element matching the given selector, if no element is found the `Promise` resolves to `null`. |
+| `harnessLoaderForAll(selector: string): Promise<HarnessLoader[]>` | Gets a `Promise` for a list of `HarnessLoader`, one rooted at each element matching the given selector. |
+
+The `MyPopup` component discussed earlier is a good example of a component with arbitrary content
+that users may want to load harnesses for. `MyPopupHarness` could add support for this:
+
+```ts
+class MyPopupHarness extends ComponentHarness {
+  static hostSelector = 'my-popup';
+
+  /** Gets a `HarnessLoader` whose root element is the popup's content element. */
+  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
+    return this.harnessLoaderFor('my-popup-content');
+  }
+}
+```
+
+#### Accessing elements outside of the component's host element
+
+There are times when a component harness might need to access elements outside of it's corresponding
+component's host element. A good example of this is components that use the
+[CDK overlay](https://material.angular.io/cdk/overlay/overview). The CDK overlay creates an element
+that is attached directly to the body, outside of the component's host element. In this case,
+`ComponentHarness` provides a method that can be used to get a `LocatorFactory` for the root element
+of the document. The `LocatorFactory` supports most of the same APIs as the `ComponentHarness` base
+class, and can then be used to query relative to the document's root element.
+
+| Method | Description |
+| ------ | ----------- |
+| `documentRootLocatorFactory(): LocatorFactory` | Creates a `LocatorFactory` rooted at the document's root element. |
+
+Consider if the `MyPopup` component above used the CDK overlay for the popup content, rather than an
+element in its own template. In this case, `MyPopupHarness` would have to access the content element
+via `documentRootLocatorFactory()`:
+
+```ts
+class MyPopupHarness extends ComponentHarness {
+  static hostSelector = 'my-popup';
+
+  /** Gets a `HarnessLoader` whose root element is the popup's content element. */
+  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
+    const rootLocator = this.documentRootLocatorFactory();
+    return rootLocator.harnessLoaderFor('my-popup-content');
+  }
+}
+```
+
+#### Waiting for asynchronous tasks
+
+The methods on `TestElement` automatically trigger Angular's change detection and wait for tasks
+inside the `NgZone`, so in most cases no special effort is required for harness authors to wait on
+asynchronous tasks. However, there are some edge cases where this may not be sufficient.
+
+Under some circumstances Angular animations may require a second cycle of change detection and
+subsequent `NgZone` stabilization before animation events are fully flushed. In cases where this is
+needed, the `ComponentHarness` offers a `forceStabilize()` method that can be called to do the
+second round.
+
+Additionally some components may intentionally schedule tasks _outside_ of `NgZone`, this is
+typically accomplished by using `NgZone.runOutsideAngular`. In this case the corresponding harness
+may need to explicitly wait for tasks outside `NgZone`, as this does not happen automatically.
+`ComponentHarness` offers a method called `waitForTasksOutsideAngular` for this purpose.
+
+| Method | Description |
+| ------ | ----------- |
+| `forceStabilize(): Promise<void>` | Explicitly runs a round of change detection in Angular and waits for `NgZone` to stabilize. |
+| `waitForTasksOutsideAngular(): Promise<void>` | Waits for tasks scheduled outside of `NgZone` to complete. |
 
 ### API for harness environment authors
 

From f0ce58c2f0a91e42d1511c77f8014d1a64c987a9 Mon Sep 17 00:00:00 2001
From: Jeremy Elbourn <jelbourn@google.com>
Date: Wed, 23 Oct 2019 19:20:28 -0700
Subject: [PATCH 2/3] proposed edits

---
 src/cdk/testing/testing.md | 101 ++++++++++++++++++-------------------
 1 file changed, 48 insertions(+), 53 deletions(-)

diff --git a/src/cdk/testing/testing.md b/src/cdk/testing/testing.md
index 860b5678d497..67d6fccab9ae 100644
--- a/src/cdk/testing/testing.md
+++ b/src/cdk/testing/testing.md
@@ -176,12 +176,12 @@ common components for a large Angular application.
 
 #### Extending `ComponentHarness`
 
-The abstract `ComponentHarness` class is the base class for all component harnesses. To work with
-the CDK's component harness infrastructure, a class must extend `ComponentHarness` and implement a
-static property `hostSelector`.  The `hostSelector` property is used to identify elements in the DOM
-that match this harness subclass. In most cases the `hostSelector` should be the same as the
-`selector` of the `Component` or `Directive` that the harness corresponds to. For example, consider
-a simple popup component with a helper directive to manage some accessibility attributes:
+The abstract `ComponentHarness` class is the base class for all component harnesses. To create a
+custom component harness, extend `ComponentHarness` and implement the static property
+`hostSelector`. The `hostSelector` property identifies elements in the DOM that match this harness
+subclass. In most cases the `hostSelector` should be the same as the `selector` of the corresponding
+`Component` or `Directive`. For example, consider a simple popup component with a helper directive
+to manage some accessibility attributes:
 
 ```ts
 @Component({
@@ -210,24 +210,23 @@ class MyPopupHarness extends ComponentHarness {
 }
 ```
 
-Other than the `hostSelector` property, there are no other properties or methods that are required
-to implement on a `ComponentHarness` subclass, though it is highly recommended to add a static
-`with` method that can be used to generate `HarnessPredicate` instances. This is discussed in more
-detail in the [`HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) section
-below.
+While `ComponentHarness` subclasses require only the `hostSelector` property, most harnesses should
+also implement a static `with` method to generate `HarnessPredicate` instances. The
+[`HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) section
+below covers this in more detail.
 
 #### Finding elements in the component's DOM
 
-Each instance of the `ComponentHarness` subclass represents a particular instance of the
-corresponding component. The corresponding component instance's host element can be accessed via the
-`host` method on the `ComponentHarness` base class.
+Each instance of a `ComponentHarness` subclass represents a particular instance of the
+corresponding component. You can access the component's host element via the `host` method from
+the `ComponentHarness` base class.
 
-In addition to being able to access the component's host element, `ComponentHarness` has several
-methods that can be used to locate elements under the host element; that is, elements that are part
-of the component's template or content. These methods are `locatorFor`, `locatorForOptional`, and
-`locatorForAll`. One important caveat to understand about these methods is that they do not find
-elements, they _create functions_ that can be used to find elements. This avoids caching references
-to elements that later turn stale (for example when an `ngIf` binding updates).
+`ComponentHarness` additionally offers several methods for locating elements within the component's
+DOM. These methods are `locatorFor`, `locatorForOptional`, and `locatorForAll`. 
+Note, though, that these methods do not directly find elements. Instead, they _create functions_
+that find elements. This approach safeguards against caching references to out-of-date elements. For
+example, when an `ngIf` hides and then shows an element, the result is a new DOM element; using
+functions ensures that tests always reference the current state of the DOM.
 
 | Method | Description |
 | ------ | ----------- |
@@ -253,7 +252,7 @@ class MyPopupHarness extends ComponentHarness {
 
 #### Working with `TestElement` instances
 
-The various methods described above for finding elements all return a `TestElement` class.
+The locator methods described above all return a `TestElement` instance.
 `TestElement` offers a number of methods to interact with the underlying DOM:
 
 | Method | Description |
@@ -273,18 +272,18 @@ The various methods described above for finding elements all return a `TestEleme
 | `matchesSelector(selector: string): Promise<boolean>` | Checks whether the element matches the given CSS selector. |
 
 `TestElement` is an abstraction designed to work across different test environments (Karma,
-Protractor, etc); therefore, it is important that all DOM interaction inside harness classes happens
-via this interface. `ComponentHarness` subclasses must _not_ use other means of accessing DOM
-elements (e.g. `document.querySelector`), otherwise it will not work in all test environments.
+Protractor, etc). When using harnesses, you should perform all DOM interaction via this interface.
+Other means of accessing DOM elements (e.g. `document.querySelector`) will not work in all test
+environments.
 
-As a best practice, it is recommended not to expose `TestElement` instances to users of a harness,
-unless its an element the user has some control over (e.g. the host element). Exposing `TestElement`
-instances for internal elements may lead users to depend on implementation details (e.g. assertions
-against particular attributes or classes in your component's template that may change later).
+As a best practice, you should not `TestElement` instances to users of a harness
+unless its an element the component consumer defines directly (e.g. the host element). Exposing
+`TestElement` instances for internal elements leads users to depend on a component's internal DOM
+structure.
 
-Instead, consider providing more narrow-focused methods for particular actions the user may want to
+Instead, provide more narrow-focused methods for particular actions the end user will
 take or particular state they may want to check. For example, `MyPopupHarness` could provide methods
-like:
+like `toggle` and `isOpen`:
 
 ```ts
 class MyPopupHarness extends ComponentHarness {
@@ -309,10 +308,9 @@ class MyPopupHarness extends ComponentHarness {
 
 #### Loading harnesses for subcomponents
 
-Often times larger components are made up of a composition of smaller components, and it can be
-useful to have this structure reflected in a component's harness as well. Each of the `locatorFor`
-methods on `ComponentHarness` discussed earlier has an alternate signature that can be used for
-locating sub-harnesses rather than elements.
+Larger components often compose smaller components. You can reflect this structure in a
+component's harness as well. Each of the `locatorFor` methods on `ComponentHarness` discussed
+earlier has an alternate signature that can be used for locating sub-harnesses rather than elements.
 
 | Method | Description |
 | ------ | ----------- |
@@ -368,13 +366,12 @@ class MyMenuItemHarness extends ComponentHarness {
 
 #### Filtering harness instances with `HarnessPredicate`
 
-When there are multiple instances of a particular component on a page, it is often necessary to
-filter based on some property of the component to determine the correct one to instantiate a harness
-for (e.g. a button with some specific text, a menu with a specific ID, etc). The `HarnessPredicate`
-class can be used to attach certain criteria like this to a `ComponentHarness` subclass. While the
-test author is able to construct `HarnessPredicate` instances manually, its much nicer if the
-`ComponentHarness` subclass provides a helper method to construct predicates for things that will
-need to be commonly filtered on.
+When a page contains multiple instances of a particular component, you may want to filter based on
+some property of the component to get a particular component instance. For example, you may want
+a button with some specific text, or a menu with a specific ID. The `HarnessPredicate`
+class can capture criteria like this for a `ComponentHarness` subclass. While the
+test author is able to construct `HarnessPredicate` instances manually, its easier when the
+`ComponentHarness` subclass provides a helper method to construct predicates for common filters.
 
 The recommended approach to providing this helper is to create a static `with` method on each
 `ComponentHarness` subclass that returns a `HarnessPredicate` for that class. This allows test
@@ -446,11 +443,11 @@ class MyMenuItemHarness extends ComponentHarness {
 }
 ```
 
-A `HarnessPredicate` can be passed in place of a `ComponentHarness` class to any of the APIs on
+You can pass a `HarnessPredicate` in place of a `ComponentHarness` class to any of the APIs on
 `HarnessLoader`, `LocatorFactory`, or `ComponentHarness`. This allows test authors to easily target
-the particular component instance they're interested in when creating a harness instance. It also
-allows the harness author to leverage the same `HarnessPredicate` to enable more powerful APIs on
-their harness class. For example, consider the `getItems` method on the `MyMenuHarness` shown above.
+a particular component instance when creating a harness instance. It also allows the harness author
+to leverage the same `HarnessPredicate` to enable more powerful APIs on their harness class. For
+example, consider the `getItems` method on the `MyMenuHarness` shown above.
 This can now easily be expanded to allow users of the harness to search for particular menu items:
 
 ```ts
@@ -469,13 +466,11 @@ class MyMenuHarness extends ComponentHarness {
 
 #### Creating a `HarnessLoader` for an element
 
-Some components use `<ng-content>` allow the user of the component to pass in whatever content they
-like, and have that content inserted in a particular place in the component's template. When
-creating a harness for a component like this, it is nice to be able to give the harness user a
-`HarnessLoader` instance scoped to the element containing the `<ng-content>`. This allows the user
-of the harness to load additional harnesses for whatever components were passed in as content.
-`ComponentHarness` has several APIs that can be used to create `HarnessLoader` instances for cases
-like this.
+Some components use `<ng-content>` to project additional content into the component's template. When
+creating a harness for such a component, you can give the harness user a `HarnessLoader` instance
+scoped to the element containing the `<ng-content>`. This allows the user of the harness to load
+additional harnesses for whatever components were passed in as content. `ComponentHarness` has
+several APIs that can be used to create `HarnessLoader` instances for cases like this.
 
 | Method | Description |
 | ------ | ----------- |
@@ -533,7 +528,7 @@ The methods on `TestElement` automatically trigger Angular's change detection an
 inside the `NgZone`, so in most cases no special effort is required for harness authors to wait on
 asynchronous tasks. However, there are some edge cases where this may not be sufficient.
 
-Under some circumstances Angular animations may require a second cycle of change detection and
+Under some circumstances, Angular animations may require a second cycle of change detection and
 subsequent `NgZone` stabilization before animation events are fully flushed. In cases where this is
 needed, the `ComponentHarness` offers a `forceStabilize()` method that can be called to do the
 second round.

From 9f524df7ce882b9db6dffc531601c496b53fd9f8 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Thu, 24 Oct 2019 11:09:17 -0700
Subject: [PATCH 3/3] a few more edits

---
 src/cdk/testing/testing.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/cdk/testing/testing.md b/src/cdk/testing/testing.md
index 67d6fccab9ae..d84d944c3a88 100644
--- a/src/cdk/testing/testing.md
+++ b/src/cdk/testing/testing.md
@@ -180,8 +180,7 @@ The abstract `ComponentHarness` class is the base class for all component harnes
 custom component harness, extend `ComponentHarness` and implement the static property
 `hostSelector`. The `hostSelector` property identifies elements in the DOM that match this harness
 subclass. In most cases the `hostSelector` should be the same as the `selector` of the corresponding
-`Component` or `Directive`. For example, consider a simple popup component with a helper directive
-to manage some accessibility attributes:
+`Component` or `Directive`. For example, consider a simple popup component:
 
 ```ts
 @Component({
@@ -212,8 +211,8 @@ class MyPopupHarness extends ComponentHarness {
 
 While `ComponentHarness` subclasses require only the `hostSelector` property, most harnesses should
 also implement a static `with` method to generate `HarnessPredicate` instances. The
-[`HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) section
-below covers this in more detail.
+[`HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) section below covers this
+in more detail.
 
 #### Finding elements in the component's DOM
 
@@ -252,7 +251,7 @@ class MyPopupHarness extends ComponentHarness {
 
 #### Working with `TestElement` instances
 
-The locator methods described above all return a `TestElement` instance.
+The functions created with the locator methods described above all return `TestElement` instances.
 `TestElement` offers a number of methods to interact with the underlying DOM:
 
 | Method | Description |
@@ -276,7 +275,7 @@ Protractor, etc). When using harnesses, you should perform all DOM interaction v
 Other means of accessing DOM elements (e.g. `document.querySelector`) will not work in all test
 environments.
 
-As a best practice, you should not `TestElement` instances to users of a harness
+As a best practice, you should not expose `TestElement` instances to users of a harness
 unless its an element the component consumer defines directly (e.g. the host element). Exposing
 `TestElement` instances for internal elements leads users to depend on a component's internal DOM
 structure.