expect-webdriverio 5.6.9 → 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/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.9",
+  "version": "5.7.0",
   "author": "Mykola Grybyk <mykola.grybyk@gmail.com>",
   "description": "WebdriverIO Assertion Library",
   "license": "MIT",
@@ -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,6 +97,7 @@
     "npm-run-all2": "^9.0.1",
     "release-it": "^20.2.0",
     "rimraf": "^6.1.3",
+    "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

@@ -468,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.
@@ -512,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 {}
 
@@ -522,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