expect-webdriverio 5.6.9 → 6.0.0

package/types/expect-webdriverio.d.ts

@@ -21,6 +21,9 @@ type ExpectLibAsyncExpectationResult = import('expect').AsyncExpectationResult
 type ExpectLibExpectationResult = import('expect').ExpectationResult
 type ExpectLibMatcherContext = import('expect').MatcherContext
 type MatchersObject = Parameters<typeof import('expect').expect.extend>[0]
+type ExpectLibAnything = ReturnType<typeof expect.any> | ReturnType<typeof expect.anything>
+
+type WdioSome<T> = import('../src/matchers/modifiers/some.js').SomeElementsWrapper<T>
 
 // Extracted from the expect library, this is the type of the matcher function used in the expect library.
 type RawMatcherFn<Context extends ExpectLibMatcherContext = ExpectLibMatcherContext> = {
@@ -29,48 +32,72 @@ type RawMatcherFn<Context extends ExpectLibMatcherContext = ExpectLibMatcherCont
 }
 
 /**
- * Real Promise and wdio chainable promise types.
+ * Indicates that a value can be either one T or an array of T.
  */
-type WdioPromiseLike<T = unknown> = PromiseLike<T> | ChainablePromiseElement | ChainablePromiseArray
-type WdioElementOrPromiseLike<T = unknown> = WdioPromiseLike<T> | WebdriverIO.Element
-type ElementPromise = Promise<WebdriverIO.Element>
-type ElementArrayPromise = Promise<WebdriverIO.ElementArray>
+type MaybeArray<T> = T | T[]
+
+type MaybeSome<T> = T | WdioSome<T>
 
 /**
- * Only Wdio real promise
+ * Indicates that a value can be either one T, an array of T with oneOf of T, or a oneOf matcher of T.
+ * For oneOf anything is excluded since it does not make any sense to have a oneOf with Anything matcher.
+ * TODO support number in oneOf until then we exclude it from the type to avoid confusion.
  */
-type WdioOnlyPromiseLike = ElementPromise | ElementArrayPromise | ChainablePromiseElement | ChainablePromiseArray
+type MaybeArrayOrOneOf<T> = T | (T | ExpectWebdriverIO.OneOfPartialMatcher<Exclude<T, ExpectWebdriverIO.PartialMatcherAnything | number>>)[] | ExpectWebdriverIO.OneOfPartialMatcher<Exclude<T, ExpectWebdriverIO.PartialMatcherAnything | number>>
 
 /**
- * Only wdio real promise or potential promise usage on element or element array or browser
+ * Indicates that a value can be either one T, or oneOf matchers of T.
+ * For oneOf anything is excluded since it does not make any sense to have a oneOf with Anything matcher.
  */
-type WdioOnlyMaybePromiseLike = ElementPromise | ElementArrayPromise | ChainablePromiseElement | ChainablePromiseArray | WebdriverIO.Browser | WebdriverIO.Element | WebdriverIO.ElementArray
+type MaybeOneOf<T> = T | ExpectWebdriverIO.OneOfPartialMatcher<Exclude<T, ExpectWebdriverIO.PartialMatcherAnything>>
 
 /**
- * Note we are defining Matchers outside of the namespace as done in jest library until we can make every typing work correctly.
+ * Real Promise and wdio chainable promise types.
+ */
+type WdioPromiseLike<T = unknown> = PromiseLike<T> | ChainablePromiseElement | ChainablePromiseArray
+type WdioElementOrPromiseLike<T = unknown> = WdioPromiseLike<T> | WebdriverIO.Element
+type ElementPromise = Promise<WebdriverIO.Element>
+type ElementArrayPromise = Promise<WebdriverIO.ElementArray>
+type ArrayOfElementsPromise = Promise<WebdriverIO.Element[]>
+
+/**
+ * Note we are defining types outside of the namespace as done in jest library until we can make every typing work correctly.
  * Once we have all types working, we could check to bring those back into the `ExpectWebdriverIO` namespace.
  */
 
 /**
  * Type helpers to be able to targets specific types mostly used in conjunctions with the Type of the `actual` parameter of the `expect`
  */
-type ElementOrArrayLike = ElementLike | ElementArrayLike
+type ElementOrMaybeSomeArrayLike = ElementLike | MaybeSomeElementArrayLike
 type ElementLike = WebdriverIO.Element | ChainablePromiseElement
-type ElementArrayLike = WebdriverIO.ElementArray | ChainablePromiseArray | WebdriverIO.Element[]
+type ElementArrayLike = WebdriverIO.ElementArray | ChainablePromiseArray | WebdriverIO.Element[] | ArrayOfElementsPromise | ElementArrayPromise
+type MaybeSomeElementArrayLike = MaybeSome<WebdriverIO.ElementArray | ChainablePromiseArray | WebdriverIO.Element[] | ArrayOfElementsPromise | ElementArrayPromise>
 type MockPromise = Promise<WebdriverIO.Mock>
 
 /**
  * Type helpers allowing to use the function when the expect(actual: T) is of the expected type T.
  */
 type FnWhenBrowser<ActualT, Fn> = ActualT extends WebdriverIO.Browser ? Fn : never
-type FnWhenElementOrArrayLike<ActualT, Fn> = ActualT extends ElementOrArrayLike ? Fn : never
-type FnWhenElementArrayLike<ActualT, Fn> = ActualT extends ElementArrayLike ? Fn : never
+/**
+ * Enables distinct function signatures for single elements versus arrays of elements.
+ *
+ * Note on Union Types: Passing a union type (e.g., `Element | Element[]`) may cause
+ * overload resolution failures, preventing the IDE and compiler from inferring the correct signature.
+ *
+ * Fix: If type inference issues arise, split the implementation into separate interfaces
+ */
+type FnWhenElementOrArrayLike<ActualT, FnElement, FnArray = FnElement> = ActualT extends MaybeSomeElementArrayLike ? FnArray : ActualT extends ElementLike ? FnElement: never
+type FnWhenElementArrayLike<ActualT, Fn> = ActualT extends MaybeSomeElementArrayLike ? Fn : never
 
 /**
  * Same as the other but because of Jasmine and it's expectAsync typing which does not force T to be a promise, then we need to account for `WebdriverIO.Mock
  */
 type FnWhenMock<ActualT, Fn> = ActualT extends MockPromise | WebdriverIO.Mock ? Fn : never
 
+interface WdioCustomAsymmetricMatchers {
+    oneOf(...values: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | null>): ExpectWebdriverIO.OneOfPartialMatcher<string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | null>
+}
+
 /**
  * Matchers dedicated to Wdio Browser.
  * When asserting on a browser's properties requiring to be awaited, the return type is a Promise.
@@ -95,11 +122,23 @@ interface WdioBrowserMatchers<_R, ActualT>{
     /**
      * `WebdriverIO.Browser` -> `execute`
      */
-    toHaveLocalStorageItem: FnWhenBrowser<ActualT, (
-        key: string,
-        expectedValue?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveLocalStorageItem: FnWhenBrowser<ActualT, {
+        /**
+         * @deprecated since v6.0.0, removed in v8.0.0. Use `expect.anything()` instead of `undefined` as expected value.
+         */
+        (
+            key: string,
+            expectedValue: undefined,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>,
+
+        (
+            key: string,
+            expectedValue?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | ExpectWebdriverIO.PartialMatcherAnything,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }
+    >
 }
 
 /**
@@ -112,10 +151,25 @@ interface WdioNetworkMatchers<_R, ActualT> {
      * Check that `WebdriverIO.Mock` was called
      */
     toBeRequested: FnWhenMock<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
     /**
      * Check that `WebdriverIO.Mock` was called N times
      */
-    toBeRequestedTimes: FnWhenMock<ActualT, (times: number | ExpectWebdriverIO.NumberOptions, options?: ExpectWebdriverIO.NumberOptions) => Promise<void>>
+    toBeRequestedTimes: FnWhenMock<ActualT, {
+        (
+            times: number | ExpectWebdriverIO.NumberMatcher,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>
+
+        /**
+        * @deprecated since v6.0.0, remove in v8.0.0. Use `NumberMatcher` & `CommandOptions` separately `toBeRequestedTimes(NumberMatcher, options)`.
+        */
+        (
+            times: ExpectWebdriverIO.NumberOptions,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+
+    }>
 
     /**
      * Check that `WebdriverIO.Mock` was called with the specific parameters
@@ -151,18 +205,94 @@ interface WdioElementOrArrayMatchers<_R, ActualT = unknown> {
     toBeExisting: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
 
     /**
-     * `WebdriverIO.Element` -> `getAttribute`
+     * `WebdriverIO.Element` -> `isClickable`
      */
-    toHaveAttribute: FnWhenElementOrArrayLike<ActualT, (
-        attribute: string, value?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions)
-    => Promise<void>>
+    toBeClickable: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    /**
+     * `WebdriverIO.Element` -> `!isEnabled`
+     */
+    toBeDisabled: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
 
     /**
+     * `WebdriverIO.Element` -> `isDisplayedInViewport`
+     */
+    toBeDisplayedInViewport: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    /**
+     * `WebdriverIO.Element` -> `isEnabled`
+     */
+    toBeEnabled: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    /**
+     * `WebdriverIO.Element` -> `isFocused`
+     */
+    toBeFocused: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    /**
+     * `WebdriverIO.Element` -> `isSelected`
+     */
+    toBeSelected: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    /**
+     * `WebdriverIO.Element` -> `isSelected`
+     */
+    toBeChecked: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+
+    toHaveAttribute: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        /**
+         * @deprecated since v6.0.0, remove in v8.0.0. Passing explicit `undefined` as a value is deprecated. Omit the second argument entirely or pass options instead: `toHaveAttribute(attribute, options)`.
+         */
+        (
+            attribute: string,
+            value: undefined,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+
+        /** Check ONLY for the presence of the attribute (and optional configuration options) */
+        (
+            attribute: string,
+        ): Promise<void>;
+
+        /** Assert both attribute name AND a specific expected value */
+        (
+            attribute: string,
+            value: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>> | ExpectWebdriverIO.PartialMatcherAnything,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+    }, {
+        /** Elements $$() API */
+        /**
+         * @deprecated Not supported
+         */
+        (
+            attribute: string,
+            value: undefined,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+
+        /** Check ONLY for the presence of the attribute (and optional configuration options) */
+        (
+            attribute: string,
+        ): Promise<void>;
+
+        /** Assert both attribute name AND a specific expected value */
+        (
+            attribute: string,
+            value: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | ExpectWebdriverIO.PartialMatcherAnything>,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+    }
+    >
+
+    /**
+     * @deprecated since v6.0.0, removed in v8.0.0. Use `toHaveAttribute` instead.
      * `WebdriverIO.Element` -> `getAttribute`
      */
     toHaveAttr: FnWhenElementOrArrayLike<ActualT, (
-        attribute: string, value?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
+        attribute: string,
+        value?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
         options?: ExpectWebdriverIO.StringOptions
     ) => Promise<void>>
 
@@ -191,106 +321,214 @@ interface WdioElementOrArrayMatchers<_R, ActualT = unknown> {
      * await expect(element).toHaveElementClass(['btn', 'btn-large']);
      * ```
      */
-    toHaveElementClass: FnWhenElementOrArrayLike<ActualT, (
-        className: string | RegExp | Array<string | RegExp> | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveElementClass: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            className: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) :Promise<void>
+        /** @deprecated use `expect.oneOf()` instead of an array */
+        (
+            className: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) :Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            className: MaybeArray<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) :Promise<void>
+    }>
 
-    /**
-     * `WebdriverIO.Element` -> `getProperty`
-     */
-    toHaveElementProperty: FnWhenElementOrArrayLike<
-        ActualT,
+    toHaveElementProperty: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        /**
+         * Allow to check ONLY for the presence of the property
+         * Use `toHaveElementProperty(property, expect.anything(), options)` to check for the presence of the property with options.
+         */
         (
             property: string,
-            value?: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | null,
-            options?: ExpectWebdriverIO.StringOptions,
-        ) => Promise<void>
-    >
+        ): Promise<void>;
 
-    /**
-     * `WebdriverIO.Element` -> `getProperty` value
-     */
-    toHaveValue: FnWhenElementOrArrayLike<ActualT, (
-        value: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+        /**
+         * @deprecated since v6.0.0, removed in v8.0.0. Passing explicit `undefined` or `null` as a value is deprecated.
+         * Omit the second argument entirely or use expect.anything() with options: `toHaveElementProperty(property, expect.anything(), options)`.
+         */
+        (
+            property: string,
+            value: undefined | null, // Use expect.any(type) or expect.anything() instead of undefined or null
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
 
-    /**
-     * `WebdriverIO.Element` -> `isClickable`
-     */
-    toBeClickable: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+        /** Assert both property name AND a specific expected value */
+        (
+            property: string,
+            // TODO support `oneOf` for number!
+            value: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | ExpectWebdriverIO.PartialMatcherAnything> | number,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+    }, {
+        /** Elements $$() API */
+        /**
+         * Allow to check ONLY for the presence of the property
+         * Use `toHaveElementProperty(property, expect.anything(), options)` to check for the presence of the property with options.
+         */
+        (
+            property: string,
+        ): Promise<void>;
 
-    /**
-     * `WebdriverIO.Element` -> `!isEnabled`
-     */
-    toBeDisabled: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+        /**
+         * @deprecated Not supported
+         * Use `expect.anything()` or `[expect.anything()] as value` to check for the presence of the property with options.
+         */
+        (
+            property: string,
+            propertyValue: undefined | null, // Use expect.any(type) or expect.anything() instead of undefined or null
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<never>;
 
-    /**
-     * `WebdriverIO.Element` -> `isDisplayedInViewport`
-     */
-    toBeDisplayedInViewport: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+        /** Assert both property name AND a specific expected value */
+        (
+            property: string,
+            value: MaybeArrayOrOneOf<string | number | RegExp | ExpectWebdriverIO.PartialMatcher<string> | ExpectWebdriverIO.PartialMatcherAnything | null>,
+            options?: ExpectWebdriverIO.StringOptions
+        ): Promise<void>;
+    }>
 
     /**
-     * `WebdriverIO.Element` -> `isEnabled`
+     * `WebdriverIO.Element` -> `getProperty` value
      */
-    toBeEnabled: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+    toHaveValue: FnWhenElementOrArrayLike<ActualT,
+        /** Element $() API */
+        (
 
-    /**
-     * `WebdriverIO.Element` -> `isFocused`
-     */
-    toBeFocused: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+            value: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) => Promise<void>,
 
-    /**
-     * `WebdriverIO.Element` -> `isSelected`
-     */
-    toBeSelected: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+        /** Elements $$() API */
+        (
 
-    /**
-     * `WebdriverIO.Element` -> `isSelected`
-     */
-    toBeChecked: FnWhenElementOrArrayLike<ActualT, (options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+            value: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) => Promise<void>
+    >
 
     /**
      * `WebdriverIO.Element` -> `$$('./*').length`
-     * supports less / greater then or equals to be passed in options
+     * Supports less / greater then or equals to be passed in value as a NumberMatcher.
      */
-    toHaveChildren: FnWhenElementOrArrayLike<ActualT, (
-        size?: number | ExpectWebdriverIO.NumberOptions,
-        options?: ExpectWebdriverIO.NumberOptions
-    ) => Promise<void>>
+    toHaveChildren: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        /**
+         * Verifies that the element has children.
+         * Same as `expect(el).toHaveChildren({ gte: 1 })` or `expect(el).toHaveChildren({ gte: 1 }, options)`.
+         */
+        (): Promise<void>;
+        /**
+         * @deprecated since 6.0.0, remove in v8.0.0.
+         * Passing explicit `undefined` or `{ wait : 1 }` (NumberOptions) as a value is deprecated.
+         * Use options with `toHaveChildren({ gte: 1 }, options)`.
+         */
+        (
+            expectedValue: undefined, // {} also deprecated but we cannot use it as a type because it would match any object
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+
+        /**
+         * When called with an expected child count or number matcher.
+         */
+        (
+            expectedValue: number | ExpectWebdriverIO.NumberMatcher,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+
+        /**
+         * @deprecated since 6.0.0, remove in v8.0.0.
+         * NumberOptions is no longer supported. Use `expect(el).toHaveChildren(numberMatcher, options)` instead.
+         * Instead of `expect(el).toHaveChildren({ wait: 1 })` use `expect(el).toHaveChildren({ gte: 1 }, { wait: 1 })`.
+         */
+        (
+            expectedValue: ExpectWebdriverIO.NumberOptions,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+    }, {
+        /** Element $$() API */
+        /**
+         * Verifies that the element has children.
+         * Same as `expect(el).toHaveChildren({ gte: 1 })` or `expect(el).toHaveChildren({ gte: 1 }, options)`.
+         */
+        (): Promise<void>;
+
+        /**
+         * @deprecated Not supported
+         * NumberOptions is no longer supported. Use `expect(el).toHaveChildren(numberMatcher, options)` instead.
+         * Instead of `expect(el).toHaveChildren({ wait: 1 })` use `expect(el).toHaveChildren({ gte: 1 }, { wait: 1 })`.
+         */
+        (
+            expectedValue: undefined,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+
+        /**
+         * When called with an expected child count or number matcher.
+         */
+        (
+            expectedValue: MaybeArray<number | ExpectWebdriverIO.NumberMatcher>,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>;
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getAttribute` href
      */
-    toHaveHref: FnWhenElementOrArrayLike<ActualT, (
-        href: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveHref: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            href: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            href: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getAttribute` href
      */
-    toHaveLink: FnWhenElementOrArrayLike<ActualT, (
-        href: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveLink: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            href: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            href: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getProperty` value
      */
-    toHaveId: FnWhenElementOrArrayLike<ActualT, (
-        id: string | RegExp | ExpectWebdriverIO.PartialMatcher<string>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveId: FnWhenElementOrArrayLike<ActualT,
+        /** Element $() API */
+        (
+            id: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) => Promise<void>,
 
-    /**
-     * `WebdriverIO.Element` -> `getSize` value
-     */
-    toHaveSize: FnWhenElementOrArrayLike<ActualT, (
-        size: { height: number; width: number },
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+        /** Elements $$() API */
+        (
+            id: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) => Promise<void>
+    >
 
     /**
      * `WebdriverIO.Element` -> `getText`
@@ -311,66 +549,191 @@ interface WdioElementOrArrayMatchers<_R, ActualT = unknown> {
      * await expect(elem).toHaveText(['Coffee', 'Tea', 'Milk'])
      * ```
      */
-    toHaveText: FnWhenElementOrArrayLike<ActualT, (
-        text: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveText: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            text: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+        /** @deprecated Use `expect.oneOf()` instead. */
+        (
+            text: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            text: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getHTML`
      * Element's html equals the html provided
      */
-    toHaveHTML: FnWhenElementOrArrayLike<ActualT, (
-        html: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | Array<string | RegExp>,
-        options?: ExpectWebdriverIO.HTMLOptions
-    ) => Promise<void>>
+    toHaveHTML: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            text: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.HTMLOptions
+        ) : Promise<void>
+        /** @deprecated to replace by oneOf() or anyOf() when available */
+        (
+            text: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.HTMLOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            text: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | ExpectWebdriverIO.OneOfPartialMatcher<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>>,
+            options?: ExpectWebdriverIO.HTMLOptions
+        ): Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getComputedLabel`
      * Element's computed label equals the computed label provided
      */
-    toHaveComputedLabel: FnWhenElementOrArrayLike<ActualT, (
-        computedLabel: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | Array<string | RegExp>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveComputedLabel: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            computedLabel: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+
+        /** @deprecated use `expect.oneOf()` instead of an array */
+        (
+            computedLabel: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            computedLabel: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getComputedRole`
      * Element's computed role equals the computed role provided
      */
-    toHaveComputedRole: FnWhenElementOrArrayLike<ActualT, (
-        computedRole: string | RegExp | ExpectWebdriverIO.PartialMatcher<string> | Array<string | RegExp>,
-        options?: ExpectWebdriverIO.StringOptions
-    ) => Promise<void>>
+    toHaveComputedRole: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            computedRole: MaybeOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+
+        /** @deprecated use `expect.oneOf()` instead of an array */
+        (
+            computedRole: Array<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            computedRole: MaybeArrayOrOneOf<string | RegExp | ExpectWebdriverIO.PartialMatcher<string>>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getSize('width')`
      * Element's width equals the width provided
      */
-    toHaveWidth: FnWhenElementOrArrayLike<ActualT, (width: number, options?: ExpectWebdriverIO.CommandOptions) => Promise<void>>
+    toHaveWidth: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            width: number | ExpectWebdriverIO.NumberMatcher,
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>,
+
+        /**
+         * @deprecated since v6.0.0, remove in v8.0.0. Use `toHaveWidth` with number | NumberMatcher instead. This matcher will be removed in version 8.0.0.
+         */
+        (
+            size: ExpectWebdriverIO.NumberOptions,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>,
+    }, {
+        /** Elements $$() API */
+        (
+            width: MaybeArray<number | ExpectWebdriverIO.NumberMatcher>,
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>
+    }>
 
     /**
-     * `WebdriverIO.Element` -> `getSize('height')` or `getSize()`
-     * Checks if the element's height equals the given number, or its size equals the given object.
+     * `WebdriverIO.Element` -> `getSize('height')`
+     * Checks if the element's height equals the given number.
      *
-     * @param heightOrSize - Either a number (height) or an object with height and width.
+     * @param height - The expected height of the element.
      * @param options - Optional command options.
      *
      * **Usage Example:**
      * ```js
      * await expect(element).toHaveHeight(42)
-     * await expect(element).toHaveHeight({ height: 42, width: 42 })
      * ```
      */
-    toHaveHeight: FnWhenElementOrArrayLike<ActualT, (
-        heightOrSize: number | { height: number; width: number },
-        options?: ExpectWebdriverIO.CommandOptions
-    ) => Promise<void>>
+    toHaveHeight: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            height: number | ExpectWebdriverIO.NumberMatcher,
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>
+
+        /**
+         * @deprecated since v6.0.0, will be removed in version v8.0.0. Use `toHaveHeight` with number | NumberMatcher instead.
+         */
+        (
+            size: ExpectWebdriverIO.NumberOptions,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>,
+    }, {
+        /** Elements $$() API */
+        (
+            height: MaybeArray<number | ExpectWebdriverIO.NumberMatcher>,
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>
+    }>
+
+    /**
+     * `WebdriverIO.Element` -> `getSize` value
+     * Element's size equals the size provided
+     * // TODO: add support for NumberMatcher on width and height
+     */
+    toHaveSize: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            size: { height: number; width: number },
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            size: MaybeArray<{ height: number; width: number }>,
+            options?: ExpectWebdriverIO.CommandOptions
+        ) : Promise<void>
+    }>
 
     /**
      * `WebdriverIO.Element` -> `getAttribute("style")`
      */
-    toHaveStyle: FnWhenElementOrArrayLike<ActualT, (style: { [key: string]: string }, options?: ExpectWebdriverIO.StringOptions) => Promise<void>>
+    toHaveStyle: FnWhenElementOrArrayLike<ActualT, {
+        /** Element $() API */
+        (
+            style: { [key: string]: string },
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }, {
+        /** Elements $$() API */
+        (
+            style: MaybeArray<{ [key: string]: string }>,
+            options?: ExpectWebdriverIO.StringOptions
+        ) : Promise<void>
+    }>
 }
 
 /**
@@ -379,15 +742,26 @@ interface WdioElementOrArrayMatchers<_R, ActualT = unknown> {
  * When actual is not of WebdriverIO.ElementArray nor ChainableElementArray, the return type is never, so the function cannot be used.
  */
 interface WdioElementArrayOnlyMatchers<_R, ActualT = unknown> {
-    // ===== $$ only =====
+    // ===== Elements $$() only =====
     /**
      * `WebdriverIO.ElementArray` -> `$$('...').length`
-     * supports less / greater then or equals to be passed in options
+     * The element arrays is refreshed/mutated until the size equals the size provided or matches the number matcher.
+     *
      */
-    toBeElementsArrayOfSize: FnWhenElementArrayLike<ActualT, (
-        size: number | ExpectWebdriverIO.NumberOptions,
-        options?: ExpectWebdriverIO.NumberOptions
-    ) => Promise<void> & Promise<WebdriverIO.ElementArray>>
+    toBeElementsArrayOfSize: FnWhenElementArrayLike<ActualT, {
+        (
+            size: number | ExpectWebdriverIO.NumberMatcher,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>,
+
+        /**
+         * @deprecated since v6.0.0, remove in v8.0.0. Use `toBeElementsArrayOfSize` with number | NumberMatcher instead. This matcher will be removed in version 8.0.0.
+         */
+        (
+            size: ExpectWebdriverIO.NumberOptions,
+            options?: ExpectWebdriverIO.CommandOptions
+        ): Promise<void>,
+    }>
 }
 
 /**
@@ -468,8 +842,49 @@ type WdioAsymmetricMatchers = ExpectLibAsymmetricMatchers
 type WdioAsymmetricMatcher<R> = ExpectWebdriverIO.PartialMatcher<R> & {
     // Overwrite protected properties of expect.AsymmetricMatcher to access them
     sample: R;
+    inverse?: boolean;
+}
+
+type WdioOneOfAsymmetricMatcher<R> = ExpectWebdriverIO.PartialMatcher<R> & {
+    sample: [R];
 }
 
+type JasmineBaseAsymmetricMatcher = {
+    jasmineToString(): string;
+    asymmetricMatch(other: unknown): boolean;
+}
+
+/**
+ * Jasmine asymetric matcher does not always use sample, some use expected. `any` uses even `expectedObject`
+ * @see https://github.com/jasmine/jasmine/tree/v5.13.0/src/core/asymmetric_equality
+ */
+type JasmineAsymmetricMatcher<R> = JasmineBaseAsymmetricMatcher & ({
+    expected: R;
+} | {
+    sample: R;
+} | {
+    regexp: string | RegExp;
+} | {
+    expectedObject: R;
+} | {} // jasmine.anything()
+)
+
+type JasmineStringContainingAsymmetricMatcher<R> = JasmineBaseAsymmetricMatcher & {
+    expected: R;
+}
+
+type JasmineStringMatchingAsymmetricMatcher<R extends string | RegExp> = JasmineBaseAsymmetricMatcher & {
+    regexp: R;
+}
+
+type JasmineStringAsymmetricMatcher<R extends string | RegExp> = JasmineStringContainingAsymmetricMatcher<R> | JasmineStringMatchingAsymmetricMatcher<R>
+
+type JasmineAnythingAsymmetricMatcher = JasmineBaseAsymmetricMatcher & {}
+
+type AsymmetricMatcher<R> = WdioAsymmetricMatcher<R> | JasmineStringContainingAsymmetricMatcher<R> | (R extends string | RegExp ? JasmineStringMatchingAsymmetricMatcher<R> : never) | JasmineAsymmetricMatcher<R>
+
+type WdioAnythingAsymmetricMatcher = ExpectLibAnything | JasmineAnythingAsymmetricMatcher
+
 declare namespace ExpectWebdriverIO {
     /**
      * When importing expect from 'expect-webdriverio', instead of using globals this is the one used.
@@ -480,9 +895,22 @@ declare namespace ExpectWebdriverIO {
     /**
      * Used by the webdriverio main project to configure the matchers in the runner.
      */
+    function setDefaultOptions(options: DefaultOptions): void
+    /** @deprecated since v6.0.0, use setDefaultOptions instead, will be removed in v8.0.0 */
     function setOptions(options: DefaultOptions): void
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    function getConfig(): any
+
+    /**
+     * Allow to enable some new features in the expect-webdriverio library.
+     * @param flags
+     */
+    function setFeatureFlags(flags: FeatureFlags): void
+
+    /**
+     * Get the default options set by the user.
+     */
+    function getDefaultOptions(): DefaultOptions
+    /** @deprecated since v6.0.0, use getDefaultOptions instead, will be removed in v8.0.0 */
+    function getConfig(): DefaultOptions
 
     /**
      * The below block are overloaded types from the expect library.
@@ -512,17 +940,23 @@ declare namespace ExpectWebdriverIO {
         <T = unknown>(actual: T): T extends PromiseLike<unknown> ? ExpectWebdriverIO.MatchersAndInverse<void, T> & ExpectWebdriverIO.PromiseMatchers<T> : ExpectWebdriverIO.MatchersAndInverse<void, T>;
     }
 
-    interface Matchers<R extends void | Promise<void>, T> extends WdioMatchers<R, T> {}
+    /**
+     * Matchers defining the custom wdio matchers.
+     * Matchers is documented as the interface to augment to add other custom matchers.
+     *
+     * We MUST NOT have Jest's expect Lib matchers here, so that we can use it with Jasmine augmentation as well.
+     */
+    interface Matchers<R extends void | Promise<void>, T> extends WdioCustomMatchers<R, T> {}
 
-    interface AsymmetricMatchers extends WdioAsymmetricMatchers {}
+    interface AsymmetricMatchers extends WdioAsymmetricMatchers, WdioCustomAsymmetricMatchers {}
 
-    interface InverseAsymmetricMatchers extends Omit<ExpectWebdriverIO.AsymmetricMatchers, 'anything' | 'any'> {}
+    interface InverseAsymmetricMatchers extends Omit<ExpectWebdriverIO.AsymmetricMatchers, 'anything' | 'any' | 'oneOf'> {}
 
     /**
      * End of block overloading types from the expect library.
      */
 
-    type MatchersAndInverse<R extends void | Promise<void>, ActualT> = ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibInverse<ExpectWebdriverIO.Matchers<R, ActualT>>
+    type MatchersAndInverse<R extends void | Promise<void>, ActualT> = (ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibMatchers<R, ActualT>) & ExpectLibInverse<ExpectWebdriverIO.Matchers<R, ActualT> & ExpectLibMatchers<R, ActualT>>
 
     /**
      * Take from expect library
@@ -595,7 +1029,7 @@ declare namespace ExpectWebdriverIO {
     const wdioCustomMatchers: MatchersObject
 
     /**
-     * @deprecated use `wdioCustomMatchers` instead
+     * @deprecated since 5.6.9 use `wdioCustomMatchers` instead, will be removed in v8.0.0?
      */
     const matchers: Map<string, RawMatcherFn>
 
@@ -625,6 +1059,16 @@ declare namespace ExpectWebdriverIO {
         result: AssertionResult
     }
 
+    interface FeatureFlags {
+        /**
+             * Feature flag to enable the new multi-elements comparison for `toHaveText` matcher, allowing to keep the current behavior without breaking changes.
+             * When enabled, the matcher will compare the text of multiple elements in an indexed exact match manner, rather than using the array as a possible match for any of the elements.
+             *
+             * Will be removed in v6.0.0, as the new behavior will become the default and only behavior for `toHaveText` matcher.
+             */
+        useToHaveTextStrictMultiElementsCompareStrategy?: boolean
+    }
+
     interface DefaultOptions {
         /**
          * time in ms to wait for expectation to succeed. Default: 3000
@@ -645,6 +1089,8 @@ declare namespace ExpectWebdriverIO {
          * hook that gets executed after each assertion, it contains the result of the assertion
          */
         afterAssertion?: (params: AfterAssertionHookParams) => Promise<void>
+
+        featureFlags?: FeatureFlags
     }
 
     interface CommandOptions extends DefaultOptions {
@@ -703,16 +1149,23 @@ declare namespace ExpectWebdriverIO {
         replace?: [string | RegExp, string | Function] | Array<[string | RegExp, string | Function]>
 
         /**
-         * might be helpful to force converting property value to string
+         * convert element's property value to string
          */
         asString?: boolean
     }
 
+    /**
+     * @deprecated since v6.0.0, remove in v8.0.0. Use `NumberMatcher` & `CommandOptions` as separate parameters instead.
+     * @see NumberMatcher
+     * @see CommandOptions
+     */
     interface NumberOptions extends CommandOptions {
+
         /**
          * equals
          */
         eq?: number
+
         /**
          * less than or equals
          */
@@ -751,6 +1204,22 @@ declare namespace ExpectWebdriverIO {
         visibilityProperty?: boolean
     }
 
+    interface NumberMatcher {
+        /**
+         * equals
+         */
+        eq?: number
+        /**
+         * less than or equals
+         */
+        lte?: number
+
+        /**
+         * greater than or equals
+         */
+        gte?: number
+    }
+
     type RequestedWith = {
         url?: string | ExpectWebdriverIO.PartialMatcher<string>| ((url: string) => boolean)
         method?: string | Array<string>
@@ -785,6 +1254,29 @@ declare namespace ExpectWebdriverIO {
      * Some properties are omitted for the type check to work correctly.
      */
     type PartialMatcher<T> = Omit<ExpectLibAsymmetricMatcher<T>, 'sample' | 'inverse' | '$$typeof'>
+
+    /**
+     * Allow to match any defined value or any defined value of a given type and simply validate a value exists.
+     */
+    type PartialMatcherAnything = ExpectLibAnything | JasmineAnythingAsymmetricMatcher
+
+    /**
+     * Allow to match one of the specified value.
+     */
+    type OneOfPartialMatcher<T> = ExpectWebdriverIO.PartialMatcher<T[]>
+
+    /**
+     * Quantifier modifier. Wraps a `$$()` result so that the matcher passes
+     * when at least one element satisfies the condition (∃ semantics).
+     *
+     * @example
+     * await expect(some($$('.items'))).toBeDisplayed()
+     * await expect(some($$('.items'))).not.toBeDisplayed() // at least one is NOT displayed
+     * await expect(some($$('.items'))).toHaveText('foo')
+     */
+    function some<T extends ElementArrayLike>(
+        elements: T
+    ): WdioSome<T>
 }
 
 declare module 'expect-webdriverio' {