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

`countHarnesses`

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

* `getHarnessWithOffset` functions similarly to `getHarness`, but returns
  a harness for the matching component instance with the given offset.
  An example use case is to fetch the third 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

Sneakily manually tested using the MatInput test suite

Author: wildcardalice

src/cdk/testing/component-harness.ts

@@ -106,6 +106,20 @@ 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
+   * with the given offset. If no matching component exists with that offset, an error is thrown.
+   * @param query A query for a harness to create
+   * @param offset 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 with the given offset.
+   */
+  getHarnessWithOffset<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.
@@ -114,6 +128,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.
@@ -425,10 +447,21 @@ export abstract class ContentContainerComponentHarness<S extends string = string
     return (await this.getRootHarnessLoader()).getHarnessOrNull(query);
   }
 
+  async getHarnessWithOffset<T extends ComponentHarness>(
+    query: HarnessQuery<T>,
+    offset: number,
+  ): Promise<T> {
+    return (await this.getRootHarnessLoader()).getHarnessWithOffset(query, offset);
+  }
+
   async getAllHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<T[]> {
     return (await this.getRootHarnessLoader()).getAllHarnesses(query);
   }
 
+  async countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number> {
+    return (await this.getRootHarnessLoader()).countHarnesses(query);
+  }
+
   async hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean> {
     return (await this.getRootHarnessLoader()).hasHarness(query);
   }

src/cdk/testing/harness-environment.ts

@@ -122,11 +122,31 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     return this.locatorForOptional(query)();
   }
 
+  // Implemented as part of the `HarnessLoader` interface.
+  async getHarnessWithOffset<T extends ComponentHarness>(
+    query: HarnessQuery<T>,
+    offset: number,
+  ): Promise<T> {
+    if (offset < 0) {
+      throw Error('Offset must not be negative');
+    }
+    const harnesses = await this.locatorForAll(query)();
+    if (offset >= harnesses.length) {
+      throw Error(`No harness was located at offset ${offset}`);
+    }
+    return harnesses[offset];
+  }
+
   // 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 countHarnesses<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<number> {
+    return (await this.locatorForAll(query)()).length;
+  }
+
   // Implemented as part of the `HarnessLoader` interface.
   async hasHarness<T extends ComponentHarness>(query: HarnessQuery<T>): Promise<boolean> {
     return (await this.locatorForOptional(query)()) !== null;

src/cdk/testing/test-harnesses.md

@@ -134,9 +134,10 @@ 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 |
+| `getHarnessWithOffset<T extends ComponentHarness>(harnessType: ComponentHarnessConstructor<T> \| HarnessPredicate<T>, offset: number): Promise<T>` | Acts like `getHarness`, but returns an instance of the harness corresponding to the element with the given zero-indexed offset |
 | `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  |
 
-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