address comments

Author: mmalerba

src/cdk/testing/change-detection.ts

@@ -8,50 +8,50 @@
 
 import {BehaviorSubject, Subscription} from 'rxjs';
 
-/** Represents the status of change detection batching. */
-export interface ChangeDetectionBatchingStatus {
-  /** Whether change detection is batching. */
-  isBatching: boolean;
+/** Represents the status of auto change detection. */
+export interface AutoChangeDetectionStatus {
+  /** Whether auto change detection is disabled. */
+  isDisabled: boolean;
   /**
    * An optional callback, if present it indicates that change detection should be run immediately,
-   * while handling the batching status change. The callback should then be called as soon as change
+   * while handling the status change. The callback should then be called as soon as change
    * detection is done.
    */
   onDetectChangesNow?: () => void;
 }
 
-/** Subject used to dispatch and listen for changes to the change detection batching status . */
-const batchChangeDetectionSubject = new BehaviorSubject<ChangeDetectionBatchingStatus>({
-  isBatching: false
+/** Subject used to dispatch and listen for changes to the auto change detection status . */
+const autoChangeDetectionSubject = new BehaviorSubject<AutoChangeDetectionStatus>({
+  isDisabled: false
 });
 
-/** The current subscription to `batchChangeDetectionSubject`. */
-let batchChangeDetectionSubscription: Subscription | null;
+/** The current subscription to `autoChangeDetectionSubject`. */
+let autoChangeDetectionSubscription: Subscription | null;
 
 /**
- * The default handler for change detection batching status changes. This handler will be used if
- * the specific environment does not install its own.
- * @param status The new change detection batching status.
+ * The default handler for auto change detection status changes. This handler will be used if the
+ * specific environment does not install its own.
+ * @param status The new auto change detection status.
  */
-function defaultBatchChangeDetectionHandler(status: ChangeDetectionBatchingStatus) {
+function defaultAutoChangeDetectionHandler(status: AutoChangeDetectionStatus) {
   status.onDetectChangesNow?.();
 }
 
 /**
- * Allows a test `HarnessEnvironment` to install its own handler for change detection batching
- * status changes.
- * @param handler The handler for the change detection batching status.
+ * Allows a test `HarnessEnvironment` to install its own handler for auto change detection status
+ * changes.
+ * @param handler The handler for the auto change detection status.
  */
-export function handleChangeDetectionBatching(
-    handler: (status: ChangeDetectionBatchingStatus) => void) {
-  stopHandlingChangeDetectionBatching();
-  batchChangeDetectionSubscription = batchChangeDetectionSubject.subscribe(handler);
+export function handleAutoChangeDetectionStatus(
+    handler: (status: AutoChangeDetectionStatus) => void) {
+  stopHandlingAutoChangeDetectionStatus();
+  autoChangeDetectionSubscription = autoChangeDetectionSubject.subscribe(handler);
 }
 
-/** Allows a `HarnessEnvironment` to stop handling change detection batching status changes. */
-export function stopHandlingChangeDetectionBatching() {
-  batchChangeDetectionSubscription?.unsubscribe();
-  batchChangeDetectionSubscription = null;
+/** Allows a `HarnessEnvironment` to stop handling auto change detection status changes. */
+export function stopHandlingAutoChangeDetectionStatus() {
+  autoChangeDetectionSubscription?.unsubscribe();
+  autoChangeDetectionSubscription = null;
 }
 
 /**
@@ -63,30 +63,30 @@ export function stopHandlingChangeDetectionBatching() {
  */
 async function batchChangeDetection<T>(fn: () => Promise<T>, triggerBeforeAndAfter: boolean) {
   // If change detection batching is already in progress, just run the function.
-  if (batchChangeDetectionSubject.getValue().isBatching) {
+  if (autoChangeDetectionSubject.getValue().isDisabled) {
     return await fn();
   }
 
   // If nothing is handling change detection batching, install the default handler.
-  if (!batchChangeDetectionSubscription) {
-    batchChangeDetectionSubject.subscribe(defaultBatchChangeDetectionHandler);
+  if (!autoChangeDetectionSubscription) {
+    autoChangeDetectionSubject.subscribe(defaultAutoChangeDetectionHandler);
   }
 
   if (triggerBeforeAndAfter) {
-    await new Promise(resolve => batchChangeDetectionSubject.next({
-      isBatching: true,
+    await new Promise(resolve => autoChangeDetectionSubject.next({
+      isDisabled: true,
       onDetectChangesNow: resolve,
     }));
     const result = await fn();
-    await new Promise(resolve => batchChangeDetectionSubject.next({
-      isBatching: false,
+    await new Promise(resolve => autoChangeDetectionSubject.next({
+      isDisabled: false,
       onDetectChangesNow: resolve,
     }));
     return result;
   } else {
-    batchChangeDetectionSubject.next({isBatching: true});
+    autoChangeDetectionSubject.next({isDisabled: true});
     const result = await fn();
-    batchChangeDetectionSubject.next({isBatching: false});
+    autoChangeDetectionSubject.next({isDisabled: false});
     return result;
   }
 }

src/cdk/testing/component-harness.ts

@@ -501,7 +501,7 @@ export class HarnessPredicate<T extends ComponentHarness> {
    *   and resolves to false otherwise.
    */
   async evaluate(harness: T): Promise<boolean> {
-    const results = await parallel((this._predicates.map(p => p(harness))));
+    const results = await parallel(this._predicates.map(p => p(harness)));
     return results.reduce((combined, current) => combined && current, true);
   }
 

src/cdk/testing/test-harnesses.md

@@ -147,9 +147,9 @@ created manually.
 
 #### Change detection
 By default, test harnesses will run Angular's change detection before reading the state of a DOM
-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 
+element and after interacting with a DOM element. While convenient in most cases, there may be times
+that you need finer-grained control over change detection. For example, you may want to check the
+state of a component while an async operation is pending. In these cases you can use the
 `manualChangeDetection` function to disable automatic handling of change detection for a block of
 code. For example:
 
@@ -177,11 +177,12 @@ therefore, the Angular team recommends using
 to improve the test readability.
 
 Note that `await` statements block the execution of your test until the associated `Promise`
-resolves. There are often times when you want to perform multiple actions simultaneously and wait
-until they're all done rather than blocking. For example, reading multiple properties off a harness.
-In these situations use the `parallel` function to parallelize the operations. The parallel function
-works similarly to `Promise.all`, while also optimizing change detection, so it is not run an
-excessive number of times. For example:
+resolves. Occasionally, you may want to perform multiple actions simultaneously and wait until
+they're all done rather than performing each action sequentially. For example, reading multiple
+properties off a single component. In these situations use the `parallel` function to parallelize
+the operations. The parallel function works similarly to `Promise.all`, while also optimizing change
+detection, so it is not run an excessive number of times. The following code demonstrates how you
+can read multiple properties from a harness with `parallel`:
 
 ```ts
 it('reads properties in parallel', async () => {
@@ -445,7 +446,7 @@ class MyMenuHarness extends ComponentHarness {
   protected getPopupHarness = this.locatorFor(MyPopupHarness);
 
   /** Gets the text of the menu trigger. */
-  getTriggerText(): Promise<string> {
+  async getTriggerText(): Promise<string> {
     const popupHarness = await this.getPopupHarness();
     return popupHarness.getTriggerText();
   }
@@ -653,19 +654,19 @@ 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
+#### Handling auto change detection status
 In order to support the `manualChangeDetection` and `parallel` APIs, your environment should install
-a handler for change detection batching.
+a handler for the auto change detection status.
 
-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:
+When your environment wants to start handling the auto change detection status it can call
+`handleAutoChangeDetectionStatus(handler)`. The handler function will receive a 
+`AutoChangeDetectionStatus` 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.
+* `isDisabled: boolean` - Indicates whether auto change detection is currently disabled. When true,
+  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()`.
+If your environment wants to stop handling auto change detection status it can call
+`stopHandlingAutoChangeDetectionStatus()`.

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

@@ -9,10 +9,10 @@
 import {
   ComponentHarness,
   ComponentHarnessConstructor,
-  handleChangeDetectionBatching,
+  handleAutoChangeDetectionStatus,
   HarnessEnvironment,
   HarnessLoader,
-  stopHandlingChangeDetectionBatching,
+  stopHandlingAutoChangeDetectionStatus,
   TestElement
 } from '@angular/cdk/testing';
 import {ComponentFixture, flush} from '@angular/core/testing';
@@ -44,10 +44,10 @@ const activeFixtures = new Set<ComponentFixture<unknown>>();
  * Installs a handler for change detection batching status changes for a specific fixture.
  * @param fixture The fixture to handle change detection batching for.
  */
-function installChangeDetectionBatchingHandler(fixture: ComponentFixture<unknown>) {
+function installAutoChangeDetectionStatusHandler(fixture: ComponentFixture<unknown>) {
   if (!activeFixtures.size) {
-    handleChangeDetectionBatching(({isBatching, onDetectChangesNow}) => {
-      disableAutoChangeDetection = isBatching;
+    handleAutoChangeDetectionStatus(({isDisabled, onDetectChangesNow}) => {
+      disableAutoChangeDetection = isDisabled;
       if (onDetectChangesNow) {
         Promise.all(Array.from(activeFixtures).map(detectChanges)).then(onDetectChangesNow);
       }
@@ -60,10 +60,10 @@ function installChangeDetectionBatchingHandler(fixture: ComponentFixture<unknown
  * Uninstalls a handler for change detection batching status changes for a specific fixture.
  * @param fixture The fixture to stop handling change detection batching for.
  */
-function uninstallChangeDetectionBatchingHandler(fixture: ComponentFixture<unknown>) {
+function uninstallAutoChangeDetectionStatusHandler(fixture: ComponentFixture<unknown>) {
   activeFixtures.delete(fixture);
   if (!activeFixtures.size) {
-    stopHandlingChangeDetectionBatching();
+    stopHandlingAutoChangeDetectionStatus();
   }
 }
 
@@ -92,9 +92,9 @@ export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
     super(rawRootElement);
     this._options = {...defaultEnvironmentOptions, ...options};
     this._taskState = TaskStateZoneInterceptor.setup();
-    installChangeDetectionBatchingHandler(_fixture);
+    installAutoChangeDetectionStatusHandler(_fixture);
     _fixture.componentRef.onDestroy(() => {
-      uninstallChangeDetectionBatchingHandler(_fixture);
+      uninstallAutoChangeDetectionStatusHandler(_fixture);
       this._destroyed = true;
     });
   }

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

@@ -120,9 +120,8 @@ describe('TestbedHarnessEnvironment', () => {
         const harness =
             await TestbedHarnessEnvironment.harnessForFixture(fixture, MainComponentHarness);
         detectChangesSpy.calls.reset();
-        await manualChangeDetection(async () => {
-          await parallel(Array.from({length: 5}, () => harness.button().then(b => b.click())));
-        });
+        await manualChangeDetection(() => parallel(
+            Array.from({length: 5}, () => harness.button().then(b => b.click()))));
         expect(detectChangesSpy).toHaveBeenCalledTimes(0);
       });
     });

tools/public_api_guard/cdk/testing.d.ts

@@ -6,16 +6,16 @@ export declare type AsyncOptionPredicate<T, O> = (item: T, option: O) => Promise
 
 export declare type AsyncPredicate<T> = (item: T) => Promise<boolean>;
 
+export interface AutoChangeDetectionStatus {
+    isDisabled: boolean;
+    onDetectChangesNow?: () => void;
+}
+
 export interface BaseHarnessFilters {
     ancestor?: string;
     selector?: string;
 }
 
-export interface ChangeDetectionBatchingStatus {
-    isBatching: boolean;
-    onDetectChangesNow?: () => void;
-}
-
 export declare abstract class ComponentHarness {
     protected readonly locatorFactory: LocatorFactory;
     constructor(locatorFactory: LocatorFactory);
@@ -47,7 +47,7 @@ export interface ElementDimensions {
     width: number;
 }
 
-export declare function handleChangeDetectionBatching(handler: (status: ChangeDetectionBatchingStatus) => void): void;
+export declare function handleAutoChangeDetectionStatus(handler: (status: AutoChangeDetectionStatus) => void): void;
 
 export declare abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFactory {
     protected rawRootElement: E;
@@ -126,7 +126,7 @@ export interface ModifierKeys {
 
 export declare function parallel<T>(values: Iterable<T | PromiseLike<T>>): Promise<T[]>;
 
-export declare function stopHandlingChangeDetectionBatching(): void;
+export declare function stopHandlingAutoChangeDetectionStatus(): void;
 
 export interface TestElement {
     blur(): Promise<void>;