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

@@ -25,6 +25,9 @@ export type AsyncOptionPredicate<T, O> = (item: T, option: O) => Promise<boolean
 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.
@@ -137,7 +140,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):
+  locatorFor<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T>>;
 
   /**
@@ -161,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)[]>(...queries: T):
+  locatorForOptional<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T> | null>;
 
   /**
@@ -200,7 +203,7 @@ export interface LocatorFactory {
    *   ]`
    * - `await lf.locatorForAll('span')()` gets `[]`.
    */
-  locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T):
+  locatorForAll<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T>[]>;
 
   /** @return A `HarnessLoader` rooted at the root element of this `LocatorFactory`. */
@@ -286,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)[]>(...queries: T):
+  protected locatorFor<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T>> {
     return this.locatorFactory.locatorFor(...queries);
   }
@@ -312,7 +315,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)[]>(...queries: T):
+  protected locatorForOptional<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T> | null> {
     return this.locatorFactory.locatorForOptional(...queries);
   }
@@ -353,7 +356,7 @@ export abstract class ComponentHarness {
    *   ]`
    * - `await ch.locatorForAll('span')()` gets `[]`.
    */
-  protected locatorForAll<T extends (HarnessQuery<any> | string)[]>(...queries: T):
+  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,21 +58,21 @@ export abstract class HarnessEnvironment<E> implements HarnessLoader, LocatorFac
   }
 
   // Implemented as part of the `LocatorFactory` interface.
-  locatorFor<T extends (HarnessQuery<any> | string)[]>(...queries: T):
+  locatorFor<T extends LocatorQueries>(...queries: T):
       AsyncFactoryFn<LocatorFnResult<T>> {
     return () => _assertResultFound(
         this._getAllHarnessesAndTestElements(queries),
         _getDescriptionForLocatorForQueries(queries));
   }
 
   // Implemented as part of the `LocatorFactory` interface.
-  locatorForOptional<T extends (HarnessQuery<any> | string)[]>(...queries: T):
+  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):
+  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';
@@ -154,6 +155,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';
@@ -166,6 +167,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>;