expect-webdriverio 5.7.0 → 6.0.0

package/lib/util/numberOptionsUtil.js

@@ -0,0 +1,92 @@
+import { AsymmetricMatcher } from 'expect';
+import { isDefinedPlainObject } from './commandOptionsUtils.js';
+export const isNumber = (value) => typeof value === 'number' && !isNaN(value);
+export const isDefinedNotNumber = (value) => value !== undefined && !isNumber(value);
+export const isDefinedNumberOrNonEmptyObject = (value) => typeof value === 'number' || (typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length > 0);
+export function validateNumberAndExtractOptions(expectedValue, commandOptions, { supportDefaultAsGteThen1 } = {}) {
+    let defaultExpectedValue = undefined;
+    if (supportDefaultAsGteThen1 && (expectedValue === undefined || (isDefinedPlainObject(expectedValue) && expectedValue.eq === undefined && expectedValue.gte === undefined && expectedValue.lte === undefined))) {
+        defaultExpectedValue = new NumberMatcher({ gte: 1 });
+    }
+    else if (isNumber(expectedValue)) {
+        return { numberMatcher: new NumberMatcher({ eq: expectedValue }), commandOptions };
+    }
+    else if (!isDefinedNumberOrNonEmptyObject(expectedValue) || isDefinedNotNumber(expectedValue.eq) || isDefinedNotNumber(expectedValue.gte) || isDefinedNotNumber(expectedValue.lte)
+        || (expectedValue.eq === undefined && expectedValue.gte === undefined && expectedValue.lte === undefined)) {
+        throw new Error(`Invalid NumberMatcher. Received: ${JSON.stringify(expectedValue)}`);
+    }
+    const { eq, gte, lte, ...restCommandOptions } = expectedValue ?? {};
+    if (isNumber(gte) && isNumber(lte) && gte > lte) {
+        throw new Error(`Invalid NumberMatcher range: 'gte' (${gte}) cannot be greater than 'lte' (${lte}).`);
+    }
+    return {
+        numberMatcher: defaultExpectedValue ?? new NumberMatcher({ eq, gte, lte }),
+        commandOptions: { ...commandOptions, ...restCommandOptions }
+    };
+}
+export function validateNumberArrayAndExtractOptions(expectedValues, commandOptions, { supportDefaultAsGteThen1 } = {}) {
+    if (Array.isArray(expectedValues)) {
+        const allNumbers = expectedValues.map((value) => validateNumberAndExtractOptions(value, commandOptions, { supportDefaultAsGteThen1 }));
+        return { numberMatcher: allNumbers.map(({ numberMatcher }) => numberMatcher), commandOptions };
+    }
+    return validateNumberAndExtractOptions(expectedValues, commandOptions, { supportDefaultAsGteThen1 });
+}
+export class NumberMatcher extends AsymmetricMatcher {
+    sample;
+    constructor(sample) {
+        super(sample);
+        this.sample = sample;
+    }
+    asymmetricMatch(actual) {
+        if (actual === undefined) {
+            return false;
+        }
+        if (isNumber(this.sample)) {
+            return actual === this.sample;
+        }
+        if (isNumber(this.sample.eq)) {
+            return actual === this.sample.eq;
+        }
+        if (isNumber(this.sample.gte) && isNumber(this.sample.lte)) {
+            return actual >= this.sample.gte && actual <= this.sample.lte;
+        }
+        if (isNumber(this.sample.gte)) {
+            return actual >= this.sample.gte;
+        }
+        if (isNumber(this.sample.lte)) {
+            return actual <= this.sample.lte;
+        }
+        return false;
+    }
+    toAsymmetricMatcher() {
+        if (isNumber(this.sample)) {
+            return `${this.sample}`;
+        }
+        if (isNumber(this.sample.eq)) {
+            return `${this.sample.eq}`;
+        }
+        if (isNumber(this.sample.gte) && isNumber(this.sample.lte)) {
+            return `>= ${this.sample.gte} && <= ${this.sample.lte}`;
+        }
+        if (isNumber(this.sample.gte)) {
+            return `>= ${this.sample.gte}`;
+        }
+        if (isNumber(this.sample.lte)) {
+            return `<= ${this.sample.lte}`;
+        }
+        return 'Incorrect number options provided';
+    }
+    toString() {
+        return this.toAsymmetricMatcher();
+    }
+    jasmineToString() {
+        return this.toString();
+    }
+}
+export const isEmptyOrLegacyNumberOptions = (value) => {
+    if (!isDefinedPlainObject(value)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length === 0 || keys.filter((key) => !['eq', 'gte', 'lte'].includes(key)).length > 0;
+};

package/lib/util/refetchElements.js

@@ -1,10 +1,35 @@
-import { DEFAULT_OPTIONS } from '../constants.js';
-import { isElementArray } from './elementsUtil.js';
-export const refetchElements = async (elements, wait = DEFAULT_OPTIONS.wait, full = false) => {
-    if (elements && wait > 0 && (elements.length === 0 || full) && isElementArray(elements) && elements.parent && elements.foundWith && elements.foundWith in elements.parent) {
+import { isStrictlyElementArray } from './elementsUtil.js';
+export const refetchElements = async (elements) => {
+    if (elements
+        && isStrictlyElementArray(elements)
+        && elements.parent && elements.foundWith && elements.foundWith in elements.parent) {
         const browser = elements.parent;
         const $$ = browser[elements.foundWith];
-        elements = await $$.call(browser, elements.selector, ...elements.props);
+        return await $$.call(browser, elements.selector, ...elements.props);
     }
     return elements;
 };
+export const syncronizeElements = async (subject, refetchedElements) => {
+    if (subject instanceof Promise) {
+        await syncronizeChainableElementArray(subject, refetchedElements);
+    }
+    else if (isStrictlyElementArray(subject)) {
+        synchronizeElementArray(subject, refetchedElements);
+    }
+};
+export const syncronizeChainableElementArray = async (subject, refetchedElements) => {
+    const awaitedSubject = await subject;
+    if (isStrictlyElementArray(awaitedSubject) && refetchedElements) {
+        synchronizeElementArray(await awaitedSubject.getElements(), refetchedElements);
+    }
+};
+export const synchronizeElementArray = (subject, refetchedElements) => {
+    subject.length = refetchedElements.length;
+    for (let index = 0; index < refetchedElements.length; index++) {
+        subject[index] = refetchedElements[index];
+    }
+};
+export const refreshElementArray = async (subject) => {
+    const refetchedElements = await refetchElements(subject);
+    synchronizeElementArray(subject, refetchedElements);
+};

package/lib/util/stringUtil.js

@@ -0,0 +1,12 @@
+export const isString = (value) => typeof value === 'string';
+export const toJsonString = (value) => {
+    if (isString(value)) {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+};

package/lib/util/waitUntil.js

@@ -0,0 +1,44 @@
+import { DEFAULT_OPTIONS } from '../constants.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const waitUntil = async (condition, isNot = false, { wait = DEFAULT_OPTIONS.wait, interval = DEFAULT_OPTIONS.interval } = {}) => {
+    if (wait === 0) {
+        return await condition(0);
+    }
+    let error;
+    let result;
+    let iteration = 0;
+    try {
+        const start = Date.now();
+        while (true) {
+            if (Date.now() - start > wait) {
+                throw new Error('timeout');
+            }
+            try {
+                result = await condition(iteration++);
+                const passed = isNot !== result?.success;
+                error = undefined;
+                if (passed) {
+                    break;
+                }
+                else if (result?.abort) {
+                    return { ...result, success: isNot };
+                }
+                await sleep(interval);
+            }
+            catch (err) {
+                error = err;
+                await sleep(interval);
+            }
+        }
+        if (error) {
+            throw error;
+        }
+        return { ...result, success: !isNot };
+    }
+    catch {
+        if (error) {
+            throw error;
+        }
+        return { ...result, subject: result?.subject, success: isNot, actual: result?.actual };
+    }
+};

package/lib/utils.js

@@ -1,12 +1,13 @@
 import deepEql from 'deep-eql';
 import { expect } from 'expect';
-import { DEFAULT_OPTIONS } from './constants.js';
 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));
+import { executeCommandWithStrategy } from './util/executeCommand.js';
+import { enhanceError, enhanceErrorBe } from './util/formatMessage.js';
+import { waitUntil } from './util/waitUntil.js';
+import { DEFAULT_FEATURE_FLAGS } from './constants.js';
+import { OneOfMatcher } from './matchers/asymmetrics/oneOf.js';
 export function isJasmineStringAsymmetricMatcher(expected) {
-    return isAsymmetricMatcher(expected) && 'expected' in expected;
+    return isAsymmetricMatcher(expected) && !('toAsymmetricMatcher' in expected) && 'jasmineToString' in expected && typeof expected.jasmineToString === 'function';
 }
 export function isAsymmetricMatcher(expected) {
     return (typeof expected === 'object' &&
@@ -47,51 +48,21 @@ export function getAsymmetricMatcherValue(expected) {
     }
     return undefined;
 }
-const waitUntil = async (condition, isNot = false, { wait = DEFAULT_OPTIONS.wait, interval = DEFAULT_OPTIONS.interval } = {}) => {
-    if (wait === 0) {
-        return await condition();
-    }
-    let error;
-    try {
-        const start = Date.now();
-        while (true) {
-            if (Date.now() - start > wait) {
-                throw new Error('timeout');
-            }
-            try {
-                const result = isNot !== (await condition());
-                error = undefined;
-                if (result) {
-                    break;
-                }
-                await sleep(interval);
-            }
-            catch (err) {
-                error = err;
-                await sleep(interval);
-            }
-        }
-        if (error) {
-            throw error;
-        }
-        return !isNot;
-    }
-    catch {
-        if (error) {
-            throw error;
-        }
-        return isNot;
-    }
-};
-async function executeCommandBe(received, command, options) {
-    const { isNot, verb = 'be' } = this;
-    let el = await received?.getElement();
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand.call(this, el, async (element) => ({ result: await command(element) }), options);
-        el = result.el;
-        return result.success;
-    }, isNot, options);
-    const message = enhanceErrorBe(el, { ...this, verb }, options);
+async function executeCommandBe(received, command, options = {}) {
+    const { isNot, verb = 'be', allowEmptyElements = false } = this;
+    const { success: pass, actual, subject, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+        return await executeCommandWithStrategy({
+            unresolvedElements: received,
+            expectedValues: true,
+            singleElementCompare: async (element) => {
+                const result = await command(element);
+                return { success: result, actual: result };
+            },
+            context: { isNot, iteration },
+            strictConfiguration: { allowEmptyElements },
+        });
+    }, isNot, { wait: options.wait, interval: options.interval });
+    const message = enhanceErrorBe(subject, actual, { ...this, verb, isSome }, options);
     return {
         pass,
         message: () => message,
@@ -112,11 +83,30 @@ const compareNumbers = (actual, options = {}) => {
     }
     return false;
 };
+export const compareTextOrArray = (actualText, expectedTexts, options) => {
+    if (expectedTexts === undefined) {
+        return { actual: actualText, success: false };
+    }
+    if (Array.isArray(expectedTexts)) {
+        if (expectedTexts.some((expected) => expected instanceof OneOfMatcher)) {
+            throw new Error('OneOf is not supported in array under legacy behavior. Please enable `useToHaveTextStrictMultiElementsCompareStrategy` feature flag to use the new strict index based matching strategy with `expect.oneOf()`.');
+        }
+        else {
+            console.warn('Array of expected values is deprecated. Please use `expect.oneOf()` asymmetric matcher to compare against multiple expected values. This will be removed in v8.0.0.');
+            expectedTexts = new OneOfMatcher(...expectedTexts).withOptions(options);
+        }
+    }
+    if (expectedTexts instanceof OneOfMatcher) {
+        return { success: expectedTexts.asymmetricMatch(actualText), actual: actualText };
+    }
+    const compareResults = compareText(actualText, expectedTexts, options);
+    return { success: compareResults.success, actual: actualText };
+};
 export const compareText = (actual, expected, { ignoreCase = false, trim = true, containing = false, atStart = false, atEnd = false, atIndex, replace, }) => {
-    if (typeof actual !== 'string') {
+    if (typeof actual !== 'string' || expected === null || expected === undefined) {
         return {
-            value: actual,
-            result: false,
+            actual,
+            success: false,
         };
     }
     if (trim) {
@@ -140,50 +130,50 @@ export const compareText = (actual, expected, { ignoreCase = false, trim = true,
     if (isAsymmetricMatcher(expected)) {
         const result = expected.asymmetricMatch(actual);
         return {
-            value: actual,
-            result
+            actual,
+            success: result
         };
     }
     if (expected instanceof RegExp) {
         return {
-            value: actual,
-            result: !!actual.match(expected),
+            actual,
+            success: !!actual.match(expected),
         };
     }
     if (containing) {
         return {
-            value: actual,
-            result: actual.includes(expected),
+            actual,
+            success: actual.includes(expected),
         };
     }
     if (atStart) {
         return {
-            value: actual,
-            result: actual.startsWith(expected),
+            actual,
+            success: actual.startsWith(expected),
         };
     }
     if (atEnd) {
         return {
-            value: actual,
-            result: actual.endsWith(expected),
+            actual,
+            success: actual.endsWith(expected),
         };
     }
     if (atIndex) {
         return {
-            value: actual,
-            result: actual.substring(atIndex, actual.length).startsWith(expected),
+            actual,
+            success: actual.substring(atIndex, actual.length).startsWith(expected),
         };
     }
     return {
-        value: actual,
-        result: actual === expected,
+        actual,
+        success: actual === expected,
     };
 };
 export const compareTextWithArray = (actual, expectedArray, { ignoreCase = false, trim = false, containing = false, atStart = false, atEnd = false, atIndex, replace, }) => {
     if (typeof actual !== 'string') {
         return {
-            value: actual,
-            result: false,
+            actual,
+            success: false,
         };
     }
     if (trim) {
@@ -207,7 +197,7 @@ export const compareTextWithArray = (actual, expectedArray, { ignoreCase = false
             return item;
         });
     }
-    const textInArray = expectedArray.some((expected) => {
+    const hasFoundTextInArray = expectedArray.some((expected) => {
         if (expected instanceof RegExp) {
             return !!actual.match(expected);
         }
@@ -229,24 +219,24 @@ export const compareTextWithArray = (actual, expectedArray, { ignoreCase = false
         return actual === expected;
     });
     return {
-        value: actual,
-        result: textInArray,
+        actual,
+        success: hasFoundTextInArray,
     };
 };
 export const compareObject = (actual, expected) => {
     if (typeof actual !== 'object' || Array.isArray(actual)) {
         return {
-            value: actual,
-            result: false,
+            actual,
+            success: false,
         };
     }
     return {
-        value: actual,
-        result: deepEql(actual, expected),
+        actual,
+        success: deepEql(actual, expected),
     };
 };
 export const compareStyle = async (actualEl, style, { ignoreCase = false, trim = true, containing = false, atStart = false, atEnd = false, atIndex, replace, }) => {
-    let result = true;
+    let success = true;
     const actual = {};
     for (const key in style) {
         const css = await actualEl.getCSSProperty(key);
@@ -261,42 +251,37 @@ export const compareStyle = async (actualEl, style, { ignoreCase = false, trim =
             expectedVal = expectedVal.toLowerCase();
         }
         if (containing) {
-            result = actualVal.includes(expectedVal);
+            success = actualVal.includes(expectedVal);
             actual[key] = actualVal;
         }
         else if (atStart) {
-            result = actualVal.startsWith(expectedVal);
+            success = actualVal.startsWith(expectedVal);
             actual[key] = actualVal;
         }
         else if (atEnd) {
-            result = actualVal.endsWith(expectedVal);
+            success = actualVal.endsWith(expectedVal);
             actual[key] = actualVal;
         }
         else if (atIndex) {
-            result = actualVal.substring(atIndex, actualVal.length).startsWith(expectedVal);
+            success = actualVal.substring(atIndex, actualVal.length).startsWith(expectedVal);
             actual[key] = actualVal;
         }
         else if (replace) {
             const replacedActual = replaceActual(replace, actualVal);
-            result = replacedActual === expectedVal;
+            success = replacedActual === expectedVal;
             actual[key] = replacedActual;
         }
         else {
-            result = result && actualVal === expectedVal;
+            success = success && actualVal === expectedVal;
             actual[key] = css.value;
         }
     }
     return {
-        value: actual,
-        result,
+        actual,
+        success,
     };
 };
-function aliasFn(fn, { verb, expectation, } = {}, ...args) {
-    this.verb = verb;
-    this.expectation = expectation;
-    return fn.apply(this, args);
-}
-export { aliasFn, compareNumbers, enhanceError, executeCommand, executeCommandBe, numberError, waitUntil, wrapExpectedWithArray };
+export { compareNumbers, enhanceError, executeCommandBe, waitUntil, wrapExpectedWithArray };
 function replaceActual(replace, actual) {
     const hasMultipleReplacers = replace.every((r) => Array.isArray(r));
     const replacers = hasMultipleReplacers
@@ -311,3 +296,11 @@ function replaceActual(replace, actual) {
     }
     return actual;
 }
+export const getFeatureFlagValue = ({ featureFlags }, featureFlag) => {
+    const providedFeatureFlagValue = featureFlags?.[featureFlag];
+    if (providedFeatureFlagValue !== undefined) {
+        return providedFeatureFlagValue;
+    }
+    return DEFAULT_FEATURE_FLAGS[featureFlag] ?? false;
+};
+export const toArray = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expect-webdriverio",
-  "version": "5.7.0",
+  "version": "6.0.0",
   "author": "Mykola Grybyk <mykola.grybyk@gmail.com>",
   "description": "WebdriverIO Assertion Library",
   "license": "MIT",
@@ -77,7 +77,7 @@
     "playgrounds:snapshots:update": "cd playgrounds && npm run snapshots:update"
   },
   "dependencies": {
-    "@vitest/snapshot": "^4.1.7",
+    "@vitest/snapshot": "^4.1.10",
     "deep-eql": "^5.0.2",
     "expect": "^30.4.1",
     "jest-matcher-utils": "^30.4.1"
@@ -88,19 +88,20 @@
     "@types/jasmine": "^5.1.15",
     "@types/jest": "^30.0.0",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.12.4",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.26",
     "@wdio/eslint": "^0.1.3",
-    "@wdio/types": "^9.27.2",
-    "eslint": "^9.39.4",
+    "@wdio/types": "^9.30.1",
+    "eslint": "^9.39.5",
     "husky": "^9.1.7",
-    "npm-run-all2": "^9.0.1",
-    "release-it": "^20.2.0",
+    "npm-run-all2": "^9.0.3",
+    "release-it": "^20.2.1",
     "rimraf": "^6.1.3",
     "strip-ansi": "^7.2.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.7",
-    "webdriverio": "^9.27.2"
+    "vitest": "^4.1.10",
+    "webdriverio": "^9.30.1"
   },
   "peerDependencies": {
     "@wdio/globals": "^9.0.0",