refactor: move force-stabilize from TestElement to ComponentHa… (#17149)

* refactor: move force-stabilize from TestElement to ComponentHarness

Currently the `forceStabilize` method lives on `TestElement`. This is
not the most ergonomic place, given its intended use. This PR moves it
to the `ComponentHarness` base class so that subclasses can simply call
`await this.forceStabilize()`

* fix api test

Author: mmalerba

src/cdk/testing/component-harness.ts

@@ -142,6 +142,13 @@ export interface LocatorFactory {
    */
   locatorForAll<T extends ComponentHarness>(
       harnessType: ComponentHarnessConstructor<T> | HarnessPredicate<T>): AsyncFactoryFn<T[]>;
+
+  /**
+   * Flushes change detection and async tasks.
+   * In most cases it should not be necessary to call this manually. However, there may be some edge
+   * cases where it is needed to fully flush animation events.
+   */
+  forceStabilize(): Promise<void>;
 }
 
 /**
@@ -245,6 +252,15 @@ export abstract class ComponentHarness {
   protected locatorForAll(arg: any) {
     return this.locatorFactory.locatorForAll(arg);
   }
+
+  /**
+   * Flushes change detection and async tasks.
+   * In most cases it should not be necessary to call this manually. However, there may be some edge
+   * cases where it is needed to fully flush animation events.
+   */
+  protected async forceStabilize() {
+    return this.locatorFactory.forceStabilize();
+  }
 }
 
 /** Constructor for a ComponentHarness subclass. */

src/cdk/testing/harness-environment.ts

@@ -110,6 +110,9 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return new harnessType(this.createEnvironment(element));
   }
 
+  // Part of LocatorFactory interface, subclasses will implement.
+  abstract forceStabilize(): Promise<void>;
+
   /** Gets the root element for the document. */
   protected abstract getDocumentRoot(): E;
 

src/cdk/testing/protractor/protractor-element.ts

@@ -148,6 +148,4 @@ export class ProtractorElement implements TestElement {
                   Element.prototype.msMatchesSelector).call(arguments[0], arguments[1])
           `, this.element, selector);
   }
-
-  async forceStabilize(): Promise<void> {}
 }

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

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {HarnessEnvironment} from '@angular/cdk/testing';
 import {by, element as protractorElement, ElementFinder} from 'protractor';
 import {HarnessLoader} from '../component-harness';
-import {HarnessEnvironment} from '../harness-environment';
 import {TestElement} from '../test-element';
 import {ProtractorElement} from './protractor-element';
 
@@ -23,6 +23,8 @@ export class ProtractorHarnessEnvironment extends HarnessEnvironment<ElementFind
     return new ProtractorHarnessEnvironment(protractorElement(by.css('body')));
   }
 
+  async forceStabilize(): Promise<void> {}
+
   protected getDocumentRoot(): ElementFinder {
     return protractorElement(by.css('body'));
   }

src/cdk/testing/test-element.ts

@@ -104,11 +104,4 @@ export interface TestElement {
 
   /** Checks whether this element matches the given selector. */
   matchesSelector(selector: string): Promise<boolean>;
-
-  /**
-   * Flushes change detection and async tasks.
-   * In most cases it should not be necessary to call this. However, there may be some edge cases
-   * where it is needed to fully flush animation events.
-   */
-  forceStabilize(): Promise<void>;
 }

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

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {HarnessEnvironment} from '@angular/cdk/testing';
 import {ComponentFixture} from '@angular/core/testing';
 import {ComponentHarness, ComponentHarnessConstructor, HarnessLoader} from '../component-harness';
-import {HarnessEnvironment} from '../harness-environment';
 import {TestElement} from '../test-element';
 import {UnitTestElement} from './unit-test-element';
 
@@ -43,33 +43,33 @@ export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
   static async harnessForFixture<T extends ComponentHarness>(
       fixture: ComponentFixture<unknown>, harnessType: ComponentHarnessConstructor<T>): Promise<T> {
     const environment = new TestbedHarnessEnvironment(fixture.nativeElement, fixture);
-    await environment._stabilize();
+    await environment.forceStabilize();
     return environment.createComponentHarness(harnessType, fixture.nativeElement);
   }
 
+  async forceStabilize(): Promise<void> {
+    if (this._destroyed) {
+      throw Error('Harness is attempting to use a fixture that has already been destroyed.');
+    }
+
+    this._fixture.detectChanges();
+    await this._fixture.whenStable();
+  }
+
   protected getDocumentRoot(): Element {
     return document.body;
   }
 
   protected createTestElement(element: Element): TestElement {
-    return new UnitTestElement(element, this._stabilize.bind(this));
+    return new UnitTestElement(element, () => this.forceStabilize());
   }
 
   protected createEnvironment(element: Element): HarnessEnvironment<Element> {
     return new TestbedHarnessEnvironment(element, this._fixture);
   }
 
   protected async getAllRawElements(selector: string): Promise<Element[]> {
-    await this._stabilize();
+    await this.forceStabilize();
     return Array.from(this.rawRootElement.querySelectorAll(selector));
   }
-
-  private async _stabilize(): Promise<void> {
-    if (this._destroyed) {
-      throw Error('Harness is attempting to use a fixture that has already been destroyed.');
-    }
-
-    this._fixture.detectChanges();
-    await this._fixture.whenStable();
-  }
 }

src/cdk/testing/testbed/unit-test-element.ts

@@ -144,8 +144,4 @@ export class UnitTestElement implements TestElement {
     return (elementPrototype['matches'] || elementPrototype['msMatchesSelector'])
         .call(this.element, selector);
   }
-
-  async forceStabilize(): Promise<void> {
-    return this._stabilize();
-  }
 }

tools/public_api_guard/cdk/testing.d.ts

@@ -14,6 +14,7 @@ export declare function clearElement(element: HTMLInputElement | HTMLTextAreaEle
 export declare abstract class ComponentHarness {
     constructor(locatorFactory: LocatorFactory);
     protected documentRootLocatorFactory(): LocatorFactory;
+    protected forceStabilize(): Promise<void>;
     host(): Promise<TestElement>;
     protected locatorFor(selector: string): AsyncFactoryFn<TestElement>;
     protected locatorFor<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> | HarnessPredicate<T>): AsyncFactoryFn<T>;
@@ -54,6 +55,7 @@ export declare abstract class HarnessEnvironment<E> implements HarnessLoader, Lo
     protected abstract createEnvironment(element: E): HarnessEnvironment<E>;
     protected abstract createTestElement(element: E): TestElement;
     documentRootLocatorFactory(): LocatorFactory;
+    abstract forceStabilize(): Promise<void>;
     getAllChildLoaders(selector: string): Promise<HarnessLoader[]>;
     getAllHarnesses<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> | HarnessPredicate<T>): Promise<T[]>;
     protected abstract getAllRawElements(selector: string): Promise<E[]>;
@@ -92,6 +94,7 @@ export declare function isTextInput(element: Element): element is HTMLInputEleme
 export interface LocatorFactory {
     rootElement: TestElement;
     documentRootLocatorFactory(): LocatorFactory;
+    forceStabilize(): Promise<void>;
     locatorFor(selector: string): AsyncFactoryFn<TestElement>;
     locatorFor<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> | HarnessPredicate<T>): AsyncFactoryFn<T>;
     locatorForAll(selector: string): AsyncFactoryFn<TestElement[]>;
@@ -114,7 +117,6 @@ export interface TestElement {
     clear(): Promise<void>;
     click(relativeX?: number, relativeY?: number): Promise<void>;
     focus(): Promise<void>;
-    forceStabilize(): Promise<void>;
     getAttribute(name: string): Promise<string | null>;
     getCssValue(property: string): Promise<string>;
     getDimensions(): Promise<ElementDimensions>;