feat(cdk/testing): Allow custom querySelectorAll method

This allows the user to drop in a shadow-piercing version of
`querySelectorAll` to handle components that use
`ViewEncapsulation.ShadowDom`

Author: mmalerba

package.json

@@ -112,6 +112,7 @@
     "husky": "^1.3.1",
     "inquirer": "^6.2.0",
     "jasmine-core": "^3.3.0",
+    "kagekiri": "^1.0.16",
     "karma": "^4.4.1",
     "karma-browserstack-launcher": "^1.3.0",
     "karma-chrome-launcher": "^2.2.0",

rollup-globals.bzl

@@ -69,6 +69,7 @@ ROLLUP_GLOBALS = {
     "@material/top-app-bar": "mdc.topAppBar",
 
     # Third-party libraries.
+    "kagekiri": "kagekiri",
     "moment": "moment",
     "protractor": "protractor",
     "rxjs": "rxjs",

src/cdk/testing/BUILD.bazel

@@ -26,7 +26,15 @@ filegroup(
 
 ng_web_test_suite(
     name = "unit_tests",
-    deps = ["//src/cdk/testing/tests:unit_test_sources"],
+    # We need to load Kagekiri statically since it is not a named AMD module and needs to
+    # be manually configured through "require.js" which is used by "karma_web_test_suite".
+    static_files = [
+        "@npm//kagekiri",
+    ],
+    deps = [
+        ":require-config.js",
+        "//src/cdk/testing/tests:unit_test_sources"
+    ],
 )
 
 e2e_test_suite(

src/cdk/testing/kagekiri.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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
+ */
+
+declare module 'kagekiri' {
+  export function querySelectorAll(selector: string, root: Element);
+}

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

@@ -7,18 +7,30 @@
  */
 
 import {HarnessEnvironment, HarnessLoader, TestElement} from '@angular/cdk/testing';
-import {by, element as protractorElement, ElementFinder} from 'protractor';
+import {
+  by,
+  element as protractorElement,
+  ElementArrayFinder,
+  ElementFinder,
+  Locator
+} from 'protractor';
 import {ProtractorElement} from './protractor-element';
 
+/** The default query function that respects shadow boundaries. */
+const defaultQueryFn = (selector: string, root: ElementFinder) => root.all(by.css(selector));
+
 /** A `HarnessEnvironment` implementation for Protractor. */
 export class ProtractorHarnessEnvironment extends HarnessEnvironment<ElementFinder> {
-  protected constructor(rawRootElement: ElementFinder) {
+  protected constructor(rawRootElement: ElementFinder,
+      private _queryFn: (selector: string, root: ElementFinder) => ElementArrayFinder =
+          defaultQueryFn) {
     super(rawRootElement);
   }
 
   /** Creates a `HarnessLoader` rooted at the document root. */
-  static loader(): HarnessLoader {
-    return new ProtractorHarnessEnvironment(protractorElement(by.css('body')));
+  static loader(queryFn?: (selector: string, root: ElementFinder) => ElementArrayFinder):
+      HarnessLoader {
+    return new ProtractorHarnessEnvironment(protractorElement(by.css('body')), queryFn);
   }
 
   async forceStabilize(): Promise<void> {}
@@ -37,11 +49,11 @@ export class ProtractorHarnessEnvironment extends HarnessEnvironment<ElementFind
   }
 
   protected createEnvironment(element: ElementFinder): HarnessEnvironment<ElementFinder> {
-    return new ProtractorHarnessEnvironment(element);
+    return new ProtractorHarnessEnvironment(element, this._queryFn);
   }
 
   protected async getAllRawElements(selector: string): Promise<ElementFinder[]> {
-    const elementFinderArray = this.rawRootElement.all(by.css(selector));
+    const elementFinderArray = this._queryFn(selector, this.rawRootElement);
     const length = await elementFinderArray.count();
     const elements: ElementFinder[] = [];
     for (let i = 0; i < length; i++) {

src/cdk/testing/require-config.js

@@ -0,0 +1,7 @@
+// Require.js is being used by the karma bazel rules and needs to be configured to properly
+// load AMD modules which are not explicitly named in their output bundle.
+require.config({
+  paths: {
+    'kagekiri': '/base/npm/node_modules/kagekiri/dist/kagekiri.umd.min',
+  }
+});

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

@@ -19,6 +19,8 @@ import {takeWhile} from 'rxjs/operators';
 import {TaskState, TaskStateZoneInterceptor} from './task-state-zone-interceptor';
 import {UnitTestElement} from './unit-test-element';
 
+/** The default query function that respects shadow boundaries. */
+const defaultQueryFn = (selector: string, root: Element) => root.querySelectorAll(selector);
 
 /** A `HarnessEnvironment` implementation for Angular's Testbed. */
 export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
@@ -27,23 +29,26 @@ export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
   /** Observable that emits whenever the test task state changes. */
   private _taskState: Observable<TaskState>;
 
-  protected constructor(rawRootElement: Element, private _fixture: ComponentFixture<unknown>) {
+  protected constructor(rawRootElement: Element, private _fixture: ComponentFixture<unknown>,
+      private _queryFn: (selector: string, root: Element) => ArrayLike<Element> = defaultQueryFn) {
     super(rawRootElement);
     this._taskState = TaskStateZoneInterceptor.setup();
     _fixture.componentRef.onDestroy(() => this._destroyed = true);
   }
 
   /** Creates a `HarnessLoader` rooted at the given fixture's root element. */
-  static loader(fixture: ComponentFixture<unknown>): HarnessLoader {
-    return new TestbedHarnessEnvironment(fixture.nativeElement, fixture);
+  static loader(fixture: ComponentFixture<unknown>,
+      queryFn?: (selector: string, root: Element) => ArrayLike<Element>): HarnessLoader {
+    return new TestbedHarnessEnvironment(fixture.nativeElement, fixture, queryFn);
   }
 
   /**
    * Creates a `HarnessLoader` at the document root. This can be used if harnesses are
    * located outside of a fixture (e.g. overlays appended to the document body).
    */
-  static documentRootLoader(fixture: ComponentFixture<unknown>): HarnessLoader {
-    return new TestbedHarnessEnvironment(document.body, fixture);
+  static documentRootLoader(fixture: ComponentFixture<unknown>,
+      queryFn?: (selector: string, root: Element) => ArrayLike<Element>): HarnessLoader {
+    return new TestbedHarnessEnvironment(document.body, fixture, queryFn);
   }
 
   /**
@@ -53,8 +58,9 @@ export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
    * of the fixture.
    */
   static async harnessForFixture<T extends ComponentHarness>(
-      fixture: ComponentFixture<unknown>, harnessType: ComponentHarnessConstructor<T>): Promise<T> {
-    const environment = new TestbedHarnessEnvironment(fixture.nativeElement, fixture);
+      fixture: ComponentFixture<unknown>, harnessType: ComponentHarnessConstructor<T>,
+      queryFn?: (selector: string, root: Element) => ArrayLike<Element>): Promise<T> {
+    const environment = new TestbedHarnessEnvironment(fixture.nativeElement, fixture, queryFn);
     await environment.forceStabilize();
     return environment.createComponentHarness(harnessType, fixture.nativeElement);
   }
@@ -95,11 +101,11 @@ export class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
   }
 
   protected createEnvironment(element: Element): HarnessEnvironment<Element> {
-    return new TestbedHarnessEnvironment(element, this._fixture);
+    return new TestbedHarnessEnvironment(element, this._fixture, this._queryFn);
   }
 
   protected async getAllRawElements(selector: string): Promise<Element[]> {
     await this.forceStabilize();
-    return Array.from(this.rawRootElement.querySelectorAll(selector));
+    return Array.from(this._queryFn(selector, this.rawRootElement));
   }
 }

src/cdk/testing/tests/BUILD.bazel

@@ -39,6 +39,7 @@ ng_test_library(
         "//src/cdk/testing",
         "//src/cdk/testing/private",
         "//src/cdk/testing/testbed",
+        "@npm//kagekiri",
     ],
 )
 

src/cdk/testing/tests/harnesses/main-component-harness.ts

@@ -81,6 +81,8 @@ export class MainComponentHarness extends ComponentHarness {
       this.locatorForAll(SubComponentHarness, SubComponentSpecialHarness);
   readonly missingElementsAndHarnesses =
       this.locatorFor('.not-found', SubComponentHarness.with({title: /not found/}));
+  readonly shadows = this.locatorForAll('.in-the-shadows');
+  readonly deepShadow = this.locatorFor('.in-the-shadows + test-shadow-boundary > .in-the-shadows');
 
   private _testTools = this.locatorFor(SubComponentHarness);
 

src/cdk/testing/tests/test-components-module.ts

@@ -10,11 +10,12 @@ import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
 import {FormsModule} from '@angular/forms';
 import {TestMainComponent} from './test-main-component';
+import {TestShadowBoundary} from './test-shadow-boundary';
 import {TestSubComponent} from './test-sub-component';
 
 @NgModule({
   imports: [CommonModule, FormsModule],
-  declarations: [TestMainComponent, TestSubComponent],
-  exports: [TestMainComponent, TestSubComponent]
+  declarations: [TestMainComponent, TestSubComponent, TestShadowBoundary],
+  exports: [TestMainComponent, TestSubComponent, TestShadowBoundary]
 })
 export class TestComponentsModule {}

src/cdk/testing/tests/test-main-component.html

@@ -32,4 +32,9 @@ <h1 style="height: 100px; width: 200px;">Main Component</h1>
   </button>
   <span id="task-state-result" #taskStateResult></span>
 </div>
-
+<test-shadow-boundary>
+  <div class="in-the-shadows">Shadow 1</div>
+  <test-shadow-boundary>
+    <div class="in-the-shadows">Shadow 2</div>
+  </test-shadow-boundary>
+</test-shadow-boundary>

src/cdk/testing/tests/test-shadow-boundary.ts

@@ -0,0 +1,10 @@
+import {ChangeDetectionStrategy, Component, ViewEncapsulation} from '@angular/core';
+
+@Component({
+  selector: 'test-shadow-boundary',
+  template: '<ng-content></ng-content>',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  // tslint:disable-next-line:validate-decorators
+  encapsulation: ViewEncapsulation.ShadowDom,
+})
+export class TestShadowBoundary {}

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

@@ -12,6 +12,7 @@ import {MainComponentHarness} from './harnesses/main-component-harness';
 import {SubComponentHarness, SubComponentSpecialHarness} from './harnesses/sub-component-harness';
 import {TestComponentsModule} from './test-components-module';
 import {TestMainComponent} from './test-main-component';
+import {querySelectorAll as piercingQuerySelectorAll} from 'kagekiri';
 
 function activeElementText() {
   return document.activeElement && (document.activeElement as HTMLElement).innerText || '';
@@ -492,6 +493,27 @@ describe('TestbedHarnessEnvironment', () => {
       }
     });
   });
+
+  describe('shadow DOM interaction', () => {
+    it('should not pierce shadow boundary by default', async () => {
+      const harness = await TestbedHarnessEnvironment
+          .harnessForFixture(fixture, MainComponentHarness);
+      expect(await harness.shadows()).toEqual([]);
+    });
+
+    it('should pierce shadow boundary when using piercing query', async () => {
+      const harness = await TestbedHarnessEnvironment
+          .harnessForFixture(fixture, MainComponentHarness, piercingQuerySelectorAll);
+      const shadows = await harness.shadows();
+      expect(await Promise.all(shadows.map(el => el.text()))).toEqual(['Shadow 1', 'Shadow 2']);
+    });
+
+    it('should allow querying across shadow boundary', async () => {
+      const harness = await TestbedHarnessEnvironment
+          .harnessForFixture(fixture, MainComponentHarness, piercingQuerySelectorAll);
+      expect(await (await harness.deepShadow()).text()).toBe('Shadow 2');
+    });
+  });
 });
 
 async function checkIsElement(result: ComponentHarness | TestElement, selector?: string) {

test/karma-system-config.js

@@ -6,6 +6,7 @@ System.config({
     'rxjs': 'node:rxjs',
     'tslib': 'node:tslib/tslib.js',
     'moment': 'node:moment/min/moment-with-locales.min.js',
+    'kagekiri': 'node:kagekiri/dist/kagekiri.umd.min.js',
 
     // MDC Web
     '@material/animation': 'node:@material/animation/dist/mdc.animation.js',

test/karma.conf.js

@@ -45,6 +45,7 @@ module.exports = config => {
         watched: false
       },
       {pattern: 'node_modules/@material/*/dist/*', included: false, watched: false},
+      {pattern: 'node_modules/kagekiri/**', included: false, watched: false},
 
       // Include all Angular dependencies
       {pattern: 'node_modules/@angular/**/*', included: false, watched: false},

yarn.lock

@@ -3526,6 +3526,11 @@ cssesc@^0.1.0:
   resolved "https://registry.yarnpkg.com/cssesc/-/cssesc-0.1.0.tgz#c814903e45623371a0477b40109aaafbeeaddbb4"
   integrity sha1-yBSQPkViM3GgR3tAEJqq++6t27Q=
 
+cssesc@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/cssesc/-/cssesc-3.0.0.tgz#37741919903b868565e1c09ea747445cd18983ee"
+  integrity sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==
+
 csv-streamify@^3.0.4:
   version "3.0.4"
   resolved "https://registry.yarnpkg.com/csv-streamify/-/csv-streamify-3.0.4.tgz#4cb614c57e3f299cca17b63fdcb4ad167777f47a"
@@ -6731,6 +6736,13 @@ jws@^3.0.0, jws@^3.1.4, jws@^3.1.5:
     jwa "^1.1.5"
     safe-buffer "^5.0.1"
 
+kagekiri@^1.0.16:
+  version "1.0.16"
+  resolved "https://registry.yarnpkg.com/kagekiri/-/kagekiri-1.0.16.tgz#b4e0aeb8d57fe2e8d8f84f0d099fe35d21c529ed"
+  integrity sha512-/F1UiJ1CpRIOqJq8o0z9r6By2Rv2B+rC37fFbcYnKTWJ4JDXmDaEMer8NAm3afWwgRrJgkrQldXy3BL1wToMlg==
+  dependencies:
+    postcss-selector-parser nolanlawson/postcss-selector-parser#util-deprecate
+
 karma-browserstack-launcher@^1.3.0:
   version "1.3.0"
   resolved "https://registry.yarnpkg.com/karma-browserstack-launcher/-/karma-browserstack-launcher-1.3.0.tgz#61fe3d36b1cf10681e40f9d874bf37271fb1c674"
@@ -8971,6 +8983,15 @@ postcss-selector-parser@^3.1.0:
     indexes-of "^1.0.1"
     uniq "^1.0.1"
 
+"postcss-selector-parser@github:nolanlawson/postcss-selector-parser#util-deprecate":
+  version "6.0.2"
+  resolved "https://codeload.github.com/nolanlawson/postcss-selector-parser/tar.gz/75e38f7a7db8d58fb033ab7d24414b55d81e5b4f"
+  dependencies:
+    cssesc "^3.0.0"
+    indexes-of "^1.0.1"
+    uniq "^1.0.1"
+    util-deprecate "^1.0.2"
+
 postcss-syntax@^0.36.2:
   version "0.36.2"
   resolved "https://registry.yarnpkg.com/postcss-syntax/-/postcss-syntax-0.36.2.tgz#f08578c7d95834574e5593a82dfbfa8afae3b51c"
@@ -11717,7 +11738,7 @@ useragent@2.3.0:
     lru-cache "4.1.x"
     tmp "0.0.x"
 
-util-deprecate@^1.0.1, util-deprecate@~1.0.1:
+util-deprecate@^1.0.1, util-deprecate@^1.0.2, util-deprecate@~1.0.1:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf"
   integrity sha1-RQ1Nyfpw3nMnYvvS1KKJgUGaDM8=