fix: make $ and $$ selectors generic (#6883)

* fix: make `$` and `$$` selectors generic

This means, much like TS's in built `querySelector` type, you can now do:

```ts
const listItems = page.$$<HTMLLIElement>('ul li');
```

And/or:

```ts
const h2 = page.$<HTMLHeadingElement>('h2');
```

And the return value will be of type `ElementHandle<T>|null`, where `T`
is the type you provided. By default `T` is an `Element`, so you don't
have to provide this if you don't care as a consumer about the exact
type you get back.

* chore: fix test assertions

scripts/test-ts-definition-files.ts

@@ -34,7 +34,7 @@ const EXPECTED_ERRORS = new Map<string, string[]>([
       "bad.js(5,35): error TS2551: Property 'launh' does not exist on type",
       "bad.js(7,29): error TS2551: Property 'devics' does not exist on type",
       'bad.js(11,39): error TS2554: Expected 0 arguments, but got 1.',
-      "bad.js(15,9): error TS2322: Type 'ElementHandle<Element> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
+      "bad.js(15,9): error TS2322: Type 'ElementHandle<HTMLElement> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
     ],
   ],
   [
@@ -43,7 +43,7 @@ const EXPECTED_ERRORS = new Map<string, string[]>([
       "bad.js(5,35): error TS2551: Property 'launh' does not exist on type",
       "bad.js(7,29): error TS2551: Property 'devics' does not exist on type",
       'bad.js(11,39): error TS2554: Expected 0 arguments, but got 1.',
-      "bad.js(15,9): error TS2322: Type 'ElementHandle<Element> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
+      "bad.js(15,9): error TS2322: Type 'ElementHandle<HTMLElement> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
     ],
   ],
   [
@@ -52,7 +52,7 @@ const EXPECTED_ERRORS = new Map<string, string[]>([
       "bad.js(5,35): error TS2551: Property 'launh' does not exist on type",
       "bad.js(7,29): error TS2551: Property 'devics' does not exist on type",
       'bad.js(11,39): error TS2554: Expected 0 arguments, but got 1.',
-      "bad.js(15,9): error TS2322: Type 'ElementHandle<Element> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
+      "bad.js(15,9): error TS2322: Type 'ElementHandle<HTMLElement> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
     ],
   ],
   [
@@ -61,7 +61,7 @@ const EXPECTED_ERRORS = new Map<string, string[]>([
       "bad.js(5,35): error TS2551: Property 'launh' does not exist on type",
       "bad.js(7,29): error TS2551: Property 'devics' does not exist on type",
       'bad.js(11,39): error TS2554: Expected 0 arguments, but got 1.',
-      "bad.js(15,9): error TS2322: Type 'ElementHandle<Element> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
+      "bad.js(15,9): error TS2322: Type 'ElementHandle<HTMLElement> | null' is not assignable to type 'ElementHandle<HTMLElement>'",
     ],
   ],
 ]);

src/common/DOMWorld.ts

@@ -166,9 +166,11 @@ export class DOMWorld {
     );
   }
 
-  async $(selector: string): Promise<ElementHandle | null> {
+  async $<T extends Element = Element>(
+    selector: string
+  ): Promise<ElementHandle<T> | null> {
     const document = await this._document();
-    const value = await document.$(selector);
+    const value = await document.$<T>(selector);
     return value;
   }
 
@@ -216,9 +218,11 @@ export class DOMWorld {
     return value;
   }
 
-  async $$(selector: string): Promise<ElementHandle[]> {
+  async $$<T extends Element = Element>(
+    selector: string
+  ): Promise<Array<ElementHandle<T>>> {
     const document = await this._document();
-    const value = await document.$$(selector);
+    const value = await document.$$<T>(selector);
     return value;
   }
 

src/common/FrameManager.ts

@@ -722,8 +722,10 @@ export class Frame {
    * @returns A promise which resolves to an `ElementHandle` pointing at the
    * element, or `null` if it was not found.
    */
-  async $(selector: string): Promise<ElementHandle | null> {
+  async $<T extends Element = Element>(
-    return this._mainWorld.$(selector);
+    selector: string
+  ): Promise<ElementHandle<T> | null> {
+    return this._mainWorld.$<T>(selector);
   }
 
   /**
@@ -801,8 +803,10 @@ export class Frame {
    * @param selector - a selector to search for
    * @returns An array of element handles pointing to the found frame elements.
    */
-  async $$(selector: string): Promise<ElementHandle[]> {
+  async $$<T extends Element = Element>(
-    return this._mainWorld.$$(selector);
+    selector: string
+  ): Promise<Array<ElementHandle<T>>> {
+    return this._mainWorld.$$<T>(selector);
   }
 
   /**

src/common/JSHandle.ts

@@ -771,7 +771,9 @@ export class ElementHandle<
    * Runs `element.querySelector` within the page. If no element matches the selector,
    * the return value resolves to `null`.
    */
-  async $(selector: string): Promise<ElementHandle | null> {
+  async $<T extends Element = Element>(
+    selector: string
+  ): Promise<ElementHandle<T> | null> {
     const { updatedSelector, queryHandler } = getQueryHandlerAndSelector(
       selector
     );
@@ -782,7 +784,9 @@ export class ElementHandle<
    * Runs `element.querySelectorAll` within the page. If no elements match the selector,
    * the return value resolves to `[]`.
    */
-  async $$(selector: string): Promise<ElementHandle[]> {
+  async $$<T extends Element = Element>(
+    selector: string
+  ): Promise<Array<ElementHandle<T>>> {
     const { updatedSelector, queryHandler } = getQueryHandlerAndSelector(
       selector
     );

src/common/Page.ts

@@ -830,8 +830,10 @@ export class Page extends EventEmitter {
    * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
    * to query page for.
    */
-  async $(selector: string): Promise<ElementHandle | null> {
+  async $<T extends Element = Element>(
-    return this.mainFrame().$(selector);
+    selector: string
+  ): Promise<ElementHandle<T> | null> {
+    return this.mainFrame().$<T>(selector);
   }
 
   /**
@@ -1074,8 +1076,10 @@ export class Page extends EventEmitter {
     return this.mainFrame().$$eval<ReturnType>(selector, pageFunction, ...args);
   }
 
-  async $$(selector: string): Promise<ElementHandle[]> {
+  async $$<T extends Element = Element>(
-    return this.mainFrame().$$(selector);
+    selector: string
+  ): Promise<Array<ElementHandle<T>>> {
+    return this.mainFrame().$$<T>(selector);
   }
 
   async $x(expression: string): Promise<ElementHandle[]> {

test/accessibility.spec.ts

@@ -434,7 +434,7 @@ describeFailsFirefox('Accessibility', function () {
 
         await page.setContent(`<button>My Button</button>`);
 
-        const button = await page.$('button');
+        const button = await page.$<HTMLButtonElement>('button');
         expect(await page.accessibility.snapshot({ root: button })).toEqual({
           role: 'button',
           name: 'My Button',

test/ariaqueryhandler.spec.ts

@@ -571,7 +571,7 @@ describeChromeOnly('AriaQueryHandler', () => {
     });
     it('should find by role "button"', async () => {
       const { page } = getTestState();
-      const found = await page.$$('aria/[role="button"]');
+      const found = await page.$$<HTMLButtonElement>('aria/[role="button"]');
       const ids = await getIds(found);
       expect(ids).toEqual(['node5', 'node6', 'node8', 'node10', 'node21']);
     });