feat(cdk-experimental): expose root loader instance in harness environment

Adds a new method that can be used by harness consumers to load a harness
through `HarnessLoader` from the document root. This is helpful for harnesses
which need to match elements outside of testbed fixtures (e.g. snack-bars, overlays etc.).

Needed for angular#16697 and angular#16709.

Author: devversion

src/cdk-experimental/testing/component-harness.ts

@@ -22,6 +22,13 @@ export type AsyncOptionPredicate<T, O> = (item: T, option: O) => Promise<boolean
  * instantiate `ComponentHarness`es.
  */
 export interface HarnessLoader {
+
+  /**
+   * Gets the harness loader at the document root. This can be used if harnesses are
+   * located outside of the current loader (e.g. overlays appended to the document body).
+   */
+  documentRootLoader(): HarnessLoader;
+
   /**
    * Searches for an element with the given selector under the current instances's root element,
    * and returns a `HarnessLoader` rooted at the matching element. If multiple elements match the

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

@@ -48,6 +48,11 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     this.rootElement = this.createTestElement(rawRootElement);
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
+  documentRootLoader(): HarnessLoader {
+    return this.createEnvironment(this.getDocumentRoot());
+  }
+
   // Implemented as part of the `LocatorFactory` interface.
   documentRootLocatorFactory(): LocatorFactory {
     return this.createEnvironment(this.getDocumentRoot());

src/cdk-experimental/testing/tests/harnesses/fake-overlay-harness.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {ComponentHarness} from '@angular/cdk-experimental/testing';
+
+export class FakeOverlayHarness extends ComponentHarness {
+  static readonly hostSelector = '.fake-overlay';
+
+  /** Gets the description of the fake overlay. */
+  async getDescription(): Promise<string> {
+    return (await this.host()).text();
+  }
+}

src/cdk-experimental/testing/tests/protractor.e2e.spec.ts

@@ -1,6 +1,7 @@
 import {HarnessLoader} from '@angular/cdk-experimental/testing';
 import {ProtractorHarnessEnvironment} from '@angular/cdk-experimental/testing/protractor';
 import {browser} from 'protractor';
+import {FakeOverlayHarness} from './harnesses/fake-overlay-harness';
 import {MainComponentHarness} from './harnesses/main-component-harness';
 import {SubComponentHarness} from './harnesses/sub-component-harness';
 
@@ -62,6 +63,13 @@ describe('ProtractorHarnessEnvironment', () => {
       const harnesses = await loader.getAllHarnesses(SubComponentHarness);
       expect(harnesses.length).toBe(2);
     });
+
+    it('should be able to load harness through document root loader', async () => {
+      const documentRootHarnesses = await loader
+        .documentRootLoader().getAllHarnesses(FakeOverlayHarness);
+      expect(documentRootHarnesses.length).toBe(1);
+      expect(await documentRootHarnesses[0].getDescription()).toBe('This is a fake overlay.');
+    });
   });
 
   describe('ComponentHarness', () => {

src/cdk-experimental/testing/tests/test-main-component.ts

@@ -12,6 +12,7 @@ import {
   ChangeDetectorRef,
   Component,
   ElementRef,
+  OnDestroy,
   ViewChild,
   ViewEncapsulation
 } from '@angular/core';
@@ -29,7 +30,7 @@ import {
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 
-export class TestMainComponent {
+export class TestMainComponent implements OnDestroy {
   username: string;
   counter: number;
   asyncCounter: number;
@@ -44,6 +45,8 @@ export class TestMainComponent {
 
   @ViewChild('clickTestElement', {static: false}) clickTestElement: ElementRef<HTMLElement>;
 
+  private _fakeOverlayElement: HTMLElement;
+
   onMouseOver() {
     this._isHovering = true;
   }
@@ -63,6 +66,15 @@ export class TestMainComponent {
       this.asyncCounter = 5;
       this._cdr.markForCheck();
     }, 1000);
+
+    this._fakeOverlayElement = document.createElement('div');
+    this._fakeOverlayElement.classList.add('fake-overlay');
+    this._fakeOverlayElement.innerText = 'This is a fake overlay.';
+    document.body.appendChild(this._fakeOverlayElement);
+  }
+
+  ngOnDestroy() {
+    document.body.removeChild(this._fakeOverlayElement);
   }
 
   click() {

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

@@ -1,6 +1,7 @@
 import {HarnessLoader} from '@angular/cdk-experimental/testing';
 import {TestbedHarnessEnvironment} from '@angular/cdk-experimental/testing/testbed';
 import {ComponentFixture, TestBed} from '@angular/core/testing';
+import {FakeOverlayHarness} from './harnesses/fake-overlay-harness';
 import {MainComponentHarness} from './harnesses/main-component-harness';
 import {SubComponentHarness} from './harnesses/sub-component-harness';
 import {TestComponentsModule} from './test-components-module';
@@ -77,6 +78,15 @@ describe('TestbedHarnessEnvironment', () => {
       const harnesses = await loader.getAllHarnesses(SubComponentHarness);
       expect(harnesses.length).toBe(2);
     });
+
+    it('should be able to load harness through document root loader', async () => {
+      const documentRootHarnesses = await loader
+          .documentRootLoader().getAllHarnesses(FakeOverlayHarness);
+      const fixtureHarnesses = await loader.getAllHarnesses(FakeOverlayHarness);
+      expect(fixtureHarnesses.length).toBe(0);
+      expect(documentRootHarnesses.length).toBe(1);
+      expect(await documentRootHarnesses[0].getDescription()).toBe('This is a fake overlay.');
+    });
   });
 
   describe('ComponentHarness', () => {