address feedback

Author: mmalerba

src/cdk/testing/change-detection.ts

@@ -96,7 +96,7 @@ async function batchChangeDetection<T>(fn: () => Promise<T>, triggerBeforeAndAft
  * @param fn The function to disable auto change detection for.
  * @return The result of the given function.
  */
-export async function noAutoChangeDetection<T>(fn: () => Promise<T>) {
+export async function manualChangeDetection<T>(fn: () => Promise<T>) {
   return batchChangeDetection(fn, false);
 }
 

src/cdk/testing/harness-environment.ts

@@ -166,10 +166,6 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     const skipSelectorCheck = (elementQueries.length === 0 && harnessTypes.size === 1) ||
         harnessQueries.length === 0;
 
-    // We want to batch change detection while we're filtering harnesses, because harness predicates
-    // may trigger change detection by reading state from DOM elements. If not batched these change
-    // detections would be triggered once per potential match element which could cause significant
-    // slowdown.
     const perElementMatches = await parallel(rawElements.map(async rawElement => {
       const testElement = this.createTestElement(rawElement);
       const allResultsForElement = await Promise.all(

src/cdk/testing/test-harnesses.md

@@ -150,13 +150,13 @@ By default, test harnesses will run Angular's change detection before reading th
 element and after interacting with a DOM element. While this is convenient in most cases, there may
 be times that you need finer-grained control over change detection. (e.g. to check the state of
 something while an async operation is in progress). In these cases you can use the 
-`noAutoChangeDetection` function to disable automatic handling of change detection for a block of
+`manualChangeDetection` function to disable automatic handling of change detection for a block of
 code. For example:
 
 ```ts
 it('checks state while async action is in progress', async () => {
   const buttonHarness = loader.getHarness(MyButtonHarness);
-  await noAutoChangeDetection(async () => {
+  await manualChangeDetection(async () => {
     await buttonHarness.click();
     fixture.detectChanges();
     // Check expectations while async click operation is in progress.
@@ -652,3 +652,20 @@ The
 and 
 [`ProtractorHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/protractor/protractor-harness-environment.ts#L16)
 implementations in Angular CDK serve as good examples of implementations of this interface.
+
+#### Handling change detection batching
+In order to support the `manualChangeDetection` and `parallel` APIs, your environment should install
+a handler for change detection batching.
+
+When your environment wants to start handling change detection batching it can call
+`handleChangeDetectionBatching(handler)`. The handler function will receive a 
+`ChangeDetectionBatchingStatus` which has two properties:
+ 
+* `isBatching: boolean` - Indicates whether change detection is batching. When change detection is
+  batching, your environment's `forceStabilize` method should act as a no-op. This allows users to
+  trigger change detection manually instead.
+* `onDetectChangesNow?: () => void` - If this optional callback is specified, your environment
+  should trigger change detection immediately and call the callback when change detection finishes.
+
+If your environment wants to stop handling change detection batching it can call
+`stopHandlingChangeDetectionBatching()`.

src/cdk/testing/tests/testbed.spec.ts

@@ -1,6 +1,6 @@
 import {_supportsShadowDom} from '@angular/cdk/platform';
 import {
-  HarnessLoader, noAutoChangeDetection, parallel,
+  HarnessLoader, manualChangeDetection, parallel,
 } from '@angular/cdk/testing';
 import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
 import {waitForAsync, ComponentFixture, fakeAsync, TestBed} from '@angular/core/testing';
@@ -81,12 +81,12 @@ describe('TestbedHarnessEnvironment', () => {
     });
 
     describe('change detection behavior', () => {
-      it('noAutoChangeDetection should prevent auto change detection', async () => {
+      it('manualChangeDetection should prevent auto change detection', async () => {
         const detectChangesSpy = spyOn(fixture, 'detectChanges').and.callThrough();
         const harness =
             await TestbedHarnessEnvironment.harnessForFixture(fixture, MainComponentHarness);
         detectChangesSpy.calls.reset();
-        await noAutoChangeDetection(async () => {
+        await manualChangeDetection(async () => {
           const button = await harness.button();
           await button.text();
           await button.click();
@@ -115,12 +115,12 @@ describe('TestbedHarnessEnvironment', () => {
         expect(detectChangesSpy).toHaveBeenCalledTimes(2);
       });
 
-      it('parallel inside noAutoChangeDetection should not cause change detection', async () => {
+      it('parallel inside manualChangeDetection should not cause change detection', async () => {
         const detectChangesSpy = spyOn(fixture, 'detectChanges').and.callThrough();
         const harness =
             await TestbedHarnessEnvironment.harnessForFixture(fixture, MainComponentHarness);
         detectChangesSpy.calls.reset();
-        await noAutoChangeDetection(async () => {
+        await manualChangeDetection(async () => {
           await parallel(Array.from({length: 5}, () => harness.button().then(b => b.click())));
         });
         expect(detectChangesSpy).toHaveBeenCalledTimes(0);

tools/public_api_guard/cdk/testing.d.ts

@@ -115,15 +115,15 @@ export declare type LocatorFnResult<T extends (HarnessQuery<any> | string)[]> =
     } ? C : T[I] extends string ? TestElement : never;
 }[number];
 
+export declare function manualChangeDetection<T>(fn: () => Promise<T>): Promise<T>;
+
 export interface ModifierKeys {
     alt?: boolean;
     control?: boolean;
     meta?: boolean;
     shift?: boolean;
 }
 
-export declare function noAutoChangeDetection<T>(fn: () => Promise<T>): Promise<T>;
-
 export declare function parallel<T>(values: Iterable<T | PromiseLike<T>>): Promise<T[]>;
 
 export declare function stopHandlingChangeDetectionBatching(): void;