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

@@ -119,6 +119,17 @@ export interface HarnessLoader {
    */
   getHarnessOrNull<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T | null>;
 
+  /**
+   * 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.
@@ -127,6 +138,14 @@ export interface HarnessLoader {
    */
   getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]>;
 
+  /**
+   * 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.
+   */
+  countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number>;
+
   /**
    * 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.
@@ -500,6 +519,20 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     return (await this.getRootHarnessLoader()).getHarnessOrNull(query);
   }
 
+  /**
+   * Gets a matching harness for the given query and index within the current harness's content.
+   * @param query The harness query to search for.
+   * @param index The zero-indexed offset of the component to find.
+   * @returns The first harness matching the given query.
+   * @throws If no matching harness is found.
+   */
+  async getHarnessAtIndex<T extends ComponentHarness>(
+    query: HarnessQuery<T>,
+    index: number,
+  ): Promise<T> {
+    return (await this.getRootHarnessLoader()).getHarnessAtIndex(query, index);
+  }
+
   /**
    * Gets all matching harnesses for the given query within the current harness's content.
    * @param query The harness query to search for.
@@ -509,12 +542,23 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     return (await this.getRootHarnessLoader()).getAllHarnesses(query);
   }
 
+ /**
+   * Returns 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.
    *
    * @param query The harness query to search for.
-   * @returns Whetehr there is matching harnesses for the given query.
+   * @returns Whether there is matching harnesses for the given query.
    */
   async hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean> {
     return (await this.getRootHarnessLoader()).hasHarness(query);

src/cdk/testing/harness-environment.ts

@@ -248,6 +248,30 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return this.locatorForOptional(query)();
   }
 
+ /**
+   * Searches for an instance of the component corresponding to the given harness type and index 
+   * under the `HarnessEnvironment`'s root element, and returns a `ComponentHarness` for that 
+   * instance. The index specifies the offset of the component to find. If no matching
+   * component is found at that index, an error is thrown.
+   * @param query A query for a harness to create
+   * @param index The zero-indexed offset of the component to find
+   * @return An instance of the given harness type
+   * @throws If a matching component instance can't be found.
+   */
+  async getHarnessAtIndex<T extends ComponentHarness>(
+    query: HarnessQuery<T>,
+    offset: number,
+  ): Promise<T> {
+    if (offset < 0) {
+      throw Error('Index must not be negative');
+    }
+    const harnesses = await this.locatorForAll(query)();
+    if (offset >= harnesses.length) {
+      throw Error(`No harness was located at index ${offset}`);
+    }
+    return harnesses[offset];
+  }
+
   /**
    * 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.
@@ -258,6 +282,16 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return this.locatorForAll(query)();
   }
 
+  /**
+   * Searches for all instance 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.
+   */
+  async countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number> {
+    return (await this.locatorForAll(query)()).length;
+  }
+
   /**
    * Searches for an instance of the component corresponding to the given harness type under the
    * `HarnessEnvironment`'s root element, and returns a boolean indicating if any were found.

src/cdk/testing/test-harnesses.md

@@ -134,9 +134,12 @@ are used to create `ComponentHarness` instances for elements under this root ele
 | `getChildLoader(selector: string): Promise<HarnessLoader>` | Searches for an element matching the given selector below the root element of this `HarnessLoader`, and returns a new `HarnessLoader` rooted at the first matching element |
 | `getAllChildLoaders(selector: string): Promise<HarnessLoader[]>` | Acts like `getChildLoader`, but returns an array of `HarnessLoader` instances, one for each matching element, rather than just the first matching element |
 | `getHarness<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>): Promise<T>` | Searches for an instance of the given `ComponentHarness` class or `HarnessPredicate` below the root element of this `HarnessLoader` and returns an instance of the harness corresponding to the first matching element |
+| `getHarnessAtIndex<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>, index: number): Promise<T>` | Acts like `getHarness`, but returns an instance of the harness corresponding to the matching element with the given index (zero-indexed) |
 | `getAllHarnesses<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>): Promise<T[]>` | Acts like `getHarness`, but returns an array of harness instances, one for each matching element, rather than just the first matching element  |
+| `countHarnesses<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>): Promise<number>` | Counts the number of instances of the given `ComponentHarness` class or `HarnessPredicate` below the root element of this `HarnessLoader`, and returns the result. |
+| `hasHarness<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>): Promise<boolean>` | Returns true if an instance of the given `ComponentHarness` class or `HarnessPredicate` exists below the root element of this `HarnessLoader` |
 
-Calls to `getHarness` and `getAllHarnesses` can either take `ComponentHarness` subclass or a
+Calls to the harness functions can either take `ComponentHarness` subclass or a
 `HarnessPredicate`. `HarnessPredicate` applies additional restrictions to the search (e.g. searching
 for a button that has some particular text, etc). The
 [details of `HarnessPredicate`](#filtering-harness-instances-with-harnesspredicate) are discussed in

src/material/input/testing/input-harness.spec.ts

@@ -18,8 +18,7 @@ describe('MatInputHarness', () => {
   });
 
   it('should load all input harnesses', async () => {
-    const inputs = await loader.getAllHarnesses(MatInputHarness);
-    expect(inputs.length).toBe(7);
+    expect(await loader.countHarnesses(MatInputHarness)).toBe(7);
   });
 
   it('should load input with specific id', async () => {