Reivew waitUntil and fixes multiple not tests

Code review + make Be/Browser matchers test type safe

Mock default option to speed up tests

Better way to speed-up tests

Add tests around default options

Fix $$ mock

Ensure matcherName is corectly passed + toExists test correctly

Reinforce and test `isElementArray`

Add missing coverage for `executeCommand`

Migrate test of toBeArraySize + add more robust util

- Migrate + add coverage for `toBeElementsArrayOfSize` matcher
- Fix wait not correctly considered in `toBeElementsArrayOfSize`
- Reinforce isElementArray and similar + add more coverage
- By default for `DEFAULT_OPTIONS`use a non 0 wait time
- Fix global mock missing element.parent

Add note on element not found + add potential case to support

Add edge cases

Add alternative with parametrized in aPI doc
Gracefully fails on invalid element types

With selector fixed add back Promise of elements case

Code review

Code review + add unsupported type to toBe matchers

Code review

Add unsupported type test coverage

Code review + add coverage + better awaitElement mechanism

Add asymmetric integration tests

Code review & coverage

Add more tests for toHaveAttribute

Array of array is not supported so adapting test for today

Review some TODOs

Support better failure msg for multiple results in toBe Matchers

Properly handle failure colored message for `.no` for multiple elementst

Properly support equal for NumberOptions and .not multiple values failure

Code review

Review coverage for formatMessage + numberOptions

Fix 0 not stringily correctly

Add .not elements integration tests

Add coverage

Review docs

Finalize `executeCommandBe` tests

Increase coverage

More stable tests

test

Add `toHaveText` non-indexed + non-strict length legacy behavior

Test more unknown expected type, but maybe some bug?

Use supported type instead of unknown for `toHaveElementProperty`

Add case of element not found which throws for single element

- Note that for multiple element so ElementArray, there is no exception but an empty array

Add missing element case and index out of bound from `$()[x]`

Review refresh test after rebase

- Ensure we return non modified args elements

Author: dprevost-LMI

docs/API.md

@@ -256,9 +256,11 @@ await expect(browser).toHaveClipboardText(expect.stringContaining('clipboard tex
 
 ### Multiples Elements Support
 
-All element matchers work with arrays of elements (e.g., `$$()` results).
-- In short, matchers is applied on each elements and must pass for the entire assertion to succeed, so if one fails, the assertions fails.
-- See [MutipleElements.md](MultipleElements.md) for more information.
+All element matchers support arrays (e.g., `$$()` results).
+
+- Each element must pass the matcher for the assertion to succeed; if any fail, the assertion fails.
+   - `toHaveText` differ and keep it's legacy behavior.
+- See [MultipleElements.md](MultipleElements.md) for details.
 
 #### Usage
 
@@ -270,16 +272,20 @@ await expect(await $$('#someElem')).toBeDisplayed()
 ```ts
 const elements = await $$('#someElem')
 
-// Single expected value compare with each element's value
+// Single value: checked against every element
 await expect(elements).toHaveAttribute('class', 'form-control')
 
-// Multiple expected values for exactly 2 elements having exactly 'control1' & 'control2' as values
+// Array: each value checked at corresponding element index (must match length)
 await expect(elements).toHaveAttribute('class', ['control1', 'control2'])
 
-// Multiple expected values for exactly 2 elements but with more flexibility for the first element's value
+// Use asymmetric matchers for flexible matching
 await expect(elements).toHaveAttribute('class', [expect.stringContaining('control1'), 'control2'])
 
-// Filtered array also works
+// Use RegEx `i` for case insensitive
+await expect(elements).toHaveAttribute('class', [/'Control1'/i, 'control2'])
+
+
+// Works with filtered arrays too
 await expect($$('#someElem').filter(el => el.isDisplayed())).toHaveAttribute('class', ['control1', 'control2'])
 ```
 

docs/MultipleElements.md

@@ -1,24 +1,42 @@
 # Multiple Elements Support
 
-All element matchers work with arrays of elements (e.g., `$$()` results).
-- **Strict Length Matching**: If you provide an array of expected values, the number of values must match the number of elements found. A failure occurs if the lengths differ.
-- **Index-based Matching**: When using an array of expected values, each element is compared to the value at the corresponding index.
-- **Single Value Matching**: If you provide a single expected value, it is compared against *every* element in the array.
-- **Asymmetric Matchers**: Asymmetric matchers can be used within the expected values array for more matching flexibility.
-- If no elements exist, a failure occurs (except with `toBeElementsArrayOfSize`).
-- Options like `StringOptions` or `HTMLOptions` apply to the entire array (except `NumberOptions`).
-- The assertion passes only if **all** elements match the expected value(s).
-- Using `.not` applies the negation to each element (e.g., *all* elements must *not* display).
+Matchers element array support (e.g., `$$()`):
 
-**Note:** Strict length matching does not apply on `toHaveText` to preserve existing behavior.
+- **Strict Index-based Matching**: If an array of expected values is provided, it must match the elements' count; each value is checked at its index.
+- If a single value is provided, every element is compared to it.
+- Asymmetric matchers (e.g., `expect.stringContaining`) work within expected value arrays.
+- An error is thrown if no elements are found (except with `toBeElementsArrayOfSize`).
+- Options like `StringOptions` or `HTMLOptions` apply to the whole array; `NumberOptions` behaves like any expected provided value.
+- The assertion passes only if **all** elements match.
+- Using `.not` means all elements must **not** match.
+
+**Note:** Strict Index-based matching does not apply to `toHaveText`, since an existing behavior was already in placed.
 
 ## Limitations
-- An alternative to using `StringOptions` (like `ignoreCase` or `containing`) for a single expected value is to use RegEx (`/MyExample/i`) or Asymmetric Matchers (`expect.stringContaining('Example')`).
-- Passing an array of "containing" values, as previously supported by `toHaveText`, is deprecated and not supported for other matchers.
+- Instead of `StringOptions` for a single expected value, use RegExp or asymmetric matchers.
+  - For `ignoreCase` use RegEx (`/MyExample/i`) 
+  - For `containing` use Asymmetric Matchers (`expect.stringContaining('Example')`)
+- Passing an array of "containing" values is deprecated and not supported outside `toHaveText`.
 
 ## Supported types
-
-Any of the below element types can be passed to `expect`:
+You can pass any of these element types to `expect`:
 - `ChainablePromiseArray` (the non-awaited case)
 - `ElementArray` (the awaited case)
 - `Element[]` (the filtered case)
+
+## Alternative
+
+For more granular or explicit per-element validation, use a parameterized test of your framework.
+Example in Mocha:
+```ts
+    describe('Element at index of `$$`', function () {
+        [ { expectedText: 'one', index: 0 },
+            { expectedText: 'two', index: 2 },
+            { expectedText: 'four', index: 4 },
+        ].forEach(function ( { expectedText, index } ) {
+            it("Element at $index of `$$('label')` is $expectedText", function () {
+                expect($$('label')[index]).toHaveText(expectedText);
+            });
+        });
+    });
+```    

src/matchers/browser/toHaveClipboardText.ts

@@ -10,25 +10,27 @@ export async function toHaveClipboardText(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
-    const isNot = this.isNot
-    const { expectation = 'clipboard text', verb = 'have' } = this
+    const { expectation = 'clipboard text', verb = 'have', matcherName = 'toHaveClipboardText', isNot } = this
 
     await options.beforeAssertion?.({
-        matcherName: 'toHaveClipboardText',
+        matcherName,
         expectedValue,
         options,
     })
 
     let actual
-    const pass = await waitUntil(async () => {
-        await browser.setPermissions({ name: 'clipboard-read' }, 'granted')
+    const pass = await waitUntil(
+        async () => {
+            await browser.setPermissions({ name: 'clipboard-read' }, 'granted')
             /**
              * changes are that some browser don't support the clipboard API yet
              */
-            .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`))
-        actual = await browser.execute(() => window.navigator.clipboard.readText())
-        return compareText(actual, expectedValue, options).result
-    }, isNot, options)
+                .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`))
+            actual = await browser.execute(() => window.navigator.clipboard.readText())
+            return compareText(actual, expectedValue, options).result
+        },
+        isNot,
+        options)
 
     const message = enhanceError('browser', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {
@@ -37,7 +39,7 @@ export async function toHaveClipboardText(
     }
 
     await options.afterAssertion?.({
-        matcherName: 'toHaveClipboardText',
+        matcherName,
         expectedValue,
         options,
         result

src/matchers/browser/toHaveTitle.ts

@@ -6,21 +6,24 @@ export async function toHaveTitle(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
-    const isNot = this.isNot
-    const { expectation = 'title', verb = 'have' } = this
+    const { expectation = 'title', verb = 'have', matcherName = 'toHaveTitle', isNot } = this
 
     await options.beforeAssertion?.({
-        matcherName: 'toHaveTitle',
+        matcherName,
         expectedValue,
         options,
     })
 
     let actual
-    const pass = await waitUntil(async () => {
-        actual = await browser.getTitle()
+    const pass = await waitUntil(
+        async () => {
+            actual = await browser.getTitle()
 
-        return compareText(actual, expectedValue, options).result
-    }, isNot, options)
+            return compareText(actual, expectedValue, options).result
+        },
+        isNot,
+        options
+    )
 
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {
@@ -29,7 +32,7 @@ export async function toHaveTitle(
     }
 
     await options.afterAssertion?.({
-        matcherName: 'toHaveTitle',
+        matcherName,
         expectedValue,
         options,
         result

src/matchers/browser/toHaveUrl.ts

@@ -6,21 +6,24 @@ export async function toHaveUrl(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
-    const isNot = this.isNot
-    const { expectation = 'url', verb = 'have' } = this
+    const { expectation = 'url', verb = 'have', matcherName = 'toHaveUrl', isNot } = this
 
     await options.beforeAssertion?.({
-        matcherName: 'toHaveUrl',
+        matcherName,
         expectedValue,
         options,
     })
 
     let actual
-    const pass = await waitUntil(async () => {
-        actual = await browser.getUrl()
+    const pass = await waitUntil(
+        async () => {
+            actual = await browser.getUrl()
 
-        return compareText(actual, expectedValue, options).result
-    }, isNot, options)
+            return compareText(actual, expectedValue, options).result
+        },
+        isNot,
+        options
+    )
 
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {
@@ -29,7 +32,7 @@ export async function toHaveUrl(
     }
 
     await options.afterAssertion?.({
-        matcherName: 'toHaveUrl',
+        matcherName,
         expectedValue,
         options,
         result

src/matchers/element/toHaveAttribute.ts

@@ -27,52 +27,55 @@ async function conditionAttributeValueMatchWithExpected(el: WebdriverIO.Element,
 }
 
 export async function toHaveAttributeAndValue(received: WdioElementOrArrayMaybePromise, attribute: string, expectedValue: MaybeArray<string | RegExp | WdioAsymmetricMatcher<string>>, options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS) {
-    const isNot = this.isNot
-    const { expectation = 'attribute', verb = 'have' } = this
+    const { expectation = 'attribute', verb = 'have', isNot } = this
 
     let el
     let attr
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand(received,
-            undefined,
-            (elements) => defaultMultipleElementsIterationStrategy(elements, expectedValue, (element, expected) => conditionAttributeValueMatchWithExpected(element, attribute, expected, options))
-        )
-
-        el = result.elementOrArray
-        attr = result.valueOrArray
-
-        return result
-    }, isNot,  { wait: options.wait, interval: options.interval })
+    const pass = await waitUntil(
+        async () => {
+            const result = await executeCommand(received,
+                undefined,
+                (elements) => defaultMultipleElementsIterationStrategy(elements, expectedValue, (element, expected) => conditionAttributeValueMatchWithExpected(element, attribute, expected, options))
+            )
+
+            el = result.elementOrArray
+            attr = result.valueOrArray
+
+            return result
+        },
+        isNot,
+        { wait: options.wait, interval: options.interval }
+    )
 
     const expected = wrapExpectedWithArray(el, attr, expectedValue)
     const message = enhanceError(el, expected, attr, this, verb, expectation, attribute, options)
 
     return {
         pass,
         message: (): string => message
-    } as ExpectWebdriverIO.AssertionResult
+    }
 }
 
 async function toHaveAttributeFn(received: WdioElementOrArrayMaybePromise, attribute: string, options: ExpectWebdriverIO.CommandOptions = DEFAULT_OPTIONS) {
-    const isNot = this.isNot
-    const { expectation = 'attribute', verb = 'have' } = this
+    const { expectation = 'attribute', verb = 'have', isNot } = this
 
     let el
 
-    const pass = await waitUntil(async () => {
-        const result = await executeCommand(
-            received,
-            undefined,
-            (elements) => defaultMultipleElementsIterationStrategy(elements, attribute, (el) => conditionAttributeIsPresent(el, attribute))
-        )
+    const pass = await waitUntil(
+        async () => {
+            const result = await executeCommand(
+                received,
+                undefined,
+                (elements) => defaultMultipleElementsIterationStrategy(elements, attribute, (el) => conditionAttributeIsPresent(el, attribute))
+            )
 
-        el = result.elementOrArray
+            el = result.elementOrArray
 
-        return result
-    }, isNot, {
-        wait: options.wait,
-        interval: options.interval,
-    })
+            return result
+        },
+        isNot,
+        { wait: options.wait, interval: options.interval }
+    )
 
     const message = enhanceError(el, !isNot, pass, this, verb, expectation, attribute, options)
 
@@ -89,8 +92,10 @@ export async function toHaveAttribute(
     value?: MaybeArray<string | RegExp | WdioAsymmetricMatcher<string>>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const { matcherName = 'toHaveAttribute' } = this
+
     await options.beforeAssertion?.({
-        matcherName: 'toHaveAttribute',
+        matcherName,
         expectedValue: [attribute, value],
         options,
     })
@@ -102,7 +107,7 @@ export async function toHaveAttribute(
         : await toHaveAttributeFn.call(this, received, attribute)
 
     await options.afterAssertion?.({
-        matcherName: 'toHaveAttribute',
+        matcherName,
         expectedValue: [attribute, value],
         options,
         result