feat: Support $$() with all element's matchers

[dprevost-LMI]

Fixes #1507.
Partially fixes #512.
Fixes #1717.

Summary

Adds official $$() (element array) support to toBe and toHave matchers. Previously, TypeScript signatures allowed arrays (by mistake in this PR), but the implementation didn't support them properly.

Example:

 await expect($$('items')).toBeDisplayed(); await expect($$('items')).toHaveHTML('<div/>'); await expect($$('items')).toHaveHTML(['<div/>', '<label/>']); // `.not` cases await expect($$('items')).not.toBeDisplayed(); await expect($$('items')).not.toHaveHTML('<div/>'); await expect($$('items')).not.toHaveHTML(['<div/>', '<label/>']);

Current Behaviour Issues

• Only toHaveText and toBeElementsArrayOfSize officially support arrays
• Non-awaited $$() or filtered $$().filter() throws errors
• toHaveText with empty elements incorrectly passes
• toHaveText doesn't trim text for multiple elements (inconsistent with single element behaviour)
• toHaveText doesn't do strict and index-based comparison but only loose comparison (kept)
• Failure message not shown all elements values (changed)

Error handling

• When $$ returns only one element and we have one expected value, the error message (CHANGED)

Expect $$(`#username`) to have text Expected: "t" Received: "" 

• When $$ returns only one element and an array of expectations is passed, the error message (CHANGED)

Expect $$(`#username`) to have text Expected: ["t", "r"] Received: "" 

• When having multiple elements and multiple expected values, we see the following (CHANGED)

Expect $$(`label`) to have text - Expected - 3 + Received + 1 Array [ - Array [ "Username", - "Password1", - ], + "Password", ] 

Note: All the above have been changed to show all the elements' values and not just those not matching

Official $$() Support

This PR adds official support for most matchers, with a focus on the toBe and toHave element matchers.

⚠️ While $$() support may incidentally enable expect() to work with multi-remote, this is not intended and may break at any time. Official multi-remote support is tracked here and is not yet available.

Types Support

• ChainablePromiseArray, the non-awaited case
• ElementArray, the awaited case
• Element[], the filtered case

Behavior

The following must pass when all elements are displayed/have the HTML; otherwise, it fails.

 await expect($$('items')).toBeDisplayed(); await expect($$('items')).toHaveHTML('<div/>'); await expect($$('items')).toHaveHTML(['<div/>', '<label/>']);

• For toBe matchers, all elements must match the expected boolean (usually true, except for toBeDisabled).
• For toHave matchers, you can provide a single expected value or an array; strict array comparison is used.
• Options like StringOptions, HTMLOptions, ToBeDisplayedOptions apply to the whole array (not per element).
• Only NumberOptions can be provided as an array since it's the only "option" treated as expected values.

Array Comparison Behaviour

• With a single expected value, all elements must strictly match (for text, trimming is the default unless { trim: false }).
• With an array of expected values, each element is compared by index; differing array lengths or mismatches cause failure.
• Except for toHaveText (deprecated), elements are not compared to any value in the expected array—only by index.
• For number options, strict matching still applies according to the NumberOptions rules.

isNot

The following must pass when all elements are not displayed/not have the text; otherwise, it fails.

 await expect($$('items')).not.toBeDisplayed(); await expect($$('items')).not.toHaveHTML('<div/>'); await expect($$('items')).not.toHaveHTML(['<div/>', '<label/>']);

Edge cases

No elements found

When no elements are found, we fail at all times with or without .not, even if the expected is an empty array.

• Only toBeElementsArrayOfSize(0) support empty array element

expect.arrayContaining

Only toHaveText will do a containing array behaviour with the following

 await expect(await $$('label')).toHaveText(['Username', 'Password']);

We should consider deprecating the above for expect.arrayContaining and supporting it, which is not the case at all

 await expect(await $$('label')).toHaveText(expect.arrayContaining(['Username', 'Password']));

Error handling

Below are examples of failures with colours.

• We can see cases for multiple elements for the toHaveText and toBeDisplayed matchers
• With .not
  • toBe are handled by adding not in the values
  • For toHave matchers, a more complex method was used to highlight those actuall matching (red highlight)

Previous Releases Bugs 🐛

Fixed bugs from previous releases (fixed when checked)

• Non-awaited $$() calls like expect($$('el')).toHaveText('text') no longer cause function errors.
• Array comparisons now trim actual text values by default.
• toBeElementsArrayOfSize typings now work correctly with Element[].
• Typings for toHaveElementProperty adjusted—using an optional value always failed; future support for existence checks like toHaveAttribute may be added.
• $$().toHaveText('C' | ['C']) now fails when there are no elements (e.g., expect([]).toHaveText('test')); all matchers fail gracefully on empty arrays.
• Multiple matchers now report the correct names in before and after hooks.
• BREAKING Removed deprecated toHaveClassContaining and toHaveClass matchers.
• Non-element parameters to expect() (e.g., expect(undefined)) now fail gracefully with clear messages.

Future Considerations

• Consider supporting arrays-per-element in $$() (compare each element against multiple values), but this is complex, limited to $$(), and alternatives exist (e.g., regex, stringContaining).
• Deprecate NumberOptions as an "option"—treat as ExpectedType for clarity and easier handling of other options (e.g., error messages, wait).
• Show failure instead of throwing for missing elements or even index out of bounds from $()[x]; POC done and working.
• Support Promise<Element|Elements> in typings.
• Enhance support and typings for expect.arrayContaining() across all matchers and remove custom “containing” logic from toHaveText.
• Improve TypeScript typing for single element vs. array of elements, reflecting matcher support for array values and elements (overloaded functions)
• For toBeElementsArrayOfSize.ts, consider updating the array of the non-awaited case by awaiting it
• For toHaveElementProperty
  • Use deep-equality to support type like object & Arrays
  • As toHaveAttribute support properly optional expected value for property existence

TODO

• Documentations
• Finish error handling cases validations
• Finish code review
• Finish writing multiple elements & multiple expected values for each matcher
• Add more UTs case got toHaveElement & unknown? And review the null case?
• Test multiple elements with assymetric matcher a bit more
• Look to support strict matching with toHaveText somehow now or later?
• Ensure toHaveText legacy behaviour is kept, including failure reporting!
• Get approval and document the fact that awaiting element/elements is now always in the wait time of waitUntil
• Test it out in the playground (when merged)
• Get approval on the documented behaviour in MultipleElements.md (Christian?)
• Review .not in waitUntil following regression in main
• Assert if we need to refreshElements (now or later) as we do for singleElement when they are not found
• Review localStorageItem once it's merged (if needed)
• Review forgotten snapshot matchers

Blocked and waiting on the merge of

• fix: Better consideration of the negated matcher in waitUntil #1983
• fix: failure msg with enhanceErrorBe + code refactoring simplification #1987
• chore: Ensure mocks used represented wdio framework reality + bonus #1991
• fix: Jasmine augmentation withContext and add Playgrounds for Jasmine, Jest & Mocha #2010
• feat(expect-webdriverio): add toHaveLocalStorageItem matcher #1900

Not blockers, but good to have dependent PR

• fix: Fix incorrect typings and commands inconsistency webdriverio#15003

[dprevost-LMI]

Waiting on merge of #1991

[dprevost-LMI]

Fixed bad matcher name

[dprevost-LMI]

Fixed issue where single expect value vs multiple expected value behavior differently by default

[dprevost-LMI]

Replaced below by ?? { gte: 1 } + test added

const numberOptions = validateNumberOptionsArray(expectedValue ?? { gte: 1 })

[dprevost-LMI]

Renaming from toHaveClass

[christian-bromann]

What is the status of this?

[dprevost-LMI]

I was waiting for at least some feedback on the defined behaviour here: https://github.com/webdriverio/expect-webdriverio/blob/860dedcc78c9ede976eae187fdd6a44cdf8b2c4e/docs/MultipleElements.md
I suspect you will be the best person to do so?

I moved back to draft and update the list of tasks

• Get approval and document the fact that awaiting element/elements is now always in the wait time of waitUntil
• Test it out in the playground (when merged)
• Get approval on the documented behaviour in MultipleElements.md (Christian?)
• Review .not in waitUntil following regression in main
• Assert if we need to refreshElements (now or later) as we do for singleElement when they are not found