Align AssertionResult and matchers type with expect library

Author: dprevost-LMI

docs/Framework.md

@@ -5,18 +5,19 @@ Expect-WebDriverIO is inspired by [`expect`](https://www.npmjs.com/package/expec
 
 ## Compatibility
 
-We can pair `expect-webdriverio` with [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), and [Jasmine](https://jasmine.github.io/).
-  - When `expect` is defined globally, we usually overwrite it with the one from `expect-webdriverio` to have our defined assertions work out of the box.
+We can pair `expect-webdriverio` with [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), and even [Jasmine](https://jasmine.github.io/). 
+
+It is highly recommended to use it with a [WDIO Testrunner](https://webdriver.io/docs/clioptions) which provides additional auto-configuration for a plug-and-play experience.
+
+When used <u>**outside of [WDIO Testrunner](https://webdriver.io/docs/clioptions)**</u>, types need to be added to your [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
 ### Jest
-We can use `expect-webdriverio` with [Jest](https://jestjs.io/) using either [`@jest/globals`](https://www.npmjs.com/package/@jest/globals) (preferred) or [`@types/jest`](https://www.npmjs.com/package/@types/jest) (which has global imports support).
+We can use `expect-webdriverio` with [Jest](https://jestjs.io/) using [`@jest/globals`](https://www.npmjs.com/package/@jest/globals) alone (preferred) and optionally [`@types/jest`](https://www.npmjs.com/package/@types/jest) (which has global ambient support).
   - Note: Jest maintainers do not support [`@types/jest`](https://www.npmjs.com/package/@types/jest). If this library gets out of date or has problems, support might be dropped.
-
-In each case, when used <u>**outside of [WDIO Testrunner](https://webdriver.io/docs/clioptions)**</u>, types need to be added to your [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
   - Note: With Jest, the matchers `toMatchSnapshot` and `toMatchInlineSnapshot` are overloaded. To resolve the types correctly, `expect-webdriverio/jest` must be last.
 
 #### With `@jest/globals`
-When paired with [Jest](https://jestjs.io/) and [`@jest/globals`](https://www.npmjs.com/package/@jest/globals), we should `import` the `expect` function from `expect-webdriverio`.
+When paired only with [`@jest/globals`](https://www.npmjs.com/package/@jest/globals), we should `import` the `expect` function from `expect-webdriverio`.
 
 ```ts
 import { expect } from 'expect-webdriverio'
@@ -40,28 +41,22 @@ Optionally, to avoid needing `import { expect } from 'expect-webdriverio'`, you
   }
 }
 ```   
-##### Augmenting Jest's `expect`
-Multiple attempts were made to augment `@jest/globals` to support `expect-webdriverio` matchers directly on Jest's `expect`. However, no namespace is available to augment it; therefore, only module augmentation can be used. This method does not allow adding matchers with the `extends` keyword; instead, they need to be added directly in the interface of the module declaration augmentation, which would create a lot of code duplication.
+##### Augmenting `@jest/globals` JestMatchers
+Multiple attempts were made to augment `@jest/globals` to support `expect-webdriverio` matchers directly on JestMatchers. However, no namespace is available to augment it; therefore, only module augmentation can be used. This method does not allow adding matchers with the `extends` keyword; instead, they need to be added directly in the interface of the module declaration augmentation, which would create a lot of code duplication.
 
 This [Jest issue](https://github.com/jestjs/jest/issues/12424) seems to target this problem, but it is still in progress.
 
 
 #### With `@types/jest`
-When also paired with [`@types/jest`](https://www.npmjs.com/package/@types/jest), no imports are required. Global types are already defined correctly and you can simply use Jest's `expect` directly.
+When also paired with [`@types/jest`](https://www.npmjs.com/package/@types/jest), no imports are required. Global ambient types are already defined correctly and you can simply use Jest's `expect` directly.
 
-Optional: If you are NOT using WDIO Testrunner, it might be required to correctly register the WDIO matchers on Jest's `expect` as shown below:
+If you are NOT using WDIO Testrunner, it may be required to correctly register the WDIO matchers on Jest's `expect` as shown below:
 ```ts
+import { expect } from "@jest/globals";
 import { matchers } from "expect-webdriverio";
 
-// Import and extend Jest's expect with WebdriverIO matchers
 beforeAll(async () => { 
-  // Convert the Map to a plain object and extend Jest's expect
-  const matchersObject: Record<string, any> = {};
-  matchers.forEach((matcher, name) => {
-    matchersObject[name] = matcher;
-  });
-  
-  expect.extend(matchersObject); 
+  expect.extend(matchers);  
 });
 ```
 
@@ -178,8 +173,8 @@ Expected in `tsconfig.json`:
 }
 ```
 
-#### Asymmetric matcher 
-Asymmetric matchers have limited support. Even though `jasmine.stringContaining` has no error, it is potentially not working even with `@wdio/jasmine-framework`, but the below should work:
+#### Asymmetric matchers 
+Asymmetric matchers have limited support. Even though `jasmine.stringContaining` has no error, it potentially does not work even with `@wdio/jasmine-framework`, but the example below should work:
 
 ```ts
 describe('My tests', async () => {

src/softExpect.ts

@@ -88,7 +88,7 @@ const createSoftMatcher = <T>(
             }
 
             // TODO ddprevost might need to review this await since not all expect requires to be awaited
-            return await ((expectChain as unknown) as Record<string, (...args: unknown[]) => Promise<ExpectWebdriverIO.AssertionResult>>)[matcherName](...args)
+            return await ((expectChain as unknown) as Record<string, (...args: unknown[]) => ExpectWebdriverIO.AsyncAssertionResult>)[matcherName](...args)
 
         } catch (error) {
             // Record the failure

src/utils.ts

@@ -91,7 +91,7 @@ async function executeCommandBe(
     received: WdioElementMaybePromise,
     command: (el: WebdriverIO.Element) => Promise<boolean>,
     options: ExpectWebdriverIO.CommandOptions
-): Promise<ExpectWebdriverIO.AssertionResult> {
+): ExpectWebdriverIO.AsyncAssertionResult {
     const { isNot, expectation, verb = 'be' } = this
 
     let el = await received?.getElement()

types/expect-webdriverio.d.ts

@@ -16,9 +16,19 @@ type ExpectLibAsymmetricMatcher<T> = import('expect').AsymmetricMatcher<T>
 type ExpectLibMatchers<R extends void | Promise<void>, T> = import('expect').Matchers<R, T>
 type ExpectLibExpect = import('expect').Expect
 type ExpectLibInverse<Matchers> = import('expect').Inverse<Matchers>
+type ExpectLibSyncExpectationResult = import('expect').SyncExpectationResult
+type ExpectLibAsyncExpectationResult = import('expect').AsyncExpectationResult
+type ExpectLibExpectationResult = import('expect').ExpectationResult
+type ExpectLibMatcherContext = import('expect').MatcherContext
 
 // TODO dprevost: a suggestion would be to move any code outside of the namespace to separate types.ts file, so that we can import the types.
 
+// Extracted from the expect library, this is the type of the matcher function used in the expect library.
+type RawMatcherFn<Context extends ExpectLibMatcherContext = ExpectLibMatcherContext> = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (this: Context, actual: any, ...expected: Array<any>): ExpectLibExpectationResult;
+}
+
 /**
  * Real Promise and wdio chainable promise types.
  */
@@ -556,21 +566,15 @@ declare namespace ExpectWebdriverIO {
         afterStep(step: PickleStep, scenario: Scenario, result: { passed: boolean, error?: Error }): void
     }
 
-    interface AssertionResult {
-        pass: boolean
-        message(): string
-    }
+    interface AssertionResult extends ExpectLibSyncExpectationResult {}
+    type AsyncAssertionResult = ExpectLibAsyncExpectationResult
 
     /**
-     * Used by the wdio main project to configure the matchers in the runner when using Jasmine.
+     * Used by the wdio main project to configure the matchers in the runner when using Jasmine or Jest.
+     * Equivalent as `MatchersObject` from the expect library.
+     * @see https://github.com/jestjs/jest/blob/fd3d6cf9fe416b549a74b6577e5e1ea1130e3659/packages/expect/src/types.ts#L43C13-L43C27
      */
-    const matchers: Map<
-        string,
-        (
-            actual: unknown,
-            ...expected: unknown[]
-        ) => Promise<AssertionResult>
-    >
+    const matchers: Record<string, RawMatcherFn>
 
     interface AssertionHookParams {
         /**