address feedback

Author: mmalerba

src/cdk/testing/harness-environment.ts

@@ -126,16 +126,25 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
   }
 
   async batchCD<T>(fn: () => Promise<T>) {
+    // Flipping on the `isCDBatching` flag will turn all calls to `forceStabilize` into no-ops to
+    // prevent triggering redundant change detection. However, we want to make sure we trigger
+    // change detection exactly once before flipping this flag to ensure that any pending changes
+    // are flushed before the harness tries to read state from DOM elements.
     const alreadyBatching = isCDBatching;
     if (!alreadyBatching) {
       await this.forceStabilize();
       isCDBatching = true;
     }
+
     const result = await fn();
+
+    // We also want to run change detection exactly once after the batched operation is complete.
+    // This will ensure that any changes from interacting with DOM elements are properly flushed.
     if (!alreadyBatching) {
       isCDBatching = false;
       await this.forceStabilize();
     }
+
     return result;
   }
 
@@ -185,6 +194,10 @@ 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 this.batchCD(() =>
         Promise.all(rawElements.map(async rawElement => {
           const testElement = this.createTestElement(rawElement);

src/cdk/testing/test-harnesses.md

@@ -157,12 +157,13 @@ Note that `await` statements block the execution of your test until the associat
 resolves. When reading multiple properties of a harness it may not be necessary to block on the
 first before asking for the next, in these cases use `Promise.all` to parallelize.
 
-Another thing to consider when parallelizing multiple operations is the component harnesses
-automatically trigger change detection before reading state from an element and after interacting
-with it. When you're running multiple operations in a `Promise.all`, you don't need change detection
-to be triggered multiple times. In order to optimize performance, both `HarnessLoader` and
-`ComponentHarness` offer a `batchCD` method that can be used to ensure change detection is only
-triggered once before the batch operation, and once after.
+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. If you're performing a large number of operations,
+this may slow down your tests. To avoid running change detection for every operation, you can use
+the `batchCD` method on `ComponentHarness` and `HarnessLoader` to run change detection just once
+before the batch operation and once after. When using `Promise.all` to parallelize operations, you
+almost always want to use `batchCD`, as it doesn't make sense to trigger change detection multiple
+times in parallel.
 
 For example, consider the following example of reading both the `checked` and `indeterminate` state
 off of a checkbox harness: