feat(test-runner): specific playwright types for expect (#10670)

packages/playwright-test/types/testExpect.d.ts

@@ -15,11 +15,20 @@
  */
 
 import type * as expect from 'expect';
+import type { Page, Locator, APIResponse } from 'playwright-core';
 
 export declare type AsymmetricMatcher = Record<string, any>;
 
+type IfAny<T, Y, N> = 0 extends (1 & T) ? Y : N;
+type ExtraMatchers<T, Type, Matchers> = T extends Type ? Matchers : IfAny<T, Matchers, {}>;
+
+type MakeMatchers<T, ReturnValue = T> = PlaywrightTest.Matchers<ReturnValue> &
+  ExtraMatchers<T, Page, PageMatchers> &
+  ExtraMatchers<T, Locator, LocatorMatchers> &
+  ExtraMatchers<T, APIResponse, APIResponseMatchers>
+
 export declare type Expect = {
-  <T = unknown>(actual: T): PlaywrightTest.Matchers<T>;
+  <T = unknown>(actual: T): MakeMatchers<T>;
 
   // Sourced from node_modules/expect/build/types.d.ts
   assertions(arg0: number): void;
@@ -36,6 +45,8 @@ export declare type Expect = {
   stringMatching(expected: string | RegExp): AsymmetricMatcher;
 };
 
+type Awaited<T> = T extends PromiseLike<infer U> ? U : T;
+
 type OverriddenExpectProperties =
   'not' |
   'resolves' |
@@ -51,17 +62,17 @@ declare global {
       /**
        * If you know how to test something, `.not` lets you test its opposite.
        */
-      not: PlaywrightTest.Matchers<R>;
+      not: MakeMatchers<R>;
       /**
        * Use resolves to unwrap the value of a fulfilled promise so any other
        * matcher can be chained. If the promise is rejected the assertion fails.
        */
-      resolves: PlaywrightTest.Matchers<Promise<R>>;
+      resolves: MakeMatchers<Awaited<R>, R>;
       /**
       * Unwraps the reason of a rejected promise so any other matcher can be chained.
       * If the promise is fulfilled the assertion fails.
       */
-      rejects: PlaywrightTest.Matchers<Promise<R>>;
+      rejects: MakeMatchers<Promise<R>>;
       /**
        * Match snapshot
        */
@@ -75,108 +86,113 @@ declare global {
       toMatchSnapshot(name: string | string[], options?: {
         threshold?: number
       }): R;
+    }
+  }
+}
 
+interface LocatorMatchers {
   /**
    * Asserts input is checked (or unchecked if { checked: false } is passed).
    */
-      toBeChecked(options?: { checked?: boolean, timeout?: number }): Promise<R>;
+  toBeChecked(options?: { checked?: boolean, timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts input is disabled.
   */
-      toBeDisabled(options?: { timeout?: number }): Promise<R>;
+  toBeDisabled(options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts input is editable.
   */
-      toBeEditable(options?: { timeout?: number }): Promise<R>;
+  toBeEditable(options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts given DOM node or input has no text content or no input value.
   */
-      toBeEmpty(options?: { timeout?: number }): Promise<R>;
+  toBeEmpty(options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts input is enabled.
   */
-      toBeEnabled(options?: { timeout?: number }): Promise<R>;
+  toBeEnabled(options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts given DOM is a focused (active) in document.
   */
-      toBeFocused(options?: { timeout?: number }): Promise<R>;
+  toBeFocused(options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts given DOM node is hidden or detached from DOM.
   */
-      toBeHidden(options?: { timeout?: number }): Promise<R>;
+  toBeHidden(options?: { timeout?: number }): Promise<Locator>;
-
-      /**
-       * Asserts given APIResponse's status is between 200 and 299.
-       */
-      toBeOK(): Promise<R>;
-
-      /**
-       * Asserts given DOM node visible on the screen.
-       */
-      toBeVisible(options?: { timeout?: number }): Promise<R>;
 
   /**
    * Asserts element's text content matches given pattern or contains given substring.
    */
-      toContainText(expected: string | RegExp | (string|RegExp)[], options?: { timeout?: number, useInnerText?: boolean }): Promise<R>;
+  toContainText(expected: string | RegExp | (string | RegExp)[], options?: { timeout?: number, useInnerText?: boolean }): Promise<Locator>;
 
   /**
    * Asserts element's attributes `name` matches expected value.
    */
-      toHaveAttribute(name: string, expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
+  toHaveAttribute(name: string, expected: string | RegExp, options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts that DOM node has a given CSS class.
   */
-      toHaveClass(className: string | RegExp | (string|RegExp)[], options?: { timeout?: number }): Promise<R>;
+  toHaveClass(className: string | RegExp | (string | RegExp)[], options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts number of DOM nodes matching given locator.
   */
-      toHaveCount(expected: number, options?: { timeout?: number }): Promise<R>;
+  toHaveCount(expected: number, options?: { timeout?: number }): Promise<Locator>;
 
   /**
    * Asserts element's computed CSS property `name` matches expected value.
    */
-      toHaveCSS(name: string, expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
+  toHaveCSS(name: string, expected: string | RegExp, options?: { timeout?: number }): Promise<Locator>;
 
   /**
    * Asserts element's `id` attribute matches expected value.
    */
-      toHaveId(expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
+  toHaveId(expected: string | RegExp, options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts JavaScript object that corresponds to the Node has a property with given value.
   */
-      toHaveJSProperty(name: string, value: any, options?: { timeout?: number }): Promise<R>;
+  toHaveJSProperty(name: string, value: any, options?: { timeout?: number }): Promise<Locator>;
 
   /**
   * Asserts element's text content.
   */
-      toHaveText(expected: string | RegExp | (string|RegExp)[], options?: { timeout?: number, useInnerText?: boolean }): Promise<R>;
+  toHaveText(expected: string | RegExp | (string | RegExp)[], options?: { timeout?: number, useInnerText?: boolean }): Promise<Locator>;
-
-      /**
-       * Asserts page's title.
-       */
-      toHaveTitle(expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
-
-      /**
-       * Asserts page's URL.
-       */
-      toHaveURL(expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
 
   /**
    * Asserts input element's value.
    */
-      toHaveValue(expected: string | RegExp, options?: { timeout?: number }): Promise<R>;
+  toHaveValue(expected: string | RegExp, options?: { timeout?: number }): Promise<Locator>;
+
+  /**
+   * Asserts given DOM node visible on the screen.
+   */
+  toBeVisible(options?: { timeout?: number }): Promise<Locator>;
 }
+interface PageMatchers {
+  /**
+   * Asserts page's title.
+   */
+  toHaveTitle(expected: string | RegExp, options?: { timeout?: number }): Promise<Page>;
+
+  /**
+  * Asserts page's URL.
+  */
+  toHaveURL(expected: string | RegExp, options?: { timeout?: number }): Promise<Page>;
 }
+
+interface APIResponseMatchers {
+  /**
+   * Asserts given APIResponse's status is between 200 and 299.
+   */
+  toBeOK(): Promise<APIResponse>;
 }
 
 export { };

tests/playwright-test/expect.spec.ts

@@ -144,29 +144,29 @@ test('should work with custom PlaywrightTest namespace', async ({ runTSC }) => {
 });
 
 test('should propose only the relevant matchers when custom expect matcher classes were passed', async ({ runTSC }) => {
-  test.fixme();
   const result = await runTSC({
     'a.spec.ts': `
     const { test } = pwt;
     test('custom matchers', async ({ page }) => {
       await test.expect(page).toHaveURL('https://example.com');
-      // @ts-expect-error
       await test.expect(page).toBe(true);
       // @ts-expect-error
       await test.expect(page).toBeEnabled();
 
       await test.expect(page.locator('foo')).toBeEnabled();
-      // @ts-expect-error
       await test.expect(page.locator('foo')).toBe(true);
       // @ts-expect-error
       await test.expect(page.locator('foo')).toHaveURL('https://example.com');
 
       const res = await page.request.get('http://i-do-definitely-not-exist.com');
       await test.expect(res).toBeOK();
-      // @ts-expect-error
       await test.expect(res).toBe(true);
       // @ts-expect-error
       await test.expect(res).toHaveURL('https://example.com');
+
+      await test.expect(res as any).toHaveURL('https://example.com');
+      // @ts-expect-error
+      await test.expect(123).toHaveURL('https://example.com');
     });
     `
   });