fix(cdk/testing): require at least one argument for locator functions

Successor to #23384. Reworks the typings so that users get a TypeScript error if they don't provide at least one argument to a locator function. This isn't a breaking change, because currently it results in a runtime error.

Author: crisbeto

src/cdk/testing/component-harness.ts

@@ -26,6 +26,9 @@ export type HarnessQuery<T extends ComponentHarness> =
   | ComponentHarnessConstructor<T>
   | HarnessPredicate<T>;
 
+/** Queries that can be passed into a locator function. */
+export type LocatorQueries = [HarnessQuery<any> | string, ...(HarnessQuery<any> | string)[]];
+
 /**
  * The result type obtained when searching using a particular list of queries. This type depends on
  * the particular items being queried.
@@ -138,9 +141,7 @@ export interface LocatorFactory {
    * - `await lf.locatorFor('div', DivHarness)()` gets a `TestElement` instance for `#d1`
    * - `await lf.locatorFor('span')()` throws because the `Promise` rejects.
    */
-  locatorFor<T extends (HarnessQuery<any> | string)[]>(
-    ...queries: T
-  ): AsyncFactoryFn<LocatorFnResult<T>>;
+  locatorFor<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
 
   /**
    * Creates an asynchronous locator function that can be used to find a `ComponentHarness` instance
@@ -163,7 +164,7 @@ export interface LocatorFactory {
    * - `await lf.locatorForOptional('div', DivHarness)()` gets a `TestElement` instance for `#d1`
    * - `await lf.locatorForOptional('span')()` gets `null`.
    */
-  locatorForOptional<T extends (HarnessQuery<any> | string)[]>(
+  locatorForOptional<T extends LocatorQueries>(
     ...queries: T
   ): AsyncFactoryFn<LocatorFnResult<T> | null>;
 
@@ -203,9 +204,7 @@ export interface LocatorFactory {
    *   ]`
    * - `await lf.locatorForAll('span')()` gets `[]`.
    */
-  locatorForAll<T extends (HarnessQuery<any> | string)[]>(
-    ...queries: T
-  ): AsyncFactoryFn<LocatorFnResult<T>[]>;
+  locatorForAll<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
 
   /** @return A `HarnessLoader` rooted at the root element of this `LocatorFactory`. */
   rootHarnessLoader(): Promise<HarnessLoader>;
@@ -290,7 +289,7 @@ export abstract class ComponentHarness {
    * - `await ch.locatorFor('div', DivHarness)()` gets a `TestElement` instance for `#d1`
    * - `await ch.locatorFor('span')()` throws because the `Promise` rejects.
    */
-  protected locatorFor<T extends (HarnessQuery<any> | string)[]>(
+  protected locatorFor<T extends LocatorQueries>(
     ...queries: T
   ): AsyncFactoryFn<LocatorFnResult<T>> {
     return this.locatorFactory.locatorFor(...queries);
@@ -317,7 +316,7 @@ export abstract class ComponentHarness {
    * - `await ch.locatorForOptional('div', DivHarness)()` gets a `TestElement` instance for `#d1`
    * - `await ch.locatorForOptional('span')()` gets `null`.
    */
-  protected locatorForOptional<T extends (HarnessQuery<any> | string)[]>(
+  protected locatorForOptional<T extends LocatorQueries>(
     ...queries: T
   ): AsyncFactoryFn<LocatorFnResult<T> | null> {
     return this.locatorFactory.locatorForOptional(...queries);
@@ -359,7 +358,7 @@ export abstract class ComponentHarness {
    *   ]`
    * - `await ch.locatorForAll('span')()` gets `[]`.
    */
-  protected locatorForAll<T extends (HarnessQuery<any> | string)[]>(
+  protected locatorForAll<T extends LocatorQueries>(
     ...queries: T
   ): AsyncFactoryFn<LocatorFnResult<T>[]> {
     return this.locatorFactory.locatorForAll(...queries);

src/cdk/testing/harness-environment.ts

@@ -16,6 +16,7 @@ import {
   HarnessQuery,
   LocatorFactory,
   LocatorFnResult,
+  LocatorQueries,
 } from './component-harness';
 import {TestElement} from './test-element';
 
@@ -57,9 +58,7 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
   }
 
   // Implemented as part of the `LocatorFactory` interface.
-  locatorFor<T extends (HarnessQuery<any> | string)[]>(
-    ...queries: T
-  ): AsyncFactoryFn<LocatorFnResult<T>> {
+  locatorFor<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>> {
     return () =>
       _assertResultFound(
         this._getAllHarnessesAndTestElements(queries),
@@ -68,16 +67,14 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
   }
 
   // Implemented as part of the `LocatorFactory` interface.
-  locatorForOptional<T extends (HarnessQuery<any> | string)[]>(
+  locatorForOptional<T extends LocatorQueries>(
     ...queries: T
   ): AsyncFactoryFn<LocatorFnResult<T> | null> {
     return async () => (await this._getAllHarnessesAndTestElements(queries))[0] || null;
   }
 
   // Implemented as part of the `LocatorFactory` interface.
-  locatorForAll<T extends (HarnessQuery<any> | string)[]>(
-    ...queries: T
-  ): AsyncFactoryFn<LocatorFnResult<T>[]> {
+  locatorForAll<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]> {
     return () => this._getAllHarnessesAndTestElements(queries);
   }
 

src/material-experimental/mdc-list/testing/list-harness-base.ts

@@ -10,6 +10,7 @@ import {
   ComponentHarness,
   ComponentHarnessConstructor,
   HarnessPredicate,
+  LocatorQueries,
   parallel,
 } from '@angular/cdk/testing';
 import {DividerHarnessFilters, MatDividerHarness} from '@angular/material/divider/testing';
@@ -176,6 +177,6 @@ export abstract class MatListHarnessBase<
     if (filters.divider !== false) {
       query.push(MatDividerHarness.with(filters.divider));
     }
-    return this.locatorForAll(...query)();
+    return this.locatorForAll(...(query as LocatorQueries))();
   }
 }

src/material/list/testing/list-harness-base.ts

@@ -10,6 +10,7 @@ import {
   ComponentHarness,
   ComponentHarnessConstructor,
   HarnessPredicate,
+  LocatorQueries,
   parallel,
 } from '@angular/cdk/testing';
 import {DividerHarnessFilters, MatDividerHarness} from '@angular/material/divider/testing';
@@ -175,6 +176,6 @@ export abstract class MatListHarnessBase<
     if (filters.divider !== false) {
       query.push(MatDividerHarness.with(filters.divider));
     }
-    return this.locatorForAll(...query)();
+    return this.locatorForAll(...(query as LocatorQueries))();
   }
 }

tools/public_api_guard/cdk/testing.md

@@ -33,9 +33,9 @@ export abstract class ComponentHarness {
     host(): Promise<TestElement>;
     // (undocumented)
     protected readonly locatorFactory: LocatorFactory;
-    protected locatorFor<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
-    protected locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
-    protected locatorForOptional<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
+    protected locatorFor<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
+    protected locatorForAll<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
+    protected locatorForOptional<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
     protected waitForTasksOutsideAngular(): Promise<void>;
 }
 
@@ -109,11 +109,11 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
     // (undocumented)
     harnessLoaderForOptional(selector: string): Promise<HarnessLoader | null>;
     // (undocumented)
-    locatorFor<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
+    locatorFor<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
     // (undocumented)
-    locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
+    locatorForAll<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
     // (undocumented)
-    locatorForOptional<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
+    locatorForOptional<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
     // (undocumented)
     protected rawRootElement: E;
     // (undocumented)
@@ -156,9 +156,9 @@ export interface LocatorFactory {
     harnessLoaderFor(selector: string): Promise<HarnessLoader>;
     harnessLoaderForAll(selector: string): Promise<HarnessLoader[]>;
     harnessLoaderForOptional(selector: string): Promise<HarnessLoader | null>;
-    locatorFor<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
-    locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
-    locatorForOptional<T extends (HarnessQuery<any> | string)[]>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
+    locatorFor<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>>;
+    locatorForAll<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T>[]>;
+    locatorForOptional<T extends LocatorQueries>(...queries: T): AsyncFactoryFn<LocatorFnResult<T> | null>;
     rootElement: TestElement;
     rootHarnessLoader(): Promise<HarnessLoader>;
     waitForTasksOutsideAngular(): Promise<void>;
@@ -171,6 +171,9 @@ export type LocatorFnResult<T extends (HarnessQuery<any> | string)[]> = {
     } ? C : T[I] extends string ? TestElement : never;
 }[number];
 
+// @public
+export type LocatorQueries = [HarnessQuery<any> | string, ...(HarnessQuery<any> | string)[]];
+
 // @public
 export function manualChangeDetection<T>(fn: () => Promise<T>): Promise<T>;