feat(cdk/testing): add optional excludes to TestElement text method (#20145)

* add optional excludes to TestElement text method

* add implementation for UnitTestElement and ProtractorElement

* add test, refactor

* add e2e test

* move shared function to separate file

* rename file, udpate golden

* add jsdoc, export TextOptions interface

* fix jsdoc and import

* export text filtering from cdk/testing

Author: annieyw

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

@@ -6,7 +6,14 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {ElementDimensions, ModifierKeys, TestElement, TestKey} from '@angular/cdk/testing';
+import {
+  _getTextWithExcludedElements,
+  ElementDimensions,
+  ModifierKeys,
+  TestElement,
+  TestKey,
+  TextOptions
+} from '@angular/cdk/testing';
 import {browser, ElementFinder, Key} from 'protractor';
 
 /** Maps the `TestKey` constants to Protractor's `Key` constants. */
@@ -129,7 +136,10 @@ export class ProtractorElement implements TestElement {
     return this.element.sendKeys(...keys);
   }
 
-  async text(): Promise<string> {
+  async text(options?: TextOptions): Promise<string> {
+    if (options?.exclude) {
+      return browser.executeScript(_getTextWithExcludedElements, this.element, options.exclude);
+    }
     return this.element.getText();
   }
 

src/cdk/testing/public-api.ts

@@ -10,3 +10,4 @@ export * from './component-harness';
 export * from './harness-environment';
 export * from './test-element';
 export * from './element-dimensions';
+export * from './text-filtering';

src/cdk/testing/test-element.ts

@@ -101,8 +101,11 @@ export interface TestElement {
    */
   sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
 
-  /** Gets the text from the element. */
-  text(): Promise<string>;
+  /**
+   * Gets the text from the element.
+   * @param options Options that affect what text is included.
+   */
+  text(options?: TextOptions): Promise<string>;
 
   /** Gets the value for the given attribute from the element. */
   getAttribute(name: string): Promise<string | null>;
@@ -128,3 +131,8 @@ export interface TestElement {
   /** Checks whether the element is focused. */
   isFocused(): Promise<boolean>;
 }
+
+export interface TextOptions {
+  /** Optional selector for elements to exclude. */
+  exclude?: string;
+}

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

@@ -7,7 +7,14 @@
  */
 
 import * as keyCodes from '@angular/cdk/keycodes';
-import {ElementDimensions, ModifierKeys, TestElement, TestKey} from '@angular/cdk/testing';
+import {
+  _getTextWithExcludedElements,
+  ElementDimensions,
+  ModifierKeys,
+  TestElement,
+  TestKey,
+  TextOptions
+} from '@angular/cdk/testing';
 import {
   clearElement,
   dispatchMouseEvent,
@@ -126,8 +133,11 @@ export class UnitTestElement implements TestElement {
     await this._stabilize();
   }
 
-  async text(): Promise<string> {
+  async text(options?: TextOptions): Promise<string> {
     await this._stabilize();
+    if (options?.exclude) {
+      return _getTextWithExcludedElements(this.element, options.exclude);
+    }
     return (this.element.textContent || '').trim();
   }
 

src/cdk/testing/tests/cross-environment.spec.ts

@@ -412,6 +412,15 @@ export function crossEnvironmentSpecs(
       expect(await button.matchesSelector('button:disabled')).toBe(false);
     });
 
+
+    it('should get correct text excluding certain selectors', async () => {
+      const results = await harness.subcomponentAndSpecialHarnesses();
+      const subHarnessHost = await results[0].host();
+
+      expect(await subHarnessHost.text({exclude: 'h2'})).toBe('ProtractorTestBedOther');
+      expect(await subHarnessHost.text({exclude: 'li'})).toBe('List of test tools');
+    });
+
     it('should get TestElements and ComponentHarnesses', async () => {
       const results = await harness.subcomponentHarnessesAndElements();
       expect(results.length).toBe(5);

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

@@ -44,6 +44,14 @@ describe('ProtractorHarnessEnvironment', () => {
         const globalEl = await harness.globalEl();
         expect(await globalEl.text()).toBe('I am a sibling!');
       });
+
+      it('should get correct text excluding certain selectors', async () => {
+        const results = await harness.subcomponentAndSpecialHarnesses();
+        const subHarnessHost = await results[0].host();
+
+        expect(await subHarnessHost.text({exclude: 'h2'})).toBe('ProtractorTestBedOther');
+        expect(await subHarnessHost.text({exclude: 'li'})).toBe('List of test tools');
+      });
     });
 
     describe('shadow DOM interaction', () => {

src/cdk/testing/text-filtering.ts

@@ -0,0 +1,22 @@
+/**
+ * @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
+ */
+
+/**
+ * Gets text of element excluding certain selectors within the element.
+ * @param element Element to get text from,
+ * @param excludeSelector Selector identifying which elements to exclude,
+ */
+export function _getTextWithExcludedElements(element: Element, excludeSelector: string) {
+  const clone = element.cloneNode(true) as Element;
+  const exclusions = clone.querySelectorAll(excludeSelector);
+  for (let i = 0; i < exclusions.length; i++) {
+    let child = exclusions[i];
+    child.parentNode?.removeChild(child);
+  }
+  return (clone.textContent || '').trim();
+}

tools/public_api_guard/cdk/testing.d.ts

@@ -1,3 +1,5 @@
+export declare function _getTextWithExcludedElements(element: Element, excludeSelector: string): string;
+
 export declare type AsyncFactoryFn<T> = () => Promise<T>;
 
 export declare type AsyncOptionPredicate<T, O> = (item: T, option: O) => Promise<boolean>;
@@ -131,7 +133,7 @@ export interface TestElement {
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue?(value: string): Promise<void>;
-    text(): Promise<string>;
+    text(options?: TextOptions): Promise<string>;
 }
 
 export declare enum TestKey {
@@ -166,3 +168,7 @@ export declare enum TestKey {
     F12 = 28,
     META = 29
 }
+
+export interface TextOptions {
+    exclude?: string;
+}

tools/public_api_guard/cdk/testing/protractor.d.ts

@@ -17,7 +17,7 @@ export declare class ProtractorElement implements TestElement {
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue(value: string): Promise<void>;
-    text(): Promise<string>;
+    text(options?: TextOptions): Promise<string>;
 }
 
 export declare class ProtractorHarnessEnvironment extends HarnessEnvironment<ElementFinder> {

tools/public_api_guard/cdk/testing/testbed.d.ts

@@ -34,5 +34,5 @@ export declare class UnitTestElement implements TestElement {
     sendKeys(...keys: (string | TestKey)[]): Promise<void>;
     sendKeys(modifiers: ModifierKeys, ...keys: (string | TestKey)[]): Promise<void>;
     setInputValue(value: string): Promise<void>;
-    text(): Promise<string>;
+    text(options?: TextOptions): Promise<string>;
 }