From 64606fa65bd0d307a87d8a64b7db0da90105102c Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Sat, 5 Feb 2022 08:06:34 +0000
Subject: [PATCH] feat(cdk/testing): add methods `getOptionalHarness` and
 `hasHarness` (#24355)

---
 src/cdk/testing/component-harness.ts          | 26 +++++++++++++++++++
 src/cdk/testing/harness-environment.ts        | 10 +++++++
 .../testing/tests/cross-environment.spec.ts   | 18 +++++++++++++
 tools/public_api_guard/cdk/testing.md         | 10 +++++++
 4 files changed, 64 insertions(+)

diff --git a/src/cdk/testing/component-harness.ts b/src/cdk/testing/component-harness.ts
index 81aa3476b521..79bec66ad5ad 100644
--- a/src/cdk/testing/component-harness.ts
+++ b/src/cdk/testing/component-harness.ts
@@ -96,6 +96,16 @@ export interface HarnessLoader {
    */
   getHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T>;
 
+  /**
+   * Searches for an instance of the component corresponding to the given harness type under the
+   * `HarnessLoader`'s root element, and returns a `ComponentHarness` for that instance. If multiple
+   * matching components are found, a harness for the first one is returned. If no matching
+   * component is found, null is returned.
+   * @param query A query for a harness to create
+   * @return An instance of the given harness type (or null if not found).
+   */
+  getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null>;
+
   /**
    * Searches for all instances of the component corresponding to the given harness type under the
    * `HarnessLoader`'s root element, and returns a list `ComponentHarness` for each instance.
@@ -103,6 +113,14 @@ export interface HarnessLoader {
    * @return A list instances of the given harness type.
    */
   getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]>;
+
+  /**
+   * Searches for an instance of the component corresponding to the given harness type under the
+   * `HarnessLoader`'s root element, and returns a boolean indicating if any were found.
+   * @param query A query for a harness to create
+   * @return A boolean indicating if an instance was found.
+   */
+  hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean>;
 }
 
 /**
@@ -403,10 +421,18 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     return (await this.getRootHarnessLoader()).getHarness(query);
   }
 
+  async getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null> {
+    return (await this.getRootHarnessLoader()).getHarnessOrNull(query);
+  }
+
   async getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]> {
     return (await this.getRootHarnessLoader()).getAllHarnesses(query);
   }
 
+  async hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean> {
+    return (await this.getRootHarnessLoader()).hasHarness(query);
+  }
+
   /**
    * Gets the root harness loader from which to start
    * searching for content contained by this harness.
diff --git a/src/cdk/testing/harness-environment.ts b/src/cdk/testing/harness-environment.ts
index cb2ea81521aa..277a842e7f19 100644
--- a/src/cdk/testing/harness-environment.ts
+++ b/src/cdk/testing/harness-environment.ts
@@ -117,11 +117,21 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return this.locatorFor(query)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
+  getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null> {
+    return this.locatorForOptional(query)();
+  }
+
   // Implemented as part of the `HarnessLoader` interface.
   getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]> {
     return this.locatorForAll(query)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
+  async hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean> {
+    return (await this.locatorForOptional(query)()) !== null;
+  }
+
   // Implemented as part of the `HarnessLoader` interface.
   async getChildLoader(selector: string): Promise<HarnessLoader> {
     return this.createEnvironment(
diff --git a/src/cdk/testing/tests/cross-environment.spec.ts b/src/cdk/testing/tests/cross-environment.spec.ts
index e6d6827670ce..553b3b916da7 100644
--- a/src/cdk/testing/tests/cross-environment.spec.ts
+++ b/src/cdk/testing/tests/cross-environment.spec.ts
@@ -89,10 +89,28 @@ export function crossEnvironmentSpecs(
       }
     });
 
+    it('should get first matching component for optional harness', async () => {
+      const harness = await loader.getHarnessOrNull(SubComponentHarness);
+      expect(harness).not.toBeNull();
+      expect(await (await harness!.title()).text()).toBe('List of test tools');
+    });
+
+    it('should get null if no matching component found for optional harness', async () => {
+      const countersLoader = await loader.getChildLoader('.counters');
+      const harness = await countersLoader.getHarnessOrNull(SubComponentHarness);
+      expect(harness).toBeNull();
+    });
+
     it('should get all matching components for all harnesses', async () => {
       const harnesses = await loader.getAllHarnesses(SubComponentHarness);
       expect(harnesses.length).toBe(4);
     });
+
+    it('should check if harness is found', async () => {
+      const countersLoader = await loader.getChildLoader('.counters');
+      expect(await loader.hasHarness(SubComponentHarness)).toBe(true);
+      expect(await countersLoader.hasHarness(SubComponentHarness)).toBe(false);
+    });
   });
 
   describe('ComponentHarness', () => {
diff --git a/tools/public_api_guard/cdk/testing.md b/tools/public_api_guard/cdk/testing.md
index 3d7a0ad36201..a256b1a5cd15 100644
--- a/tools/public_api_guard/cdk/testing.md
+++ b/tools/public_api_guard/cdk/testing.md
@@ -56,7 +56,11 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     getChildLoader(selector: S): Promise<HarnessLoader>;
     // (undocumented)
     getHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T>;
+    // (undocumented)
+    getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null>;
     protected getRootHarnessLoader(): Promise<HarnessLoader>;
+    // (undocumented)
+    hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean>;
 }
 
 // @public
@@ -103,12 +107,16 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     // (undocumented)
     getHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T>;
     // (undocumented)
+    getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null>;
+    // (undocumented)
     harnessLoaderFor(selector: string): Promise<HarnessLoader>;
     // (undocumented)
     harnessLoaderForAll(selector: string): Promise<HarnessLoader[]>;
     // (undocumented)
     harnessLoaderForOptional(selector: string): Promise<HarnessLoader | null>;
     // (undocumented)
+    hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean>;
+    // (undocumented)
     locatorFor<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
     // (undocumented)
     locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
@@ -131,6 +139,8 @@ export interface HarnessLoader {
     getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]>;
     getChildLoader(selector: string): Promise<HarnessLoader>;
     getHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T>;
+    getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null>;
+    hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean>;
 }
 
 // @public