feat(cdk/testing): add methods getOptionalHarness and hasHarness

Author: mmalerba

src/cdk/testing/component-harness.ts

@@ -96,13 +96,31 @@ 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).
+   */
+  getOptionalHarness<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.
    * @param query A query for a harness to create
    * @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 An instance of the given harness type (or null if not 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 getOptionalHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null> {
+    return (await this.getRootHarnessLoader()).getOptionalHarness(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.

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.
+  getOptionalHarness<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(

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.getOptionalHarness(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.getOptionalHarness(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', () => {