expect-webdriverio 5.7.0 → 6.0.0

package/README.md

@@ -7,15 +7,20 @@
 
 ## Key Features
 
-- [waits](#default-options) for expectation to succeed
-- detailed [error messages](#error-messages)
-- works in Mocha, Cucumber, Jest, Jasmine
-- builtin [types](docs/Types.md) for TypeScript and JS autocompletion
+- [Waits](#default-options) for expectation to succeed
+- Support single element & multi-elements
+- Detailed [error messages](#error-messages)
+- Works in Mocha, Cucumber, Jest, Jasmine
+- Builtin [types](docs/Types.md) for TypeScript and JS autocompletion
 
 ## Installation
 
-1. `npm install expect` (**Jasmine** and **Jest** users should skip this step)
-2. `npm install expect-webdriverio`
+1. `npm install expect-webdriverio`
+2. Install your test framework adapter (if not already set up via WDIO testrunner):
+   - **Mocha** (default): `npm install @wdio/mocha-framework`
+   - **Jasmine**: `npm install @wdio/jasmine-framework`
+   - **Cucumber**: `npm install @wdio/cucumber-framework`
+   - **Jest**: No adapter needed — see [Jest Framework section](docs/Framework.md#jest)
 
 NOTE: [WebdriverIO](https://github.com/webdriverio/webdriverio) `v9.0.0` or higher is required!
 
@@ -26,15 +31,15 @@ NOTE: [WebdriverIO](https://github.com/webdriverio/webdriverio) `v9.0.0` or high
 If you run your tests through the [WDIO testrunner](https://webdriver.io/docs/clioptions) no additional setup is needed. WebdriverIO initialises `expect-webdriverio` and makes `expect` available in the global scope. So you can use it directly in your tests:
 
 ```js
-const $button = await $('button')
-await expect($button).toBeDisplayed()
+const button = await $('button')
+await expect(button).toBeDisplayed()
 ```
 
 See more [Examples](docs/Examples.md)
 
 ### Using in a standalone script
 
-If you embed WebdriverIO in a standalone script, make sure you import `expect-webdriverio` before you use it anywhere.
+If you embed WebdriverIO in a standalone (without `@wdio/globals`), make sure you import `expect-webdriverio` before you use it anywhere.
 
 ```js
 import { remote } from 'webdriverio'
@@ -77,8 +82,5 @@ First of all, **feel free to raise an issue with your suggestions or help with P
 
 ### Planned
 
-- css matcher
-- size matcher
-- cookie / localStorage matchers?
-- text regex matchers
-- multiremote support (if requested)
+- cookie
+- multiremote support (coming)

package/lib/constants.js

@@ -1,8 +1,12 @@
+export const DEFAULT_FEATURE_FLAGS = {
+    useToHaveTextStrictMultiElementsCompareStrategy: false
+};
 export const DEFAULT_OPTIONS = {
     wait: 2000,
     interval: 100,
     beforeAssertion: async () => { },
     afterAssertion: async () => { },
+    featureFlags: DEFAULT_FEATURE_FLAGS
 };
 export const DEFAULT_OPTIONS_TO_BE_DISPLAYED = {
     ...DEFAULT_OPTIONS,

package/lib/index.js

@@ -3,41 +3,45 @@ import * as wdioMatchers from './matchers.js';
 import { DEFAULT_OPTIONS, defaultOptionsList } from './constants.js';
 import createSoftExpect from './softExpect.js';
 import { SoftAssertService } from './softAssert.js';
+import { oneOf } from './matchers/asymmetrics/oneOf.js';
+import { some as wdioSome } from './matchers/modifiers/some.js';
 export const wdioCustomMatchers = {};
 export const matchers = new Map();
-const filteredMatchers = {};
 const extend = expectLib.extend;
-Object.keys(wdioMatchers).forEach(matcher => {
-    if (typeof wdioMatchers[matcher] === 'function') {
-        filteredMatchers[matcher] = wdioMatchers[matcher];
-    }
-});
-expectLib.extend = (m) => {
-    if (!m || typeof m !== 'object') {
+expectLib.extend = (extendedMatchers) => {
+    if (!extendedMatchers || typeof extendedMatchers !== 'object') {
         return;
     }
-    Object.entries(m).forEach(([name, matcher]) => {
+    Object.entries(extendedMatchers).forEach(([name, matcher]) => {
         wdioCustomMatchers[name] = matcher;
         matchers.set(name, matcher);
     });
-    return extend(m);
+    return extend(extendedMatchers);
 };
-expectLib.extend(filteredMatchers);
-const expectWithSoft = expectLib;
-Object.defineProperty(expectWithSoft, 'soft', {
+const filteredWdioMatchers = {};
+Object.entries(wdioMatchers).forEach(([matcher, value]) => {
+    if (typeof value === 'function') {
+        filteredWdioMatchers[matcher] = value;
+    }
+});
+const wdioExpect = expectLib;
+wdioExpect.extend(filteredWdioMatchers);
+wdioExpect.oneOf = oneOf;
+Object.defineProperty(wdioExpect, 'soft', {
     value: (actual) => createSoftExpect(actual)
 });
-Object.defineProperty(expectWithSoft, 'getSoftFailures', {
+Object.defineProperty(wdioExpect, 'getSoftFailures', {
     value: (testId) => SoftAssertService.getInstance().getFailures(testId)
 });
-Object.defineProperty(expectWithSoft, 'assertSoftFailures', {
+Object.defineProperty(wdioExpect, 'assertSoftFailures', {
     value: (testId) => SoftAssertService.getInstance().assertNoFailures(testId)
 });
-Object.defineProperty(expectWithSoft, 'clearSoftFailures', {
+Object.defineProperty(wdioExpect, 'clearSoftFailures', {
     value: (testId) => SoftAssertService.getInstance().clearFailures(testId)
 });
-export const expect = expectWithSoft;
-export const getConfig = () => DEFAULT_OPTIONS;
+export const expect = wdioExpect;
+export const some = wdioSome;
+export const getDefaultOptions = () => DEFAULT_OPTIONS;
 export const setDefaultOptions = (options) => {
     Object.entries(options).forEach(([key, value]) => {
         defaultOptionsList.forEach((option) => {
@@ -47,7 +51,15 @@ export const setDefaultOptions = (options) => {
         });
     });
 };
+export const setFeatureFlags = (featureFlags) => {
+    Object.entries(featureFlags).forEach(([ffName, ffValue]) => {
+        defaultOptionsList.forEach((option) => {
+            option.featureFlags[ffName] = ffValue;
+        });
+    });
+};
 export const setOptions = setDefaultOptions;
+export const getConfig = getDefaultOptions;
 export { SnapshotService } from './snapshot.js';
 export { SoftAssertService } from './softAssert.js';
 export { SoftAssertionService } from './softAssertService.js';

package/lib/matchers/asymmetrics/asymmetricsUtils.js

@@ -0,0 +1,24 @@
+import { AsymmetricMatcher } from 'expect';
+import { isAsymmetricMatcher } from '../../utils.js';
+export const buildWdioAsymmetricMatchersWithOptions = (expectedValue, options) => {
+    if (options) {
+        if (Array.isArray(expectedValue)) {
+            return expectedValue.map((value) => buildOneAsymmetricMatcherWithOptions(value, options));
+        }
+        return buildOneAsymmetricMatcherWithOptions(expectedValue, options);
+    }
+    return expectedValue;
+};
+const buildOneAsymmetricMatcherWithOptions = (expectedValue, options) => {
+    if (options) {
+        if (isAsymmetricMatcher(expectedValue) && 'withOptions' in expectedValue && typeof expectedValue.withOptions === 'function') {
+            return expectedValue.withOptions(options);
+        }
+    }
+    return expectedValue;
+};
+export class WdioAsymmetricMatchers extends AsymmetricMatcher {
+    toString() {
+        return this.toAsymmetricMatcher();
+    }
+}

package/lib/matchers/asymmetrics/oneOf.js

@@ -0,0 +1,51 @@
+import { compareTextWithArray } from '../../utils.js';
+import { WdioAsymmetricMatchers } from './asymmetricsUtils.js';
+export class OneOfMatcher extends WdioAsymmetricMatchers {
+    options = {};
+    constructor(...sample) {
+        super(sample);
+    }
+    setOptions(options) {
+        this.options = options;
+        return this;
+    }
+    asymmetricMatch(actual) {
+        if (actual === null) {
+            return this.sample.includes(null);
+        }
+        else if (typeof actual !== 'string') {
+            return false;
+        }
+        return compareTextWithArray(actual, this.sample.filter(s => s !== null), this.options).success;
+    }
+    withOptions(options) {
+        return new OneOfMatcher(...this.sample).setOptions(options);
+    }
+    toAsymmetricMatcher() {
+        let prefix = '';
+        if (this.options.containing) {
+            prefix = 'containing';
+        }
+        else if (this.options.atStart) {
+            prefix = 'startingWith';
+        }
+        else if (this.options.atEnd) {
+            prefix = 'endingWith';
+        }
+        else if (typeof this.options.atIndex === 'number') {
+            prefix = `matchingAtIndex<${this.options.atIndex}>`;
+        }
+        const isArray = Array.isArray(this.sample);
+        const samples = isArray ? this.sample : [this.sample];
+        const formattedSamples = samples
+            .map((s) => (s instanceof RegExp ? s.toString() : `"${s}"`))
+            .join(', ');
+        if (isArray) {
+            prefix = prefix ? prefix + 'OneOf' : 'oneOf';
+        }
+        return prefix ? `${prefix}<${formattedSamples}>` : formattedSamples;
+    }
+}
+export function oneOf(...sample) {
+    return new OneOfMatcher(...sample);
+}

package/lib/matchers/browser/toHaveClipboardText.js

@@ -3,27 +3,26 @@ import { waitUntil, enhanceError, compareText } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 const log = logger('expect-webdriverio');
 export async function toHaveClipboardText(browser, expectedValue, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'clipboard text', verb = 'have' } = this;
+    const { expectation = 'clipboard text', verb = 'have', isNot, matcherName = 'toHaveClipboardText' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toHaveClipboardText',
+        matcherName,
         expectedValue,
         options,
     });
-    let actual;
-    const pass = await waitUntil(async () => {
+    const { actual, success: pass } = await waitUntil(async () => {
         await browser.setPermissions({ name: 'clipboard-read' }, 'granted')
             .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`));
-        actual = await browser.execute(() => window.navigator.clipboard.readText());
-        return compareText(actual, expectedValue, options).result;
-    }, isNot, options);
+        const actual = await browser.execute(() => window.navigator.clipboard.readText());
+        const compareResult = compareText(actual, expectedValue, options);
+        return { actual, success: compareResult.success, subject: browser };
+    }, isNot, { wait: options.wait, interval: options.interval });
     const message = enhanceError('browser', expectedValue, actual, this, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message
     };
     await options.afterAssertion?.({
-        matcherName: 'toHaveClipboardText',
+        matcherName,
         expectedValue,
         options,
         result

package/lib/matchers/browser/toHaveLocalStorageItem.js

@@ -1,33 +1,41 @@
 import { waitUntil, enhanceError, compareText } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
+import { expect } from '../../index.js';
 export async function toHaveLocalStorageItem(browser, key, expectedValue, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'localStorage item', verb = 'have' } = this;
+    const { expectation = 'localStorage item', verb = 'have', isNot, matcherName = 'toHaveLocalStorageItem' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toHaveLocalStorageItem',
+        matcherName,
         expectedValue: expectedValue ? [key, expectedValue] : key,
         options,
     });
-    let actual;
-    const pass = await waitUntil(async () => {
-        actual = await browser.execute((storageKey) => {
+    const paramsCount = arguments.length;
+    let expected;
+    if (expectedValue === undefined) {
+        if (paramsCount > 2) {
+            console.warn('[DEPRECATION] Using toHaveLocalStorageItem with undefined is deprecated in favor of expect.anything().');
+        }
+        expected = expect.anything();
+    }
+    else {
+        expected = expectedValue;
+    }
+    const { actual, success: pass } = await waitUntil(async () => {
+        const actual = await browser.execute((storageKey) => {
             return localStorage.getItem(storageKey);
         }, key);
-        if (expectedValue === undefined) {
-            return actual !== null;
-        }
         if (actual === null) {
-            return false;
+            return { actual, success: false, subject: browser };
         }
-        return compareText(actual, expectedValue, options).result;
-    }, isNot, options);
-    const message = enhanceError('browser', expectedValue !== undefined ? expectedValue : `localStorage item "${key}"`, actual, this, verb, expectation, key, options);
+        const compareResult = compareText(actual, expected, options);
+        return { actual, success: compareResult.success, subject: browser };
+    }, isNot, { wait: options.wait, interval: options.interval });
+    const message = enhanceError('browser', expected, actual, this, verb, expectation, key, options);
     const result = {
         pass,
         message: () => message
     };
     await options.afterAssertion?.({
-        matcherName: 'toHaveLocalStorageItem',
+        matcherName,
         expectedValue: expectedValue ? [key, expectedValue] : key,
         options,
         result

package/lib/matchers/browser/toHaveTitle.js

@@ -1,25 +1,24 @@
 import { waitUntil, enhanceError, compareText } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toHaveTitle(browser, expectedValue, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'title', verb = 'have' } = this;
+    const { expectation = 'title', verb = 'have', isNot, matcherName = 'toHaveTitle' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toHaveTitle',
+        matcherName,
         expectedValue,
         options,
     });
-    let actual;
-    const pass = await waitUntil(async () => {
-        actual = await browser.getTitle();
-        return compareText(actual, expectedValue, options).result;
-    }, isNot, options);
+    const { actual, success } = await waitUntil(async () => {
+        const actual = await browser.getTitle();
+        const compareResult = compareText(actual, expectedValue, options);
+        return { actual, success: compareResult.success, subject: browser };
+    }, isNot, { wait: options.wait, interval: options.interval });
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options);
     const result = {
-        pass,
+        pass: success,
         message: () => message
     };
     await options.afterAssertion?.({
-        matcherName: 'toHaveTitle',
+        matcherName,
         expectedValue,
         options,
         result

package/lib/matchers/browser/toHaveUrl.js

@@ -1,25 +1,24 @@
 import { waitUntil, enhanceError, compareText } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toHaveUrl(browser, expectedValue, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'url', verb = 'have' } = this;
+    const { expectation = 'url', verb = 'have', isNot, matcherName = 'toHaveUrl' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toHaveUrl',
+        matcherName,
         expectedValue,
         options,
     });
-    let actual;
-    const pass = await waitUntil(async () => {
-        actual = await browser.getUrl();
-        return compareText(actual, expectedValue, options).result;
-    }, isNot, options);
+    const { success: pass, actual } = await waitUntil(async () => {
+        const actual = await browser.getUrl();
+        const compareResult = compareText(actual, expectedValue, options);
+        return { actual, success: compareResult.success, subject: browser };
+    }, isNot, { wait: options.wait, interval: options.interval });
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message
     };
     await options.afterAssertion?.({
-        matcherName: 'toHaveUrl',
+        matcherName,
         expectedValue,
         options,
         result

package/lib/matchers/element/toBeExisting.js

@@ -1,8 +1,9 @@
-import { executeCommandBe, aliasFn } from '../../utils.js';
+import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toExist(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'exist';
     this.verb = this.verb || '';
+    this.allowEmptyElements = true;
     await options.beforeAssertion?.({
         matcherName: 'toExist',
         options,
@@ -16,8 +17,12 @@ export async function toExist(received, options = DEFAULT_OPTIONS) {
     return result;
 }
 export function toBeExisting(el, options) {
-    return aliasFn.call(this, toExist, { verb: 'be', expectation: 'existing' }, el, options);
+    this.expectation = 'existing';
+    this.verb = 'be';
+    return toExist.call(this, el, options);
 }
 export function toBePresent(el, options) {
-    return aliasFn.call(this, toExist, { verb: 'be', expectation: 'present' }, el, options);
+    this.expectation = 'present';
+    this.verb = 'be';
+    return toExist.call(this, el, options);
 }

package/lib/matchers/element/toBeSelected.js

@@ -2,29 +2,22 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeSelected(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'selected';
+    this.matcherName = this.matcherName || 'toBeSelected';
     await options.beforeAssertion?.({
-        matcherName: 'toBeSelected',
+        matcherName: this.matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isSelected(), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeSelected',
+        matcherName: this.matcherName,
         options,
         result
     });
     return result;
 }
-export async function toBeChecked(el, options = DEFAULT_OPTIONS) {
+export async function toBeChecked(received, options = DEFAULT_OPTIONS) {
     this.expectation = 'checked';
-    await options.beforeAssertion?.({
-        matcherName: 'toBeChecked',
-        options,
-    });
-    const result = await toBeSelected.call(this, el, options);
-    await options.afterAssertion?.({
-        matcherName: 'toBeChecked',
-        options,
-        result
-    });
+    this.matcherName = 'toBeChecked';
+    const result = await toBeSelected.call(this, received, options);
     return result;
 }

package/lib/matchers/element/toHaveAttribute.js

@@ -1,63 +1,64 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
-import { compareText, enhanceError, executeCommand, waitUntil, wrapExpectedWithArray } from '../../utils.js';
-async function conditionAttr(el, attribute) {
-    const attr = await el.getAttribute(attribute);
-    if (typeof attr !== 'string') {
-        return { result: false, value: attr };
+import { executeCommandWithStrategy } from '../../util/executeCommand.js';
+import { compareText, enhanceError, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { expect as wdioExpect } from '../../index.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
+import { OneOfMatcher } from '../asymmetrics/oneOf.js';
+async function conditionAttributeValueMatchWithExpected(el, attribute, expectedValue, options) {
+    const attributeValue = await el.getAttribute(attribute);
+    if (typeof attributeValue !== 'string' || expectedValue === undefined || expectedValue === null) {
+        if (isAsymmetricMatcher(expectedValue)) {
+            return { success: expectedValue.asymmetricMatch(attributeValue), actual: attributeValue };
+        }
+        return { success: attributeValue === expectedValue, actual: attributeValue };
     }
-    return { result: true, value: attr };
-}
-async function conditionAttrAndValue(el, attribute, value, options) {
-    const attr = await el.getAttribute(attribute);
-    if (typeof attr !== 'string') {
-        return { result: false, value: attr };
+    else if (expectedValue instanceof OneOfMatcher) {
+        return { success: expectedValue.asymmetricMatch(attributeValue), actual: attributeValue };
     }
-    return compareText(attr, value, options);
-}
-export async function toHaveAttributeAndValue(received, attribute, value, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'attribute', verb = 'have' } = this;
-    let el = await received?.getElement();
-    let attr;
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand.call(this, el, conditionAttrAndValue, options, [attribute, value, options]);
-        el = result.el;
-        attr = result.values;
-        return result.success;
-    }, isNot, options);
-    const expected = wrapExpectedWithArray(el, attr, value);
-    const message = enhanceError(el, expected, attr, this, verb, expectation, attribute, options);
-    return {
-        pass,
-        message: () => message
-    };
+    return compareText(attributeValue, expectedValue, options);
 }
-async function toHaveAttributeFn(received, attribute) {
-    const isNot = this.isNot;
-    const { expectation = 'attribute', verb = 'have' } = this;
-    let el = await received?.getElement();
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand.call(this, el, conditionAttr, {}, [attribute]);
-        el = result.el;
-        return result.success;
-    }, isNot, {});
-    const message = enhanceError(el, !isNot, pass, this, verb, expectation, attribute, {});
+export async function toHaveAttributeAndValue(received, attribute, expectedValue, options = DEFAULT_OPTIONS) {
+    const { expectation = 'attribute', verb = 'have', isNot } = this;
+    expectedValue = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
+    const { success: pass, actual: attr, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+        return await executeCommandWithStrategy({
+            unresolvedElements: received,
+            expectedValues: expectedValue,
+            singleElementCompare: (element, values) => {
+                return conditionAttributeValueMatchWithExpected(element, attribute, values, options);
+            },
+            context: { isNot, iteration },
+            strategy: 'NewStrictMultipleElements',
+        });
+    }, isNot, { wait: options.wait, interval: options.interval });
+    const expected = wrapExpectedWithArray(el, attr, expectedValue);
+    const message = enhanceError(el, expected, attr, { isNot, isSome }, verb, expectation, attribute, options);
     return {
         pass,
         message: () => message
     };
 }
 export async function toHaveAttribute(received, attribute, value, options = DEFAULT_OPTIONS) {
+    const matcherName = 'toHaveAttribute';
+    const paramsCount = arguments.length;
     await options.beforeAssertion?.({
-        matcherName: 'toHaveAttribute',
+        matcherName,
         expectedValue: [attribute, value],
         options,
     });
-    const result = value !== undefined
-        ? await toHaveAttributeAndValue.call(this, received, attribute, value, options)
-        : await toHaveAttributeFn.call(this, received, attribute);
+    let expectedValue;
+    if (value === undefined) {
+        if (paramsCount > 2) {
+            console.warn('Using undefined or null as value for toHaveAttribute is deprecated and will be removed in v6.0.0. Please omit the third argument entirely or use toHaveAttribute(el, attribute, wdioExpect.anything(), options).');
+        }
+        expectedValue = wdioExpect.anything();
+    }
+    else {
+        expectedValue = value;
+    }
+    const result = await toHaveAttributeAndValue.call(this, received, attribute, expectedValue, options);
     await options.afterAssertion?.({
-        matcherName: 'toHaveAttribute',
+        matcherName,
         expectedValue: [attribute, value],
         options,
         result

package/lib/matchers/element/toHaveChildren.js

@@ -1,49 +1,47 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
-import { compareNumbers, enhanceError, executeCommand, numberError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
-async function condition(el, options) {
+import { executeCommandWithStrategy } from '../../util/executeCommand.js';
+import { isEmptyOrLegacyNumberOptions, validateNumberArrayAndExtractOptions } from '../../util/numberOptionsUtil.js';
+import { enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+async function condition(el, expectedValue) {
     const children = await el.$$('./*').getElements();
-    if (typeof options.lte !== 'number' &&
-        typeof options.gte !== 'number' &&
-        typeof options.eq !== 'number') {
-        return {
-            result: children.length > 0,
-            value: children?.length
-        };
+    if (expectedValue === undefined) {
+        return { success: false, actual: children?.length };
     }
     return {
-        result: compareNumbers(children?.length, options),
-        value: children?.length
+        success: expectedValue?.asymmetricMatch(children?.length) ?? false,
+        actual: children?.length
     };
 }
-export async function toHaveChildren(received, expectedValue, options = DEFAULT_OPTIONS) {
-    const isNot = this.isNot;
-    const { expectation = 'children', verb = 'have' } = this;
+export async function toHaveChildren(received, expectedValueOrOptions, options = DEFAULT_OPTIONS) {
+    const { expectation = 'children', verb = 'have', isNot, matcherName = 'toHaveChildren' } = this;
+    const paramsCount = arguments.length;
+    if (paramsCount > 1 && (expectedValueOrOptions === undefined || isEmptyOrLegacyNumberOptions(expectedValueOrOptions))) {
+        console.warn('Passing undefined or NumberOptions as the second argument to toHaveChildren is deprecated. Use a NumberMatcher instead. For example, `expect(el).toHaveChildren({ gte: 1 }, options)`');
+    }
     await options.beforeAssertion?.({
-        matcherName: 'toHaveChildren',
-        expectedValue,
+        matcherName,
+        expectedValue: expectedValueOrOptions,
         options,
     });
-    const numberOptions = typeof expectedValue === 'number'
-        ? { eq: expectedValue }
-        : expectedValue || {};
-    let el = await received?.getElement();
-    let children;
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand.call(this, el, condition, numberOptions, [numberOptions]);
-        el = result.el;
-        children = result.values;
-        return result.success;
-    }, isNot, { ...numberOptions, ...options });
-    const error = numberError(numberOptions);
-    const expectedArray = wrapExpectedWithArray(el, children, error);
-    const message = enhanceError(el, expectedArray, children, this, verb, expectation, '', numberOptions);
+    const { numberMatcher: expectedNumber, commandOptions } = validateNumberArrayAndExtractOptions(expectedValueOrOptions, options, { supportDefaultAsGteThen1: true });
+    const { success: pass, actual: children, subject, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+        return await executeCommandWithStrategy({
+            unresolvedElements: received,
+            expectedValues: expectedNumber,
+            singleElementCompare: (element, expectedValue) => condition(element, expectedValue),
+            context: { isNot, iteration },
+            strategy: 'NewStrictMultipleElements',
+        });
+    }, isNot, { wait: commandOptions.wait, interval: commandOptions.interval });
+    const expectedArray = wrapExpectedWithArray(subject, children, expectedNumber);
+    const message = enhanceError(subject, expectedArray, children, { isNot, isSome }, verb, expectation, '', commandOptions);
     const result = {
         pass,
         message: () => message
     };
     await options.afterAssertion?.({
-        matcherName: 'toHaveChildren',
-        expectedValue,
+        matcherName,
+        expectedValue: expectedValueOrOptions,
         options,
         result
     });