feat(material/testing): Modify HarnessLoader with the addition of

`getHarnessAtIndex` and `countHarnesses`

These two new functions are intended to expand harness testing
functionality by providing built-in functions for commonly used
patterns.

* `getHarnessAtIndex` functions similarly to `getHarness`, but returns
  a harness for the matching component instance with the given index.
  An example use case is to fetch the nth MatOptionHarness on screen.
* `countHarnesses` simply counts the number of matching component
  instances and returns the result.

Documentation is updated to reflect this changes, and adds a missing row
for the `hasHarness` function

Manually tested using the MatInputHarness tests

Author: wildcardalice

src/cdk/testing/component-harness.ts

@@ -130,6 +130,17 @@ export interface HarnessLoader {
    */
   getHarnessAtIndex<T extends ComponentHarness>(query: HarnessQuery<T>, index: number): 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 the instance on the page
+   * at the given index. If no matching component exists at that index, an error is thrown.
+   * @param query A query for a harness to create
+   * @param index The zero-indexed offset of the matching component instance to return
+   * @return An instance of the given harness type.
+   * @throws If a matching component instance can't be found at the given index.
+   */
+  getHarnessAtIndex<T extends ComponentHarness>(query: HarnessQuery<T>, index: number): Promise<T>;
+
   /**
    * 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.
@@ -142,7 +153,7 @@ export interface HarnessLoader {
    * Searches for all instances of the component corresponding to the given harness type under the
    * `HarnessLoader`'s root element, and returns the total count of all matching components.
    * @param query A query for a harness to create
-   * @return An integer indicating the number of instances that were found.
+   * @return The number of instances that were found.
    */
   countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number>;
 
@@ -520,12 +531,10 @@ export abstract class ContentContainerComponentHarness<S extends string = string
   }
 
   /**
-   * Gets the nth matching harness for the given query within the current harness's content,
-   * matching the provided index.
+   * Gets the nth matching harness for the given query within the current harness's content.
    * @param query The harness query to search for.
-   * @param index The zero-indexed offset of the matching component instance to return
-   * @returns The first harness matching the given query.
-   * @throws If no matching harness is found.
+   * @param index The zero-indexed index of the instance to fetch.
+   * @returns The first harness matching the given query, or null if none is found.
    */
   async getHarnessAtIndex<T extends ComponentHarness>(
     query: HarnessQuery<T>,
@@ -554,6 +563,17 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     return (await this.getRootHarnessLoader()).countHarnesses(query);
   }
 
+  /**
+   * Counts the number of matching harnesses for the given query within the current harness's
+   * content.
+   *
+   * @param query The harness query to search for.
+   * @returns The number of matching harnesses for the given query.
+   */
+  async countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number> {
+    return (await this.getRootHarnessLoader()).countHarnesses(query);
+  }
+
   /**
    * Checks whether there is a matching harnesses for the given query within the current harness's
    * content.

src/cdk/testing/harness-environment.ts

@@ -251,8 +251,28 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
    /**
    * Searches for an instance of the component corresponding to the given harness type under the
    * `HarnessEnvironment`'s root element, and returns a `ComponentHarness` for that instance. The 
-   * specified index indicates the offset of the instance to return. If no matching component is 
-   * found at that index, an error is thrown.
+   * index specifies which harness to return. If no matching component is found, or no harness
+   * exists at that index, an error is thrown.
+   * @param query A query for a harness to create
+   * @param index the zero-indexed index of the harness to return
+   * @return An instance of the given harness type (or null if not found).
+   */
+  async getHarnessAtIndex<T extends ComponentHarness>(
+    query: HarnessQuery<T>,
+    index: number,
+  ): Promise<T> {
+    if (index < 0) {
+      throw Error('Index must not be negative');
+    }
+    const harnesses = await this.locatorForAll(query)();
+    if (index >= harnesses.length) {
+      throw Error(`No harness was found at index ${index}`);
+    }
+    return harnesses[index];
+  }
+  /**
+   * Searches for all instances of the component corresponding to the given harness type under the
+   * `HarnessEnvironment`'s root element, and returns a list `ComponentHarness` for each instance.
    * @param query A query for a harness to create
    * @param index The zero-indexed offset of the component to return
    * @return An instance of the given harness type
@@ -277,8 +297,9 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return this.locatorForAll(query)();
   }
 
-   /**
-   * Searches for all instances of the component corresponding to the given harness type under the
+  
+  /**
+   * Searches for instances of the component corresponding to the given harness type under the
    * `HarnessEnvironment`'s root element, and returns the number that were found.
    * @param query A query for a harness to create
    * @return The number of instances that were found.