expect-webdriverio 6.1.0 → 8.0.0-alpha.0

package/README.md

@@ -1,13 +1,18 @@
 # 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)
+> [!IMPORTANT]
+> This branch is v8, in development for WebdriverIO v10. Its docs are not released yet.
+> For the latest release (v7, WebdriverIO v9), see the [v7 README](https://github.com/webdriverio/expect-webdriverio/blob/v7/README.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 +26,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
 
@@ -30,12 +35,23 @@
 If you run your tests through the [WDIO testrunner](https://webdriver.io/docs/clioptions), no additional setup is needed. WebdriverIO initializes `expect-webdriverio` and makes `expect` available in the global scope so you can use it directly in your tests:
 
 ```js
-await expect($('button')).toBeDisplayed()
+await expect($('#submit')).toBeDisplayed()
 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 WebdriverIO environment variables are 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).
@@ -57,7 +73,7 @@ import { expect } from 'expect-webdriverio'
 
     await browser.url('https://webdriver.io')
 
-    const $button = await browser.$('button')
+    const $button = await browser.$('.DocSearch-Button')
     await expect($button).toBeDisplayed()
     
     await browser.deleteSession()
@@ -86,4 +102,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/jasmine-wdio-expect-async.d.ts

@@ -80,7 +80,7 @@ declare namespace ExpectWebdriverIO {
  * 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!
+// @ts-expect-error: the Jasmine `expect` is always loaded with this entry, so the two declarations conflict
 declare const expect: ExpectWebdriverIO.JasmineExpect
 declare namespace NodeJS {
     interface Global {

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/constants.js

@@ -1,14 +1,10 @@
 import { getGlobalSingleton } from './util/globalSingleton.js';
 function createSharedConstants() {
-    const DEFAULT_FEATURE_FLAGS = {
-        useToHaveTextStrictMultiElementsCompareStrategy: false
-    };
     const DEFAULT_OPTIONS = {
         wait: 2000,
         interval: 100,
         beforeAssertion: async () => { },
         afterAssertion: async () => { },
-        featureFlags: DEFAULT_FEATURE_FLAGS
     };
     const DEFAULT_OPTIONS_TO_BE_DISPLAYED = {
         ...DEFAULT_OPTIONS,
@@ -18,14 +14,12 @@ function createSharedConstants() {
         visibilityProperty: true
     };
     return {
-        DEFAULT_FEATURE_FLAGS,
         DEFAULT_OPTIONS,
         DEFAULT_OPTIONS_TO_BE_DISPLAYED,
         defaultOptionsList: [DEFAULT_OPTIONS, DEFAULT_OPTIONS_TO_BE_DISPLAYED]
     };
 }
 const shared = getGlobalSingleton('constants', createSharedConstants);
-export const DEFAULT_FEATURE_FLAGS = shared.DEFAULT_FEATURE_FLAGS;
 export const DEFAULT_OPTIONS = shared.DEFAULT_OPTIONS;
 export const DEFAULT_OPTIONS_TO_BE_DISPLAYED = shared.DEFAULT_OPTIONS_TO_BE_DISPLAYED;
 export const defaultOptionsList = shared.defaultOptionsList;

package/lib/index.js

@@ -4,10 +4,10 @@ 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 = {};
-    const matchers = new Map();
     const extend = expectLib.extend;
     expectLib.extend = (extendedMatchers) => {
         if (!extendedMatchers || typeof extendedMatchers !== 'object') {
@@ -15,7 +15,6 @@ function createSharedExpectSetup() {
         }
         Object.entries(extendedMatchers).forEach(([name, matcher]) => {
             wdioCustomMatchers[name] = matcher;
-            matchers.set(name, matcher);
         });
         return extend(extendedMatchers);
     };
@@ -28,6 +27,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)
@@ -44,11 +44,10 @@ function createSharedExpectSetup() {
         configurable: true,
         value: (testId) => SoftAssertService.getInstance().clearFailures(testId)
     });
-    return { wdioExpect, wdioCustomMatchers, matchers };
+    return { wdioExpect, wdioCustomMatchers };
 }
 const sharedExpectSetup = getGlobalSingleton('expect', createSharedExpectSetup);
 export const wdioCustomMatchers = sharedExpectSetup.wdioCustomMatchers;
-export const matchers = sharedExpectSetup.matchers;
 export const expect = sharedExpectSetup.wdioExpect;
 export const getDefaultOptions = () => DEFAULT_OPTIONS;
 export const setDefaultOptions = (options) => {
@@ -60,15 +59,6 @@ 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/jasmineUtils.js

@@ -11,10 +11,10 @@ function asymmetricMatch(a, b) {
     if (asymmetricA && asymmetricB) {
         return undefined;
     }
-    const matchersUtil = {
+    const matchersUtil = Object.assign([], {
         equals,
         contains: (actual, expected) => actual.some(value => equals(value, expected)),
-    };
+    });
     if (asymmetricA) {
         return a.asymmetricMatch(b, matchersUtil);
     }

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/asymmetrics/oneOf.js

@@ -1,4 +1,4 @@
-import { compareTextWithArray } from '../../utils.js';
+import { compareText } from '../../utils.js';
 import { WdioAsymmetricMatchers } from './asymmetricsUtils.js';
 const ONE_OF_TAG = 'expect-webdriverio.oneOf';
 const ONE_OF_SYMBOL = Symbol.for(ONE_OF_TAG);
@@ -19,7 +19,7 @@ export class OneOfMatcher extends WdioAsymmetricMatchers {
         else if (typeof actual !== 'string') {
             return false;
         }
-        return compareTextWithArray(actual, this.sample.filter(s => s !== null), this.options).success;
+        return this.sample.some((expected) => expected !== null && compareText(actual, expected, this.options).success);
     }
     withOptions(options) {
         return new OneOfMatcher(...this.sample).setOptions(options);

package/lib/matchers/browser/toHaveClipboardText.js

@@ -1,7 +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';
-const log = logger('expect-webdriverio');
+import { executeBrowserCommand } from '../../util/executeBrowserCommand.js';
+import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
+let permissionWarningLogged = false;
 export async function toHaveClipboardText(browser, expectedValue, options = DEFAULT_OPTIONS) {
     const { expectation = 'clipboard text', verb = 'have', isNot, matcherName = 'toHaveClipboardText' } = this;
     await options.beforeAssertion?.({
@@ -9,14 +10,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 +32,14 @@ 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) => {
+        if (!permissionWarningLogged) {
+            permissionWarningLogged = true;
+            console.warn(`expect-webdriverio: 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?.({
@@ -8,28 +10,17 @@ export async function toHaveLocalStorageItem(browser, key, expectedValue, option
         expectedValue: expectedValue ? [key, expectedValue] : key,
         options,
     });
-    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 (actual === null) {
-            return { actual, success: false, subject: browser };
-        }
-        const compareResult = compareText(actual, expected, options);
-        return { actual, success: compareResult.success, subject: browser };
+    const expected = expectedValue ?? expect.anything();
+    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 +33,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/toBeClickable.js

@@ -2,13 +2,14 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeClickable(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'clickable';
+    const { matcherName = 'toBeClickable' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeClickable',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isClickable(), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeClickable',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeDisabled.js

@@ -2,13 +2,14 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeDisabled(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'disabled';
+    const { matcherName = 'toBeDisabled' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeDisabled',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, async (el) => !await el.isEnabled(), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeDisabled',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeDisplayed.js

@@ -2,8 +2,9 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS_TO_BE_DISPLAYED } from '../../constants.js';
 export async function toBeDisplayed(received, options = DEFAULT_OPTIONS_TO_BE_DISPLAYED) {
     this.expectation = this.expectation || 'displayed';
+    const { matcherName = 'toBeDisplayed' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeDisplayed',
+        matcherName,
         options,
     });
     const { withinViewport, contentVisibilityAuto, opacityProperty, visibilityProperty, ...commandOptions } = { ...DEFAULT_OPTIONS_TO_BE_DISPLAYED, ...options };
@@ -14,7 +15,7 @@ export async function toBeDisplayed(received, options = DEFAULT_OPTIONS_TO_BE_DI
         visibilityProperty
     }), commandOptions);
     await options.afterAssertion?.({
-        matcherName: 'toBeDisplayed',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeDisplayedInViewport.js

@@ -2,13 +2,14 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeDisplayedInViewport(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'displayed in viewport';
+    const { matcherName = 'toBeDisplayedInViewport' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeDisplayedInViewport',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isDisplayed({ withinViewport: true }), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeDisplayedInViewport',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeEnabled.js

@@ -2,13 +2,14 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeEnabled(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'enabled';
+    const { matcherName = 'toBeEnabled' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeEnabled',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isEnabled(), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeEnabled',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeExisting.js

@@ -4,13 +4,14 @@ export async function toExist(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'exist';
     this.verb = this.verb || '';
     this.allowEmptyElements = true;
+    const { matcherName = 'toExist' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toExist',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isExisting(), options);
     await options.afterAssertion?.({
-        matcherName: 'toExist',
+        matcherName,
         options,
         result
     });
@@ -19,10 +20,12 @@ export async function toExist(received, options = DEFAULT_OPTIONS) {
 export function toBeExisting(el, options) {
     this.expectation = 'existing';
     this.verb = 'be';
+    this.matcherName ??= 'toBeExisting';
     return toExist.call(this, el, options);
 }
 export function toBePresent(el, options) {
     this.expectation = 'present';
     this.verb = 'be';
+    this.matcherName ??= 'toBePresent';
     return toExist.call(this, el, options);
 }

package/lib/matchers/element/toBeFocused.js

@@ -2,13 +2,14 @@ import { executeCommandBe } from '../../utils.js';
 import { DEFAULT_OPTIONS } from '../../constants.js';
 export async function toBeFocused(received, options = DEFAULT_OPTIONS) {
     this.expectation = this.expectation || 'focused';
+    const { matcherName = 'toBeFocused' } = this;
     await options.beforeAssertion?.({
-        matcherName: 'toBeFocused',
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isFocused(), options);
     await options.afterAssertion?.({
-        matcherName: 'toBeFocused',
+        matcherName,
         options,
         result
     });

package/lib/matchers/element/toBeSelected.js

@@ -2,14 +2,14 @@ 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';
+    const { matcherName = 'toBeSelected' } = this;
     await options.beforeAssertion?.({
-        matcherName: this.matcherName,
+        matcherName,
         options,
     });
     const result = await executeCommandBe.call(this, received, el => el?.isSelected(), options);
     await options.afterAssertion?.({
-        matcherName: this.matcherName,
+        matcherName,
         options,
         result
     });
@@ -17,7 +17,7 @@ export async function toBeSelected(received, options = DEFAULT_OPTIONS) {
 }
 export async function toBeChecked(received, options = DEFAULT_OPTIONS) {
     this.expectation = 'checked';
-    this.matcherName = 'toBeChecked';
+    this.matcherName ??= 'toBeChecked';
     const result = await toBeSelected.call(this, received, options);
     return result;
 }