expect-webdriverio 5.6.8 → 5.7.0

package/jasmine-wdio-expect-async.d.ts

@@ -1,7 +1,16 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
-declare namespace jasmine {
+/**
+ * Note: Under development, until proven, expect breaking changes!
+ * 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.
+ * TODO move into `@wdio/jasmine-framework` and deprecated it from `expect-webdriverio`.
+ */
 
+declare namespace jasmine {
     /**
      * Async matchers for Jasmine to allow the typing of `expectAsync` with WebDriverIO matchers.
      * T is the type of the actual value
@@ -10,28 +19,47 @@ declare namespace jasmine {
      *
      * We force Matchers to return a `Promise<void>` since Jasmine's `expectAsync` expects a promise in all cases (different from Jest)
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    interface AsyncMatchers<T, U> extends Omit<ExpectWebdriverIO.Matchers<Promise<void>, T>, 'toMatchSnapshot' | 'toMatchInlineSnapshot'> {
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- U is required to properly override Jasmine's AsyncMatchers
+    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.Matchers<Promise<void>, T> {
         /**
-         * snapshot matcher
-         * @param label optional snapshot label
+         * Override to unwrap Promise<T> since `expect` replaces `expectAsync` under @wdio/jasmine-framework.
+         * Without this, toBeResolvedTo expects Expected<Promise<X>> instead of Expected<X>.
          */
-        toMatchSnapshot(label?: string): Promise<void>;
+        toBeResolvedTo(expected: Expected<T extends PromiseLike<infer V> ? V : T>): PromiseLike<void>;
+
         /**
-         * inline snapshot matcher
-         * @param snapshot snapshot string (autogenerated if not specified)
-         * @param label optional snapshot label
+         * Rejection type is unknown since promises can reject with any value.
          */
-        toMatchInlineSnapshot(snapshot?: string, label?: string): Promise<void>;
+        toBeRejectedWith(expected: unknown): PromiseLike<void>;
     }
+
+    // Needed to reference it below for the withContext method
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Matchers<T> {}
 }
 
-/**
- * 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.
- */
 declare namespace ExpectWebdriverIO {
-    interface Expect {
+
+    // Should be the same as https://github.com/webdriverio/webdriverio/blob/ea0e3e00288abced4c739ff9e46c46977b7cdbd2/packages/wdio-jasmine-framework/src/index.ts#L21-L29
+    interface JasmineAsymmetricMatchers extends Pick<ExpectWebdriverIO.AsymmetricMatchers, 'any' | 'anything' | 'arrayContaining' | 'objectContaining' | 'stringContaining' | 'stringMatching'> {}
+
+    // Hack to convert all sync matchers to return Promise<void> since `wdio/jasmine-framework` forces `expect` to be async
+    type JasmineSyncMatchers<T> = {
+        [K in keyof jasmine.Matchers<T>]: K extends 'not'
+            ? JasmineSyncMatchers<T>
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            : jasmine.Matchers<T>[K] extends (...args: any) => any
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ? (...args: any[]) => Promise<void>
+                : jasmine.Matchers<T>[K]
+    }
+
+    /**
+     * 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` 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> {
         /**
          * The `expect` function is used every time you want to test a value.
          * You will rarely call `expect` by itself.
@@ -40,10 +68,22 @@ 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): jasmine.AsyncMatchers<T, void>
+        <T = unknown>(actual: T): {
+            withContext(message: string): jasmine.AsyncMatchers<T, Promise<void>> & JasmineSyncMatchers<T>;
+        } & jasmine.AsyncMatchers<T, Promise<void>> & JasmineSyncMatchers<T>
+    }
+}
+
+/**
+ * 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 {
+        expect: ExpectWebdriverIO.JasmineExpect
     }
 }

package/jasmine.d.ts

@@ -1,27 +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(wdioCustomMatchers)` 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)
+     * 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 Omit<ExpectWebdriverIO.Matchers<Promise<void>, T>, 'toMatchSnapshot' | 'toMatchInlineSnapshot'> {
-        /**
-         * 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.Matchers<Promise<void>, T> {}
+}

package/jest.d.ts

@@ -1,8 +1,8 @@
 /// <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 {
@@ -13,7 +13,7 @@ declare namespace jest {
          * 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.
          */
 
@@ -21,17 +21,17 @@ declare namespace jest {
          * 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 {}
-}
+}

package/lib/index.js

@@ -3,6 +3,7 @@ import * as wdioMatchers from './matchers.js';
 import { DEFAULT_OPTIONS, defaultOptionsList } from './constants.js';
 import createSoftExpect from './softExpect.js';
 import { SoftAssertService } from './softAssert.js';
+export const wdioCustomMatchers = {};
 export const matchers = new Map();
 const filteredMatchers = {};
 const extend = expectLib.extend;
@@ -15,7 +16,10 @@ expectLib.extend = (m) => {
     if (!m || typeof m !== 'object') {
         return;
     }
-    Object.entries(m).forEach(([name, matcher]) => matchers.set(name, matcher));
+    Object.entries(m).forEach(([name, matcher]) => {
+        wdioCustomMatchers[name] = matcher;
+        matchers.set(name, matcher);
+    });
     return extend(m);
 };
 expectLib.extend(filteredMatchers);

package/lib/jasmineUtils.js

@@ -11,11 +11,12 @@ function asymmetricMatch(a, b) {
     if (asymmetricA && asymmetricB) {
         return undefined;
     }
+    const matchersUtil = { equals, contains: equals };
     if (asymmetricA) {
-        return a.asymmetricMatch(b);
+        return a.asymmetricMatch(b, matchersUtil);
     }
     if (asymmetricB) {
-        return b.asymmetricMatch(a);
+        return b.asymmetricMatch(a, matchersUtil);
     }
 }
 function eq(a, b, aStack, bStack, customTesters, hasKey) {

package/lib/matchers/mock/toBeRequestedWith.js

@@ -1,4 +1,4 @@
-import { waitUntil, enhanceError } from '../../utils.js';
+import { waitUntil, enhanceError, isAsymmetricMatcher, getAsymmetricMatcherValue } from '../../utils.js';
 import { equals } from '../../jasmineUtils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 const STR_LIMIT = 80;
@@ -88,15 +88,6 @@ const headersMatcher = (headers, expected) => {
     }
     return equals(headers, expected);
 };
-const isMatcher = (filter) => {
-    const proto = Object.getPrototypeOf(filter);
-    return (typeof filter === 'object' &&
-        filter !== null &&
-        typeof proto === 'object' &&
-        proto &&
-        'asymmetricMatch' in proto &&
-        typeof proto.asymmetricMatch === 'function');
-};
 const minifyRequestMock = (requestMock, requestedWith) => {
     if (requestMock === undefined) {
         return requestMock;
@@ -129,10 +120,10 @@ const requestedWithParamToString = (param, transformFn) => {
     if (typeof param === 'function') {
         param = param.toString();
     }
-    else if (isMatcher(param)) {
-        return (param.constructor.name +
-            ' ' +
-            (JSON.stringify(param.sample) || ''));
+    else if (isAsymmetricMatcher(param)) {
+        const sample = getAsymmetricMatcherValue(param);
+        const sampleString = typeof sample === 'string' ? sample : sample instanceof RegExp ? sample.toString() : JSON.stringify(sample) || sample?.toString();
+        return `${param.constructor.name} ${sampleString || ''}`;
     }
     else if (transformFn && typeof param === 'object' && param !== null) {
         param = transformFn(param);

package/lib/utils.js

@@ -5,19 +5,47 @@ import { wrapExpectedWithArray } from './util/elementsUtil.js';
 import { executeCommand } from './util/executeCommand.js';
 import { enhanceError, enhanceErrorBe, numberError } from './util/formatMessage.js';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const asymmetricMatcher = typeof Symbol === 'function' && Symbol.for
-    ? Symbol.for('jest.asymmetricMatcher')
-    : 0x13_57_a5;
+export function isJasmineStringAsymmetricMatcher(expected) {
+    return isAsymmetricMatcher(expected) && 'expected' in expected;
+}
 export function isAsymmetricMatcher(expected) {
     return (typeof expected === 'object' &&
-        expected &&
-        '$$typeof' in expected &&
+        !!expected &&
         'asymmetricMatch' in expected &&
-        expected.$$typeof === asymmetricMatcher &&
-        Boolean(expected.asymmetricMatch));
+        !!expected.asymmetricMatch);
+}
+export function isStringContainingMatcherLike(expected) {
+    return !!expected && expected.constructor.name === 'StringContaining';
+}
+export function isInversedStringContainingMatcher(expected) {
+    return isStringContainingMatcherLike(expected) && expected.inverse === true;
 }
-function isStringContainingMatcher(expected) {
-    return isAsymmetricMatcher(expected) && ['StringContaining', 'StringNotContaining'].includes(expected.toString());
+export function getStringAsymmetricMatcherValue(expected) {
+    if ('expected' in expected) {
+        return expected.expected;
+    }
+    else if ('regexp' in expected) {
+        return expected.regexp;
+    }
+    else if ('sample' in expected) {
+        return expected.sample;
+    }
+    throw new Error(`Could not extract value from asymmetric matcher: ${expected}. Please report this issue to the expect-webdriverio maintainers.`);
+}
+export function getAsymmetricMatcherValue(expected) {
+    if ('expected' in expected) {
+        return expected.expected;
+    }
+    else if ('expectedObject' in expected) {
+        return expected.expectedObject;
+    }
+    else if ('regexp' in expected) {
+        return expected.regexp;
+    }
+    else if ('sample' in expected) {
+        return expected.sample;
+    }
+    return undefined;
 }
 const waitUntil = async (condition, isNot = false, { wait = DEFAULT_OPTIONS.wait, interval = DEFAULT_OPTIONS.interval } = {}) => {
     if (wait === 0) {
@@ -102,10 +130,11 @@ export const compareText = (actual, expected, { ignoreCase = false, trim = true,
         if (typeof expected === 'string') {
             expected = expected.toLowerCase();
         }
-        else if (isStringContainingMatcher(expected)) {
-            expected = (expected.toString() === 'StringContaining'
-                ? expect.stringContaining(expected.sample?.toString().toLowerCase())
-                : expect.not.stringContaining(expected.sample?.toString().toLowerCase()));
+        else if (isStringContainingMatcherLike(expected)) {
+            const sample = getStringAsymmetricMatcherValue(expected).toString().toLocaleLowerCase();
+            expected = (isInversedStringContainingMatcher(expected)
+                ? expect.not.stringContaining(sample)
+                : expect.stringContaining(sample));
         }
     }
     if (isAsymmetricMatcher(expected)) {
@@ -169,10 +198,11 @@ export const compareTextWithArray = (actual, expectedArray, { ignoreCase = false
             if (typeof item === 'string') {
                 return item.toLowerCase();
             }
-            if (isStringContainingMatcher(item)) {
-                return (item.toString() === 'StringContaining'
-                    ? expect.stringContaining(item.sample?.toString().toLowerCase())
-                    : expect.not.stringContaining(item.sample?.toString().toLowerCase()));
+            if (isStringContainingMatcherLike(item)) {
+                const sample = getStringAsymmetricMatcherValue(item).toString().toLocaleLowerCase();
+                return (isInversedStringContainingMatcher(item)
+                    ? expect.not.stringContaining(sample)
+                    : expect.stringContaining(sample));
             }
             return item;
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expect-webdriverio",
-  "version": "5.6.8",
+  "version": "5.7.0",
   "author": "Mykola Grybyk <mykola.grybyk@gmail.com>",
   "description": "WebdriverIO Assertion Library",
   "license": "MIT",
@@ -71,7 +71,7 @@
     "ts:mocha": "cd test-types/mocha && vitest --typecheck --typecheck.tsconfig ./tsconfig.json --run",
     "checks:all": "npm run build && npm run compile && npm run tsc:root-types && npm run test && npm run ts",
     "watch": "npm run compile -- --watch",
-    "prepare": "husky install",
+    "prepare": "husky",
     "playgrounds:setup": "cd playgrounds && npm run setup",
     "playgrounds:checks:all": "cd playgrounds && npm run checks:all",
     "playgrounds:snapshots:update": "cd playgrounds && npm run snapshots:update"
@@ -83,12 +83,12 @@
     "jest-matcher-utils": "^30.4.1"
   },
   "devDependencies": {
+    "@jest/globals": "^30.4.1",
     "@types/debug": "^4.1.13",
     "@types/jasmine": "^5.1.15",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.12.4",
     "@types/mocha": "^10.0.10",
-    "@jest/globals": "^30.4.1",
+    "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "^4.1.7",
     "@wdio/eslint": "^0.1.3",
     "@wdio/types": "^9.27.2",
@@ -97,7 +97,7 @@
     "npm-run-all2": "^9.0.1",
     "release-it": "^20.2.0",
     "rimraf": "^6.1.3",
-    "shelljs": "^0.10.0",
+    "strip-ansi": "^7.2.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.7",
     "webdriverio": "^9.27.2"

package/types/expect-global.d.ts

@@ -5,11 +5,12 @@
  * Required when used in standalone mode (mocha) or to override the one of Jasmine
  */
 
-//// @ts-expect-error: IDE might flags this one but just does be concerned by it. This way the `tsc:root-types` can pass!
+// @ts-expect-error: IDE might flags this one but just does be concerned by it. This way the `tsc:root-types` can pass!
 declare const expect: ExpectWebdriverIO.Expect
 
 declare namespace NodeJS {
     interface Global {
+        // @ts-expect-error: Both wdio & Jasmine augmentation declare different global expect explaining why TS is complaining here
         expect: ExpectWebdriverIO.Expect
     }
-}
+}

package/types/expect-webdriverio.d.ts

@@ -20,6 +20,7 @@ type ExpectLibSyncExpectationResult = import('expect').SyncExpectationResult
 type ExpectLibAsyncExpectationResult = import('expect').AsyncExpectationResult
 type ExpectLibExpectationResult = import('expect').ExpectationResult
 type ExpectLibMatcherContext = import('expect').MatcherContext
+type MatchersObject = Parameters<typeof import('expect').expect.extend>[0]
 
 // Extracted from the expect library, this is the type of the matcher function used in the expect library.
 type RawMatcherFn<Context extends ExpectLibMatcherContext = ExpectLibMatcherContext> = {
@@ -31,6 +32,7 @@ type RawMatcherFn<Context extends ExpectLibMatcherContext = ExpectLibMatcherCont
  * Real Promise and wdio chainable promise types.
  */
 type WdioPromiseLike<T = unknown> = PromiseLike<T> | ChainablePromiseElement | ChainablePromiseArray
+type WdioElementOrPromiseLike<T = unknown> = WdioPromiseLike<T> | WebdriverIO.Element
 type ElementPromise = Promise<WebdriverIO.Element>
 type ElementArrayPromise = Promise<WebdriverIO.ElementArray>
 
@@ -201,7 +203,7 @@ interface WdioElementOrArrayMatchers<_R, ActualT = unknown> {
         ActualT,
         (
             property: string,
-            value?: string | RegExp | WdioAsymmetricMatcher<string> | null,
+            value?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | null,
             options?: ExpectWebdriverIO.StringOptions,
         ) => Promise<void>
     >
@@ -396,18 +398,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 WdioPromiseLike ? 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 WdioPromiseLike ? Promise<void> : void;
+    toMatchInlineSnapshot(snapshot?: string, label?: string): ActualT extends WdioElementOrPromiseLike ? Promise<void> : R
 }
 
 /**
@@ -466,8 +468,41 @@ type WdioAsymmetricMatchers = ExpectLibAsymmetricMatchers
 type WdioAsymmetricMatcher<R> = ExpectWebdriverIO.PartialMatcher<R> & {
     // Overwrite protected properties of expect.AsymmetricMatcher to access them
     sample: R;
+    inverse?: boolean;
 }
 
+type JasmineBaseAsymmetricMatcher = {
+    jasmineToString(): string;
+    asymmetricMatch(other: unknown): boolean;
+}
+
+/**
+ * Jasmine asymetric matcher does not always use sample, some use expected. `any` uses even `expectedObject`
+ * @see https://github.com/jasmine/jasmine/tree/v5.13.0/src/core/asymmetric_equality
+ */
+type JasmineAsymmetricMatcher<R> = JasmineBaseAsymmetricMatcher & ({
+    expected: R;
+} | {
+    sample: R;
+} | {
+    regexp: string | RegExp;
+} | {
+    expectedObject: R;
+} | {} // jasmine.anything()
+)
+
+type JasmineStringContainingAsymmetricMatcher<R> = JasmineBaseAsymmetricMatcher & {
+    expected: R;
+}
+
+type JasmineStringMatchingAsymmetricMatcher<R extends string | RegExp> = JasmineBaseAsymmetricMatcher & {
+    regexp: R;
+}
+
+type JasmineStringAsymmetricMatcher<R extends string | RegExp> = JasmineStringContainingAsymmetricMatcher<R> | JasmineStringMatchingAsymmetricMatcher<R>
+
+type AsymmetricMatcher<R> = WdioAsymmetricMatcher<R> | JasmineStringContainingAsymmetricMatcher<R> | (R extends string | RegExp ? JasmineStringMatchingAsymmetricMatcher<R> : never) | JasmineAsymmetricMatcher<R>
+
 declare namespace ExpectWebdriverIO {
     /**
      * When importing expect from 'expect-webdriverio', instead of using globals this is the one used.
@@ -510,7 +545,13 @@ declare namespace ExpectWebdriverIO {
         <T = unknown>(actual: T): T extends PromiseLike<unknown> ? ExpectWebdriverIO.MatchersAndInverse<void, T> & ExpectWebdriverIO.PromiseMatchers<T> : ExpectWebdriverIO.MatchersAndInverse<void, T>;
     }
 
-    interface Matchers<R extends void | Promise<void>, T> extends WdioMatchers<R, T> {}
+    /**
+     * Matchers defining the custom wdio matchers.
+     * Matchers is documented as the interface to augment to add other custom matchers.
+     *
+     * We MUST NOT have Jest's expect Lib matchers here, so that we can use it with Jasmine augmentation as well.
+     */
+    interface Matchers<R extends void | Promise<void>, T> extends WdioCustomMatchers<R, T> {}
 
     interface AsymmetricMatchers extends WdioAsymmetricMatchers {}
 
@@ -520,7 +561,7 @@ declare namespace ExpectWebdriverIO {
      * End of block overloading types from the expect library.
      */
 
-    type MatchersAndInverse<R extends void | Promise<void>, ActualT> = ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibInverse<ExpectWebdriverIO.Matchers<R, ActualT>>
+    type MatchersAndInverse<R extends void | Promise<void>, ActualT> = (ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibMatchers<R, ActualT>) & ExpectLibInverse<ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibMatchers<R, ActualT>>
 
     /**
      * Take from expect library
@@ -583,17 +624,25 @@ declare namespace ExpectWebdriverIO {
     type AsyncAssertionResult = ExpectLibAsyncExpectationResult
 
     /**
-     * Used by the wdio main project to configure the matchers in the runner when using Jasmine or Jest.
+     * Used to register wdio custom matcher like the Jest's `expect.extend`. Wdio main project configure the matchers in the runner when using Jasmine.
+     * Contains only the custom matchers from wdio, and not the ones from the expect library, to avoid any conflict with the matchers from the expect library when using Jasmine or Jest.
+     * Map to src/index.ts#wdioCustomMatchers
+     *
      * Equivalent as `MatchersObject` from the expect library.
      * @see https://github.com/jestjs/jest/blob/fd3d6cf9fe416b549a74b6577e5e1ea1130e3659/packages/expect/src/types.ts#L43C13-L43C27
      */
+    const wdioCustomMatchers: MatchersObject
+
+    /**
+     * @deprecated use `wdioCustomMatchers` instead
+     */
     const matchers: Map<string, RawMatcherFn>
 
     interface AssertionHookParams {
         /**
          * name of the matcher, e.g. `toHaveText` or `toBeClickable`
          */
-        matcherName: keyof Matchers<void, unknown>,
+        matcherName: keyof Matchers<void, unknown>
         /**
          * Value that the user has passed in
          *