expect-webdriverio 6.1.0 → 7.0.1

package/README.md

@@ -1,13 +1,14 @@
 # expect-webdriverio [![Test](https://github.com/webdriverio/expect-webdriverio/actions/workflows/test.yml/badge.svg)](https://github.com/webdriverio/expect-webdriverio/actions/workflows/test.yml)
 
-###### [API](docs/API.md) | [TypeScript / JS Autocomplete](docs/Types.md) | [Examples](docs/Examples.md) | [Extending Matchers](docs/CustomMatchers.md)
+###### [API](docs/API.md) | [Multiple Elements](docs/MultipleElements.md) | [Multi-remote](docs/MultiRemote.md) | [TypeScript / JS Autocomplete](docs/Types.md) | [Examples](docs/Examples.md) | [Extending Matchers](docs/CustomMatchers.md)
 
 > [WebdriverIO](https://webdriver.io/) assertion library inspired by [expect](https://www.npmjs.com/package/expect)
 
 ## Key Features
 
-- [Waits](#default-options) for expectations to succeed
-- Supports single element `$()` & multiple elements `$$()`
+- [Waits](docs/API.md#default-options) for expectations to succeed
+- Supports single element `$()` & [multiple elements](docs/MultipleElements.md) `$$()`
+- Supports [multi-remote](docs/MultiRemote.md) browsers & elements, with one expected value per browser instance
 - Detailed [error messages](#error-messages)
 - Works in Mocha, Cucumber, Jest, and Jasmine
 - Built-in [types](docs/Types.md) for TypeScript and JS autocompletion
@@ -21,7 +22,7 @@
    - **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!
+**Note:** [WebdriverIO](https://github.com/webdriverio/webdriverio) `v9.31.5` or higher is required!
 
 ## Usage
 
@@ -36,6 +37,17 @@ await expect($$('buttons')).toBeDisplayed()
 
 See more [Examples](docs/Examples.md).
 
+#### Multi-remote
+
+With [multi-remote](https://webdriver.io/docs/multiremote), assertions check every browser instance, with a single expected value or one per instance:
+
+```js
+await expect(multiRemoteBrowser).toHaveTitle('WebdriverIO')
+await expect(multiRemoteBrowser.$('h1')).toHaveText(expect.multiRemote({ chrome: 'Welcome', firefox: 'Bienvenue' }))
+```
+
+Some feature flags and WebdriverIO environment variables are required or recommended, see [Multi-remote Support](docs/MultiRemote.md#requirements--configuration).
+
 #### Local & Browser Runners
 - **Local Runner**: Fully compatible. You can leverage your test framework adapter as mentioned above.
 - **Browser Runner**: Designed for component frameworks like React, Preact, Vue.js, Svelte, and SolidJS, with a few known limitations. For details, see the [Browser Runner Framework section](docs/Framework.md#browser-runner).
@@ -86,4 +98,3 @@ First of all, **feel free to raise an issue with your suggestions or help with P
 ### Planned
 
 - Cookie matchers
-- Multiremote support (in progress)

package/jest.d.ts

@@ -19,16 +19,18 @@ declare namespace jest {
 
         /**
          * snapshot matcher
+         * A plain `Element[]` or `MultiRemoteElement[]` is only recognized from its elements, so an empty one is snapshotted synchronously
          * @param label optional snapshot label
          */
-        toMatchSnapshot(label?: string): T extends WdioElementOrPromiseLike ? Promise<void> : R;
+        toMatchSnapshot(label?: string): T extends WdioElementOrPromiseLike | WebdriverIO.MultiRemoteElement | WebdriverIO.ElementArray ? Promise<void> : T extends WebdriverIO.Element[] | WebdriverIO.MultiRemoteElement[] ? Promise<void> | R : R;
 
         /**
          * inline snapshot matcher
+         * A plain `Element[]` or `MultiRemoteElement[]` is only recognized from its elements, so an empty one is snapshotted synchronously
          * @param snapshot snapshot string (autogenerated if not specified)
          * @param label optional snapshot label
          */
-        toMatchInlineSnapshot(snapshot?: string, label?: string): T extends WdioElementOrPromiseLike ? Promise<void> : R;
+        toMatchInlineSnapshot(snapshot?: string, label?: string): T extends WdioElementOrPromiseLike | WebdriverIO.MultiRemoteElement | WebdriverIO.ElementArray ? Promise<void> : T extends WebdriverIO.Element[] | WebdriverIO.MultiRemoteElement[] ? Promise<void> | R : R;
     }
 
     interface Expect extends ExpectWebdriverIO.Expect {}

package/lib/api/index.js

@@ -1,2 +1,4 @@
 import { some as wdioSome } from '../matchers/modifiers/some.js';
+import { multiRemote as wdioMultiRemote } from '../matchers/asymmetrics/multiRemote.js';
 export const some = wdioSome;
+export const multiRemote = wdioMultiRemote;

package/lib/index.js

@@ -4,6 +4,7 @@ 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 { multiRemote } from './matchers/asymmetrics/multiRemote.js';
 import { getGlobalSingleton } from './util/globalSingleton.js';
 function createSharedExpectSetup() {
     const wdioCustomMatchers = {};
@@ -28,6 +29,7 @@ function createSharedExpectSetup() {
     const wdioExpect = expectLib;
     wdioExpect.extend(filteredWdioMatchers);
     wdioExpect.oneOf = oneOf;
+    wdioExpect.multiRemote = multiRemote;
     Object.defineProperty(wdioExpect, 'soft', {
         configurable: true,
         value: (actual) => createSoftExpect(actual)

package/lib/matchers/asymmetrics/asymmetricsUtils.js

@@ -5,10 +5,20 @@ export const buildWdioAsymmetricMatchersWithOptions = (expectedValue, options) =
         if (Array.isArray(expectedValue)) {
             return expectedValue.map((value) => buildOneAsymmetricMatcherWithOptions(value, options));
         }
+        if (isPlainObject(expectedValue)) {
+            return Object.fromEntries(Object.entries(expectedValue).map(([key, value]) => [key, buildWdioAsymmetricMatchersWithOptions(value, options)]));
+        }
         return buildOneAsymmetricMatcherWithOptions(expectedValue, options);
     }
     return expectedValue;
 };
+const isPlainObject = (value) => {
+    if (typeof value !== 'object' || value === null || isAsymmetricMatcher(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
 const buildOneAsymmetricMatcherWithOptions = (expectedValue, options) => {
     if (options) {
         if (isAsymmetricMatcher(expectedValue) && 'withOptions' in expectedValue && typeof expectedValue.withOptions === 'function') {

package/lib/matchers/asymmetrics/multiRemote.js

@@ -0,0 +1,36 @@
+import { equals } from '../../jasmineUtils.js';
+import { hasSameInstanceNames, isMultiRemoteValues, MULTI_REMOTE_MATCHER_SYMBOL } from '../../util/multiRemoteUtils.js';
+import { buildWdioAsymmetricMatchersWithOptions, WdioAsymmetricMatchers } from './asymmetricsUtils.js';
+export class MultiRemoteMatcher extends WdioAsymmetricMatchers {
+    [MULTI_REMOTE_MATCHER_SYMBOL] = true;
+    constructor(sample) {
+        if (!isMultiRemoteValues(sample)) {
+            throw new TypeError(`expect.multiRemote() expects an object with one expected value per multi-remote instance, e.g. { chrome: 'A', firefox: 'B' }. Received: ${String(sample)}`);
+        }
+        super(sample);
+    }
+    get values() {
+        return this.sample;
+    }
+    asymmetricMatch(actual) {
+        return isMultiRemoteValues(actual)
+            && hasSameInstanceNames(actual, Object.keys(this.sample))
+            && Object.entries(this.sample).every(([instance, expected]) => equals(actual[instance], expected));
+    }
+    withOptions(options) {
+        return new MultiRemoteMatcher(buildWdioAsymmetricMatchersWithOptions({ ...this.sample }, options));
+    }
+    toAsymmetricMatcher() {
+        const values = Object.entries(this.sample).map(([instance, expected]) => `${instance}: ${formatValue(expected)}`);
+        return `multiRemote<${values.join(', ')}>`;
+    }
+}
+const formatValue = (value) => {
+    if (value && typeof value === 'object' && 'toAsymmetricMatcher' in value && typeof value.toAsymmetricMatcher === 'function') {
+        return value.toAsymmetricMatcher();
+    }
+    return value instanceof RegExp ? value.toString() : JSON.stringify(value) ?? String(value);
+};
+export function multiRemote(values) {
+    return new MultiRemoteMatcher(values);
+}

package/lib/matchers/browser/toHaveClipboardText.js

@@ -1,6 +1,8 @@
 import logger from '@wdio/logger';
-import { waitUntil, enhanceError, compareText } from '../../utils.js';
+import { waitUntil, enhanceError, compareTextOrOneOf } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
+import { executeBrowserCommand } from '../../util/executeBrowserCommand.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 const log = logger('expect-webdriverio');
 export async function toHaveClipboardText(browser, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'clipboard text', verb = 'have', isNot, matcherName = 'toHaveClipboardText' } = this;
@@ -9,14 +11,16 @@ export async function toHaveClipboardText(browser, expectedValue, options = DEFA
         expectedValue,
         options,
     });
-    const { actual, success: pass } = await waitUntil(async () => {
-        await browser.setPermissions({ name: 'clipboard-read' }, 'granted')
-            .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`));
-        const actual = await browser.execute(() => window.navigator.clipboard.readText());
-        const compareResult = compareText(actual, expectedValue, options);
-        return { actual, success: compareResult.success, subject: browser };
+    const expectedWithOptions = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
+    const { actual, success: pass, subject, expected } = await waitUntil(async () => {
+        return await executeBrowserCommand({
+            browser,
+            isNot,
+            expectedValue: expectedWithOptions,
+            compare: (browser, expectedValue) => compareClipboardText(browser, expectedValue, options),
+        });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError('browser', expectedValue, actual, this, verb, expectation, '', options);
+    const message = enhanceError(subject, expected, actual, this, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message
@@ -29,3 +33,9 @@ export async function toHaveClipboardText(browser, expectedValue, options = DEFA
     });
     return result;
 }
+const compareClipboardText = async (browser, expectedValue, options) => {
+    await browser.setPermissions({ name: 'clipboard-read' }, 'granted')
+        .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`));
+    const actual = await browser.execute(() => window.navigator.clipboard.readText());
+    return compareTextOrOneOf(actual, expectedValue, options);
+};

package/lib/matchers/browser/toHaveLocalStorageItem.js

@@ -1,6 +1,8 @@
-import { waitUntil, enhanceError, compareText } from '../../utils.js';
+import { waitUntil, enhanceError, compareTextOrOneOf } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 import { expect } from 'expect';
+import { executeBrowserCommand } from '../../util/executeBrowserCommand.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 export async function toHaveLocalStorageItem(browser, key, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'localStorage item', verb = 'have', isNot, matcherName = 'toHaveLocalStorageItem' } = this;
     await options.beforeAssertion?.({
@@ -19,17 +21,16 @@ export async function toHaveLocalStorageItem(browser, key, expectedValue, option
     else {
         expected = expectedValue;
     }
-    const { actual, success: pass } = await waitUntil(async () => {
-        const actual = await browser.execute((storageKey) => {
-            return localStorage.getItem(storageKey);
-        }, key);
-        if (actual === null) {
-            return { actual, success: false, subject: browser };
-        }
-        const compareResult = compareText(actual, expected, options);
-        return { actual, success: compareResult.success, subject: browser };
+    const expectedWithOptions = buildWdioAsymmetricMatchersWithOptions(expected, options);
+    const { actual, success: pass, subject, expected: expectedValues } = await waitUntil(async () => {
+        return await executeBrowserCommand({
+            browser,
+            isNot,
+            expectedValue: expectedWithOptions,
+            compare: (browser, expectedValue) => compareStorageItem(browser, key, expectedValue, options),
+        });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError('browser', expected, actual, this, verb, expectation, key, options);
+    const message = enhanceError(subject, expectedValues, actual, this, verb, expectation, key, options);
     const result = {
         pass,
         message: () => message
@@ -42,3 +43,13 @@ export async function toHaveLocalStorageItem(browser, key, expectedValue, option
     });
     return result;
 }
+const compareStorageItem = async (browser, key, expected, options) => {
+    const actual = await browser.execute((storageKey) => {
+        return localStorage.getItem(storageKey);
+    }, key);
+    if (actual === null) {
+        return { actual, success: false };
+    }
+    const compareResult = compareTextOrOneOf(actual, expected, options);
+    return { actual, success: compareResult.success };
+};

package/lib/matchers/browser/toHaveTitle.js

@@ -1,5 +1,7 @@
-import { waitUntil, enhanceError, compareText } from '../../utils.js';
+import { waitUntil, enhanceError, compareTextOrOneOf } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
+import { executeBrowserCommand } from '../../util/executeBrowserCommand.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 export async function toHaveTitle(browser, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'title', verb = 'have', isNot, matcherName = 'toHaveTitle' } = this;
     await options.beforeAssertion?.({
@@ -7,12 +9,16 @@ export async function toHaveTitle(browser, expectedValue, options = DEFAULT_OPTI
         expectedValue,
         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 };
+    const expectedWithOptions = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
+    const { actual, success, subject, expected } = await waitUntil(async () => {
+        return await executeBrowserCommand({
+            browser,
+            isNot,
+            expectedValue: expectedWithOptions,
+            compare: (browser, expectedValue) => compareTitle(browser, expectedValue, options),
+        });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options);
+    const message = enhanceError(subject, expected, actual, { isNot, browserTargetType: 'window' }, verb, expectation, '', options);
     const result = {
         pass: success,
         message: () => message
@@ -25,3 +31,7 @@ export async function toHaveTitle(browser, expectedValue, options = DEFAULT_OPTI
     });
     return result;
 }
+const compareTitle = async (browser, expectedValue, options) => {
+    const actual = await browser.getTitle();
+    return compareTextOrOneOf(actual, expectedValue, options);
+};

package/lib/matchers/browser/toHaveUrl.js

@@ -1,5 +1,7 @@
-import { waitUntil, enhanceError, compareText } from '../../utils.js';
+import { waitUntil, enhanceError, compareTextOrOneOf } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
+import { executeBrowserCommand } from '../../util/executeBrowserCommand.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 export async function toHaveUrl(browser, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'url', verb = 'have', isNot, matcherName = 'toHaveUrl' } = this;
     await options.beforeAssertion?.({
@@ -7,12 +9,16 @@ export async function toHaveUrl(browser, expectedValue, options = DEFAULT_OPTION
         expectedValue,
         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 };
+    const expectedWithOptions = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
+    const { success: pass, actual, subject, expected } = await waitUntil(async () => {
+        return await executeBrowserCommand({
+            browser,
+            isNot,
+            expectedValue: expectedWithOptions,
+            compare: (browser, expectedValue) => compareUrl(browser, expectedValue, options),
+        });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options);
+    const message = enhanceError(subject, expected, actual, { isNot, browserTargetType: 'window' }, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message
@@ -25,3 +31,7 @@ export async function toHaveUrl(browser, expectedValue, options = DEFAULT_OPTION
     });
     return result;
 }
+const compareUrl = async (browser, expectedValue, options) => {
+    const actual = await browser.getUrl();
+    return compareTextOrOneOf(actual, expectedValue, options);
+};

package/lib/matchers/element/toHaveAttribute.js

@@ -20,7 +20,7 @@ async function conditionAttributeValueMatchWithExpected(el, attribute, expectedV
 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) => {
+    const { success: pass, actual: attr, subject: el, context: { isSome } = {}, expected: expectedValues } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -32,7 +32,7 @@ export async function toHaveAttributeAndValue(received, attribute, expectedValue
             strategy: 'NewStrictMultipleElements',
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const expected = wrapExpectedWithArray(el, attr, expectedValue);
+    const expected = expectedValues ?? wrapExpectedWithArray(el, attr, expectedValue);
     const message = enhanceError(el, expected, attr, { isNot, isSome }, verb, expectation, attribute, options);
     return {
         pass,

package/lib/matchers/element/toHaveChildren.js

@@ -1,6 +1,7 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
 import { executeCommandWithStrategy } from '../../util/executeCommand.js';
 import { isEmptyOrLegacyNumberOptions, validateNumberArrayAndExtractOptions } from '../../util/numberOptionsUtil.js';
+import { isMultiRemoteMatcher } from '../../util/multiRemoteUtils.js';
 import { enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 async function condition(el, expectedValue) {
     const children = await el.$$('./*').getElements();
@@ -15,7 +16,7 @@ async function condition(el, expectedValue) {
 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))) {
+    if (paramsCount > 1 && (expectedValueOrOptions === undefined || (isEmptyOrLegacyNumberOptions(expectedValueOrOptions) && !isMultiRemoteMatcher(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?.({
@@ -24,7 +25,7 @@ export async function toHaveChildren(received, expectedValueOrOptions, options =
         options,
     });
     const { numberMatcher: expectedNumber, commandOptions } = validateNumberArrayAndExtractOptions(expectedValueOrOptions, options, { supportDefaultAsGteThen1: true });
-    const { success: pass, actual: children, subject, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: children, subject, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             expectedValues: expectedNumber,
@@ -33,7 +34,7 @@ export async function toHaveChildren(received, expectedValueOrOptions, options =
             strategy: 'NewStrictMultipleElements',
         });
     }, isNot, { wait: commandOptions.wait, interval: commandOptions.interval });
-    const expectedArray = wrapExpectedWithArray(subject, children, expectedNumber);
+    const expectedArray = expected ?? wrapExpectedWithArray(subject, children, expectedNumber);
     const message = enhanceError(subject, expectedArray, children, { isNot, isSome }, verb, expectation, '', commandOptions);
     const result = {
         pass,

package/lib/matchers/element/toHaveComputedLabel.js

@@ -1,10 +1,10 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
 import { executeCommandWithStrategy } from '../../util/executeCommand.js';
-import { compareTextOrArray, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { compareTextOrOneOf, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 async function singleElementCompare(element, label, options) {
     const actualLabel = await element.getComputedLabel();
-    return compareTextOrArray(actualLabel, label, options);
+    return compareTextOrOneOf(actualLabel, label, options);
 }
 export async function toHaveComputedLabel(received, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'computed label', verb = 'have', isNot, matcherName = 'toHaveComputedLabel' } = this;
@@ -14,7 +14,7 @@ export async function toHaveComputedLabel(received, expectedValue, options = DEF
         options,
     });
     expectedValue = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
-    const { success: pass, actual: actualLabel, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualLabel, subject: el, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -25,7 +25,7 @@ export async function toHaveComputedLabel(received, expectedValue, options = DEF
             strictConfiguration: { allowArrayWithSingleElement: true }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError(el, wrapExpectedWithArray(el, actualLabel, expectedValue), actualLabel, { isNot, isSome }, verb, expectation, '', options);
+    const message = enhanceError(el, expected ?? wrapExpectedWithArray(el, actualLabel, expectedValue), actualLabel, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message

package/lib/matchers/element/toHaveComputedRole.js

@@ -1,10 +1,10 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
 import { executeCommandWithStrategy } from '../../util/executeCommand.js';
-import { compareTextOrArray, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { compareTextOrOneOf, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 async function singleElementCompare(element, role, options) {
     const actualRole = await element.getComputedRole();
-    return compareTextOrArray(actualRole, role, options);
+    return compareTextOrOneOf(actualRole, role, options);
 }
 export async function toHaveComputedRole(received, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'computed role', verb = 'have', isNot, matcherName = 'toHaveComputedRole' } = this;
@@ -14,7 +14,7 @@ export async function toHaveComputedRole(received, expectedValue, options = DEFA
         options,
     });
     expectedValue = buildWdioAsymmetricMatchersWithOptions(expectedValue, options);
-    const { success: pass, actual: actualRole, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualRole, subject: el, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -25,7 +25,7 @@ export async function toHaveComputedRole(received, expectedValue, options = DEFA
             strictConfiguration: { allowArrayWithSingleElement: true }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError(el, wrapExpectedWithArray(el, actualRole, expectedValue), actualRole, { isNot, isSome }, verb, expectation, '', options);
+    const message = enhanceError(el, expected ?? wrapExpectedWithArray(el, actualRole, expectedValue), actualRole, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message

package/lib/matchers/element/toHaveElementClass.js

@@ -1,6 +1,6 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
 import { executeCommandWithStrategy } from '../../util/executeCommand.js';
-import { compareText, compareTextOrArray, enhanceError, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { compareText, compareTextOrOneOf, enhanceError, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 async function singleElementCompare(el, attribute, value, options) {
     const actualClass = await el.getAttribute(attribute);
     if (value === undefined) {
@@ -14,7 +14,7 @@ async function singleElementCompare(el, attribute, value, options) {
     }
     const classes = actualClass.split(' ');
     const isValueInClasses = classes.some((clazz) => {
-        return compareTextOrArray(clazz, value, options).success;
+        return compareTextOrOneOf(clazz, value, options).success;
     });
     return {
         success: isValueInClasses,
@@ -32,7 +32,7 @@ export async function toHaveElementClass(received, expectedValue, options = DEFA
         options,
     });
     const attribute = 'class';
-    const { success: pass, actual: attr, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: attr, subject: el, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -43,7 +43,7 @@ export async function toHaveElementClass(received, expectedValue, options = DEFA
             strictConfiguration: { allowArrayWithSingleElement: true }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError(el, wrapExpectedWithArray(el, attr, expectedValue), attr, { isNot, isSome }, verb, expectation, '', options);
+    const message = enhanceError(el, expected ?? wrapExpectedWithArray(el, attr, expectedValue), attr, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message

package/lib/matchers/element/toHaveElementProperty.js

@@ -20,7 +20,7 @@ async function condition(el, property, expectedValue, options = DEFAULT_OPTIONS)
     return compareText(propertyValue.toString(), expectedValue, options);
 }
 export async function toHaveElementProperty(received, property, value, options = DEFAULT_OPTIONS) {
-    const { expectation = 'property', verb = 'have', isNot, matcherName = 'toHaveElementProperty' } = this;
+    const { expectation = 'property', verb = 'have', isNot, matcherName = 'toHaveElementProperty', allowObjectExpectedValue = true } = this;
     const paramsCount = arguments.length;
     if (value === undefined || value === null) {
         if (paramsCount > 2) {
@@ -34,7 +34,7 @@ export async function toHaveElementProperty(received, property, value, options =
         options,
     });
     value = buildWdioAsymmetricMatchersWithOptions(value, options);
-    const { success: pass, actual: actualProppertyValue, subject: elements, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualProppertyValue, subject: elements, context: { isSome } = {}, expected: expectedValues } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -44,10 +44,10 @@ export async function toHaveElementProperty(received, property, value, options =
             },
             context: { isNot, iteration },
             strategy: 'NewStrictMultipleElements',
-            strictConfiguration: { allowArrayWithSingleElement: false }
+            strictConfiguration: { allowArrayWithSingleElement: false, allowObjectExpectedValue }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const expected = wrapExpectedWithArray(elements, actualProppertyValue, value);
+    const expected = expectedValues ?? wrapExpectedWithArray(elements, actualProppertyValue, value);
     const message = enhanceError(elements, expected, actualProppertyValue, { isNot, isSome }, verb, expectation, property, options);
     const result = {
         pass,

package/lib/matchers/element/toHaveHTML.js

@@ -1,10 +1,10 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
-import { compareTextOrArray, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { compareTextOrOneOf, enhanceError, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { executeCommandWithStrategy } from '../../util/executeCommand.js';
 import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
 async function singleElementCompare(el, html, options) {
     const actualHTML = await el.getHTML(options);
-    return compareTextOrArray(actualHTML, html, options);
+    return compareTextOrOneOf(actualHTML, html, options);
 }
 export async function toHaveHTML(received, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'HTML', verb = 'have', isNot, matcherName = 'toHaveHTML' } = this;
@@ -14,7 +14,7 @@ export async function toHaveHTML(received, expectedValue, options = DEFAULT_OPTI
         expectedValue,
         options,
     });
-    const { success: pass, actual: actualHTML, subject: elements, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualHTML, subject: elements, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         const result = await executeCommandWithStrategy({
             unresolvedElements: received,
             supportsArrayContaining: true,
@@ -26,7 +26,7 @@ export async function toHaveHTML(received, expectedValue, options = DEFAULT_OPTI
         });
         return result;
     }, isNot, { wait: options.wait, interval: options.interval });
-    const expectedValues = wrapExpectedWithArray(elements, actualHTML, expectedValue);
+    const expectedValues = expected ?? wrapExpectedWithArray(elements, actualHTML, expectedValue);
     const message = enhanceError(elements, expectedValues, actualHTML, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,

package/lib/matchers/element/toHaveHeight.js

@@ -18,7 +18,7 @@ export async function toHaveHeight(received, expectedValue, options = DEFAULT_OP
         options,
     });
     const { numberMatcher: expectedNumber, commandOptions } = validateNumberArrayAndExtractOptions(expectedValue, options);
-    const { success: pass, actual: actualHeight, subject: elements, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualHeight, subject: elements, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             expectedValues: expectedNumber,
@@ -28,7 +28,7 @@ export async function toHaveHeight(received, expectedValue, options = DEFAULT_OP
             strictConfiguration: { allowArrayWithSingleElement: false }
         });
     }, isNot, { wait: commandOptions.wait, interval: commandOptions.interval });
-    const expectedValues = wrapExpectedWithArray(elements, actualHeight, expectedNumber);
+    const expectedValues = expected ?? wrapExpectedWithArray(elements, actualHeight, expectedNumber);
     const message = enhanceError(elements, expectedValues, actualHeight, { isNot, isSome }, verb, expectation, '', commandOptions);
     const result = {
         pass,

package/lib/matchers/element/toHaveSize.js

@@ -12,17 +12,17 @@ export async function toHaveSize(received, expectedValue, options = DEFAULT_OPTI
         expectedValue,
         options,
     });
-    const { success: pass, actual: actualSize, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualSize, subject: el, context: { isSome } = {}, expected } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             expectedValues: expectedValue,
             singleElementCompare: (element, expectedSize) => condition(element, expectedSize),
             context: { isNot, iteration },
             strategy: 'NewStrictMultipleElements',
-            strictConfiguration: { allowArrayWithSingleElement: false }
+            strictConfiguration: { allowArrayWithSingleElement: false, allowObjectExpectedValue: true }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const message = enhanceError(el, wrapExpectedWithArray(el, actualSize, expectedValue), actualSize, { isNot, isSome }, verb, expectation, '', options);
+    const message = enhanceError(el, expected ?? wrapExpectedWithArray(el, actualSize, expectedValue), actualSize, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,
         message: () => message

package/lib/matchers/element/toHaveStyle.js

@@ -14,17 +14,17 @@ export async function toHaveStyle(received, expectedValue, options = DEFAULT_OPT
         expectedValue,
         options,
     });
-    const { success: pass, actual: actualStyle, subject: el, context: { isSome } = {} } = await waitUntil(async (iteration) => {
+    const { success: pass, actual: actualStyle, subject: el, context: { isSome } = {}, expected: expectedValues } = await waitUntil(async (iteration) => {
         return await executeCommandWithStrategy({
             unresolvedElements: received,
             expectedValues: expectedValue,
             singleElementCompare: (element, expectedValues) => condition(element, expectedValues, options),
             context: { isNot, iteration },
             strategy: 'NewStrictMultipleElements',
-            strictConfiguration: { allowArrayWithSingleElement: false }
+            strictConfiguration: { allowArrayWithSingleElement: false, allowObjectExpectedValue: true }
         });
     }, isNot, { wait: options.wait, interval: options.interval });
-    const expected = wrapExpectedWithArray(el, actualStyle, expectedValue);
+    const expected = expectedValues ?? wrapExpectedWithArray(el, actualStyle, expectedValue);
     const message = enhanceError(el, expected, actualStyle, { isNot, isSome }, verb, expectation, '', options);
     const result = {
         pass,