Review typing, name matchers var more precisely

Author: dprevost-LMI

jasmine-wdio-expect-async.d.ts

@@ -1,5 +1,13 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
+/**
+ * Augment the Jasmine namespace to match the behavior of `@wdio/jasmine-framework`.
+ * Only custom WDIO matchers are available under `expectAsync`, as well as Jasmine's built-in matchers.
+ * `expectAsync` is forced into the `expect` global ambient, making all Jasmine sync-matchers asynchronous.
+ *
+ * When using `@wdio/jasmine-framework`, specify `expect-webdriverio/jasmine-wdio-expect-async` in the tsconfig.json's types.
+ */
+
 declare namespace jasmine {
 
     /**
@@ -9,7 +17,6 @@ declare namespace jasmine {
      * Both T,U must stay named as they are to override the default `AsyncMatchers` type from Jasmine.
      *
      * We force Matchers to return a `Promise<void>` since Jasmine's `expectAsync` expects a promise in all cases (different from Jest)
-     * With Jasmine, only custom matchers are available under `expectAsync`, and not the one from Jest `expect` Library.
      */
 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars -- U is required to properly override Jasmine's AsyncMatchers
@@ -27,7 +34,7 @@ declare namespace ExpectWebdriverIO {
 
     /**
      * Overrides the default WDIO expect specifically for Jasmine, since `expectAsync` is forced into `expect`, making all matchers fully asynchronous. This is not the case under Jest or Mocha.
-     * Using `jasmine.AsyncMatchers` pull on WdioMatchers above but also allow to using Jasmine's built-in matchers and also `withContext` matcher.
+     * Using `jasmine.AsyncMatchers` includes the WdioMatchers from above, but also allows using Jasmine's built-in matchers and the `withContext` matcher.
      */
     interface JasmineExpect extends ExpectWebdriverIO.JasmineAsymmetricMatchers, ExpectLibInverse<ExpectWebdriverIO.JasmineAsymmetricMatchers> {
         /**
@@ -38,8 +45,6 @@ declare namespace ExpectWebdriverIO {
          *  - T: the type of the actual value, e.g. any type, not just WebdriverIO.Browser or WebdriverIO.Element
          *  - R: the type of the return value, e.g. Promise<void> or void
          *
-         * Note: The function must stay here in the namespace to overwrite correctly the expect function from the expect library.
-         *
          * @param actual The value to apply matchers against.
          */
         <T = unknown>(actual: T): {
@@ -48,14 +53,14 @@ declare namespace ExpectWebdriverIO {
     }
 }
 
-// @ts-expect-error: IDE might flags this one but just does be concerned by it. This way the `tsc:root-types` can pass!
+/**
+ * Under `@wdio/jasmine-framework`, the global `expect` is overridden to use Jasmine's `expectAsync`.
+ * It contains custom WebdriverIO matchers as well as Jasmine's built-in async & sync matchers but not the basic Jest's expect library matchers.
+ */
+// @ts-expect-error: IDE might flag this, but ignore it. This way the `tsc:root-types` can pass!
 declare const expect: ExpectWebdriverIO.JasmineExpect
 declare namespace NodeJS {
     interface Global {
-        /**
-         * Under `@wdio/jasmine-framework`, the global `expect` is overridden to use Jasmine's expectAsync.
-         * It contains custom WebdriverIO matchers as well as Jasmine's async & sync matchers but not the basic Jest's expect library matchers.
-         */
         expect: ExpectWebdriverIO.JasmineExpect
     }
 }

jasmine.d.ts

@@ -1,30 +1,20 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
+/**
+ * Augment the Jasmine namespace to include the WDIO custom async matchers only.
+ * When using the vanilla Jasmine Library, use `jasmine.addAsyncMatchers(matchers)` and specify `expect-webdriverio/jasmine` in the tsconfig.json's types.
+ */
+
 declare namespace jasmine {
 
     /**
-     * Async matchers for Jasmine to allow the typing of `expectAsync` with WebDriverIO matchers.
+     * Async matchers for Jasmine to allow the typing of `expectAsync` with WebDriverIO custom matchers.
      * T is the type of the actual value
      * U is the type of the expected value
      * Both T,U must stay named as they are to override the default `AsyncMatchers` type from Jasmine.
      *
-     * We force Matchers to return a `Promise<void>` since Jasmine's `expectAsync` expects a promise in all cases (different from Jest)
-     * With Jasmine, only custom matchers are available under `expectAsync`, and not the one from Jest `expect` Library.
+     * We force Matchers to return a `Promise<void>` since under Jasmine's `expectAsync` everything is a promise.
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.CustomMatchers<Promise<void>, T> {
-
-        /**
-         * snapshot matcher
-         * @param label optional snapshot label
-         */
-        toMatchSnapshot(label?: string): Promise<void>
-
-        /**
-         * inline snapshot matcher
-         * @param snapshot snapshot string (autogenerated if not specified)
-         * @param label optional snapshot label
-         */
-        toMatchInlineSnapshot(snapshot?: string, label?: string): Promise<void>
-    }
+    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.CustomMatchers<Promise<void>, T> {}
 }

jest.d.ts

@@ -1,37 +1,37 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
 /**
- * Augment the Jest namespace to include the matchers from expect-webdriverio.
- * When Jest Library is used, it specifies `expect-webdriverio/jest` for this file in the tsconfig.json's types.
+ * Augment the Jest namespace to include the WebDriverIO custom matchers only.
+ * When Jest Library is used, specify `expect-webdriverio/jest` for this file in the tsconfig.json's types.
  */
 
 declare namespace jest {
 
-    interface Matchers<R extends void | Promise<void>, T> extends ExpectWebdriverIO.Matchers<R, T> {
+    interface Matchers<R extends void | Promise<void>, T> extends ExpectWebdriverIO.CustomMatchers<R, T> {
 
         /**
          * Below are overloaded Jest's matchers not part of `expect` but of `jest-snapshot`.
          * @see https://github.com/jestjs/jest/blob/73dbef5d2d3195a1e55fb254c54cce70d3036252/packages/jest-snapshot/src/types.ts#L37
          *
-         *  Note: We need to define them below so that they are correctly typed overloaded.
+         *  Note: We need to define them below so that they are correctly overloaded.
          *  Else even when extending `WdioJestOverloadedMatchers` we have typing errors.
          */
 
         /**
          * snapshot matcher
          * @param label optional snapshot label
          */
-        toMatchSnapshot(label?: string): T extends WdioPromiseLike ? Promise<void> : void;
+        toMatchSnapshot(label?: string): T extends WdioElementOrPromiseLike ? Promise<void> : R;
 
         /**
          * inline snapshot matcher
          * @param snapshot snapshot string (autogenerated if not specified)
          * @param label optional snapshot label
          */
-        toMatchInlineSnapshot(snapshot?: string, label?: string): T extends WdioPromiseLike ? Promise<void> : void;
+        toMatchInlineSnapshot(snapshot?: string, label?: string): T extends WdioElementOrPromiseLike ? Promise<void> : R;
     }
 
     interface Expect extends ExpectWebdriverIO.Expect {}
 
     interface InverseAsymmetricMatchers extends ExpectWebdriverIO.AsymmetricMatchers {}
-}
+}

src/index.ts

@@ -6,7 +6,14 @@ import { DEFAULT_OPTIONS, defaultOptionsList } from './constants.js'
 import createSoftExpect from './softExpect.js'
 import { SoftAssertService } from './softAssert.js'
 
-export const matchers: WdioMatchersObject = new Map<string, RawMatcherFn>()
+/**
+ * Contains only the custom WDIO matchers to be used with `expect.extend()`.
+ */
+export const wdioCustomMatchers: WdioMatchersObject = new Map<string, RawMatcherFn>()
+
+// @deprecated use `wdioCustomMatchers` instead
+export const matchers = wdioCustomMatchers
+
 const filteredMatchers = {}
 const extend = expectLib.extend
 
@@ -22,7 +29,7 @@ expectLib.extend = (m) => {
         return
     }
 
-    Object.entries(m).forEach(([name, matcher]) => matchers.set(name, matcher))
+    Object.entries(m).forEach(([name, matcher]) => wdioCustomMatchers.set(name, matcher))
     return extend(m)
 }
 

src/softExpect.ts

@@ -1,4 +1,4 @@
-import { expect, matchers } from './index.js'
+import { expect, wdioCustomMatchers } from './index.js'
 import { SoftAssertService } from './softAssert.js'
 
 /**
@@ -24,7 +24,7 @@ const createSoftExpect = <T = unknown>(actual: T): ExpectWebdriverIO.Matchers<Pr
             }
 
             // Handle matchers
-            if (matchers.has(propName)) {
+            if (wdioCustomMatchers.has(propName)) {
                 return createSoftMatcher(actual, propName, softService)
             }
 
@@ -41,7 +41,7 @@ const createSoftNotProxy = <T>(actual: T, softService: SoftAssertService) => {
     return new Proxy({} as ExpectWebdriverIO.Matchers<Promise<void>, T>, {
         get(target, prop) {
             const propName = String(prop)
-            if (matchers.has(propName)) {
+            if (wdioCustomMatchers.has(propName)) {
                 return createSoftMatcher(actual, propName, softService, 'not')
             }
             return undefined
@@ -56,7 +56,7 @@ const createSoftChainProxy = <T>(actual: T, chainType: string, softService: Soft
     return new Proxy({} as ExpectWebdriverIO.Matchers<Promise<void>, T>, {
         get(target, prop) {
             const propName = String(prop)
-            if (matchers.has(propName)) {
+            if (wdioCustomMatchers.has(propName)) {
                 return createSoftMatcher(actual, propName, softService, chainType)
             }
             return undefined

test/index.test.ts

@@ -1,9 +1,10 @@
 import { test, expect } from 'vitest'
-import { setOptions, expect as expectExport, matchers, utils } from '../src/index.js'
+import { setOptions, expect as expectExport, matchers, utils, wdioCustomMatchers } from '../src/index.js'
 
 test('index', () => {
     expect(setOptions.name).toBe('setDefaultOptions')
     expect(expectExport).toBeDefined()
     expect(utils.compareText).toBeDefined()
-    expect(matchers.size).toEqual(42)
+    expect(wdioCustomMatchers.size).toEqual(41)
+    expect(matchers.size).toEqual(41)
 })

test/matchers.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, vi, describe } from 'vitest'
-import { matchers, expect as expectLib } from '../src/index.js'
+import { matchers, wdioCustomMatchers, expect as expectLib } from '../src/index.js'
 import { $ } from '@wdio/globals'
 
 vi.mock('@wdio/globals')
@@ -60,6 +60,7 @@ const ALL_MATCHERS = [
 
 test('matchers', () => {
     expect([...matchers.keys()]).toEqual(ALL_MATCHERS)
+    expect(wdioCustomMatchers.size).toEqual(ALL_MATCHERS.length)
 })
 
 test('allows to add matcher', () => {
@@ -69,6 +70,7 @@ test('allows to add matcher', () => {
     // @ts-expect-error not in types
     expectLib('foo').toBeCustom('foo')
     expect(matchers.keys()).toContain('toBeCustom')
+    expect(wdioCustomMatchers.keys()).toContain('toBeCustom')
 })
 
 test('Generic asymmetric matchers from Expect library should work', () => {

types/expect-webdriverio.d.ts

@@ -397,18 +397,18 @@ interface WdioElementArrayOnlyMatchers<_R, ActualT = unknown> {
  * Therefore, they also need to be redefined in the jest.d.ts file so correctly overload the matchers from the Jest namespace.
  * @see jest.d.ts
  */
-interface WdioJestOverloadedMatchers<_R, ActualT> {
+interface WdioJestOverloadedMatchers<R, ActualT> {
     /**
      * snapshot matcher
      * @param label optional snapshot label
      */
-    toMatchSnapshot(label?: string): ActualT extends WdioElementOrPromiseLike ? Promise<void> : void
+    toMatchSnapshot(label?: string): ActualT extends WdioElementOrPromiseLike ? Promise<void> : R
     /**
      * inline snapshot matcher
      * @param snapshot snapshot string (autogenerated if not specified)
      * @param label optional snapshot label
      */
-    toMatchInlineSnapshot(snapshot?: string, label?: string): ActualT extends WdioElementOrPromiseLike ? Promise<void> : void
+    toMatchInlineSnapshot(snapshot?: string, label?: string): ActualT extends WdioElementOrPromiseLike ? Promise<void> : R
 }
 
 /**