`el?.isDisplayed` is not a function

[nextlevelbeard]

Versions: latest webdriverio + latest expect-webdriverio, TS 5.4.3

Trigger await expect(await $$('.item')).toBeDisplayed();

Logs:

TypeError: el?.isDisplayed is not a function
    at file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/matchers/element/toBeDisplayed.js:9:74
    at file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/utils.js:55:96
    at Object.executeCommand (file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/util/executeCommand.js:2:26)
    at file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/utils.js:55:45
    at waitUntil (file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/utils.js:26:49)
    at async Object.executeCommandBe (file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/utils.js:54:18)
    at async Object.toBeDisplayed (file:///Users/user/repos/repo/e2e/node_modules/@wdio/runner/node_modules/expect-webdriverio/lib/matchers/element/toBeDisplayed.js:9:20)
    at async Scenario.<anonymous> (file:///Users/user/repos/repo/e2e/steps/my.steps.ts:XX:X)

[christian-bromann]

@nextlevelbeard do you have a reproducible example for it?

[sangcnguyen]

Below is my reproducible code example @christian-bromann

await browser.url("https://webdriver.io/");
await expect(await $$(`//a[@class="navbar__item navbar__link"]`)).toBeDisplayed()

It seems the current code accepts $(), not $$(). Should we add support for handling an array of elements?

[christian-bromann]

Should we add support for handling an array of elements?

What would you think the behavior should be? Should it fail if one of the found elements are not visible?

Generally we only have one matcher that allows passing in WebdriverIO.ElementArrays. I am not sure what if there is an interest in adding more as you usually only assert one element at a time. However I am open for ideas here.

[sangcnguyen]

What would you think the behavior should be?

I used to write with Selenium, Playwright. I'm hesitant because they don't have behavior like this to check if an array is displayed.

Should it fail if one of the found elements are not visible?

I think it makes sense to mark the test as a failure if one of the elements is not visible.

Generally we only have one matcher that allows passing in WebdriverIO.ElementArrays. I am not sure what if there is an interest in adding more as you usually only assert one element at a time. However I am open for ideas here.

I think for now we should improve the error messages when the function does not support taking an array element and include the documentation directly into the types file. That could help users (including myself) better understand how to use the matchers.

[christian-bromann]

I think for now we should improve the error messages when the function does not support taking an array element

Maybe we can do this for all matchers that expect that? Like having a validateInput method that throws if the input is not an WebdriverIO.Element or a Promise of that. Also agree with your further suggestions.

[htho]

I'd like to mention that the types file suggests, that these matchers should work with WebdriverIO.ElementArrays (the result of $$) as well:

    interface Matchers<R, T> {
        // ===== $ or $$ ===== // << HERE IT IS
        /**
         * `WebdriverIO.Element` -> `isDisplayed`
         */
        // ...
        }

[christian-bromann]

@htho this is due to the fact that we don't have a better type for these matchers as we currently support matchers for single elements ($) and element arrays ($$). This could be improved. However most matchers are suppose to only work with single elements.

[htho]

Ah. I did not make it clear. It's not about the type definition itself. I meant the normal comment on the first line of the interface.

L491 says the following section is $$ only: // ===== $$ only =====

But L156 claims it is about $ and $$: // ===== $ or $$ =====

Yes - those are not type comments, but I like to look at the d.ts files to better understand the API. And this comment lets me believe that the following matchers are for both.

[christian-bromann]

But L156 claims it is about $ and $$: // ===== $ or $$ =====

This doesn't seem correct to me, not sure for what this stands for or if there was a plan to support expect($$('elem')).toBeExisting() that would fail if one of the elements would not exist. I doubt that though so it sounds the comment is just wrong.

[wdio-bot]

Thanks for reporting this issue, @nextlevelbeard! 👍

After investigating your report, I can confirm this is a legitimate bug that's part of a broader inconsistency in our matcher array support. Your feedback prompted a thorough analysis that revealed this is more significant than initially apparent.

🐛 Issue Summary

The toBeDisplayed matcher fails when used with element arrays from the $$() selector, throwing the error el?.isDisplayed is not a function. While users expect this to work consistently with other matchers, there's currently inconsistent array support across different matchers in the library.

🔍 Root Cause

The toBeDisplayed matcher uses the executeCommandBe function, which is designed only for single elements and calls the el?.isDisplayed() method. When passed an element array from $$(), this fails because arrays don't have an isDisplayed() method. Additionally, the type signature WdioElementMaybePromise only supports single elements, not ChainablePromiseArray types.

The broader issue: Some matchers (toHaveText, toHaveHTML) already support arrays while others (toBeDisplayed, toBeEnabled) don't, creating an inconsistent developer experience.

📁 Files That Need Modification

• src/matchers/element/toBeDisplayed.ts - Main implementation
• docs/API.md - API documentation updates
• docs/Examples.md - Fix invalid examples showing array usage
• Test files for the toBeDisplayed matcher - Add array test coverage

🛠️ Suggested Implementation Approach

Following the pattern used by array-supporting matchers like toHaveText:

1. Update Type Signature

   • Change from WdioElementMaybePromise to support both single elements and ChainablePromiseArray

2. Replace Core Function

   • Switch from executeCommandBe to executeCommand (which has array handling capability)

3. Add Array Detection Logic

   • Implement logic to detect whether input is a single element or array
   • Handle both cases appropriately

4. Array Processing Logic

   • For arrays: iterate through elements, checking each one's display status
   • Determine appropriate behavior (all must be displayed? any? configurable?)

5. Update Documentation

   • Fix examples in docs/Examples.md that incorrectly show array usage
   • Add proper array usage examples to docs/API.md

6. Comprehensive Testing

   • Add test cases for both single elements and arrays
   • Test edge cases (empty arrays, mixed display states)

⚠️ Important Considerations

• Behavior Decision: Determine whether expect(elements).toBeDisplayed() should pass when ALL elements are displayed, or if ANY element being displayed is sufficient
• Consistency: Consider applying the same array support pattern to other matchers like toBeEnabled for library-wide consistency
• Backward Compatibility: Ensure existing single-element usage continues to work unchanged
• Error Messages: Provide clear, helpful error messages for both single elements and arrays

🤝 Community Contribution Welcome!

This is a great opportunity for community contribution! Here's how you can help:

For New Contributors:

• This issue involves TypeScript, matcher implementation patterns, and documentation
• Look at src/matchers/element/toHaveText.ts as a reference for array-supporting matcher implementation
• Start with the core implementation, then move to tests and documentation

Getting Started:

1. Fork the repository and set up your development environment
2. Examine how toHaveText handles arrays vs single elements
3. Apply the same pattern to toBeDisplayed
4. Write tests covering both single elements and arrays
5. Update documentation with correct examples

Questions? Feel free to comment here or reach out if you need clarification on any part of the implementation approach.

I'll be adding the "help wanted" label to make this more discoverable for contributors. This fix will significantly improve the consistency and developer experience of our matcher library!

[dprevost-LMI]

On it. This is a problem with multiple other matchers

There are 3 types to support:

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

Failure message for each case

ChainablePromiseArray & ElementArray

Expect $$(`sel, <props>`) to be displayed

Expected: "displayed"
Received: "not displayed"

Element[]

Expect $(`sel`), $$(`sel`)[1] to be displayed

Expected: "displayed"
Received: "not displayed"

In both cases, the failure message is suboptimal because it provides no indication of which element in the array is not displayed. Something to enhance later

[dprevost-LMI]

Look at src/matchers/element/toHaveText.ts as a reference for array-supporting matcher implementation

After reviewing it (for non-boolean matchers), it documents toHaveText.ts as supporting $$(), and it mentions asserting with an array but without clarity on the exact behaviour.

However, this line is matching on any values of the array without considering its position, which introduces a possible undesired behaviour for $$(), whereas in the example, when providing the array, you might think the order is also validated.

Note: As documented, the above targeted behaviour exists for $() and makes sense when you want to pass multiple possible values to a single element, but for $$(), we might want a different behaviour.
However, for $(), we could also deprecate that behaviour and ask to rely on regex providing a similar behaviour that is clearer, as example ['Coffee', 'Tea', 'Milk'] would become /^(Coffee|Tea|Milk)$/

Conclusion: For toHaveText.ts, I will keep the current behaviour, but for all the other matchers, I will not reproduce this behaviour and make an exact match with an array