refactor!: identify WebdriverIO objects by the wdio.kind brand

[dprevost-LMI]

Closes #2296

Proposed changes

WebdriverIO v10 brands its objects with Symbol.for('wdio.kind'): browser, browsing-context, element, element-array or mock. The matchers now identify objects by this brand, not by their shape ('getElements' in, parent, calls) or their constructor name.

• src/util/wdioKind.ts: getWdioKind() reads the brand with Symbol.for(), without a dependency on @wdio/utils. getLoadedWdioKind() gives the brand only when the value has no then, the same rule as in @wdio/utils: a not-awaited $() is a Promise with the element brand, and a not-awaited $$() is a list with the element-array brand and a then.
• isElement(), isStrictlyElementArray(), isMultiRemoteElement(), isMultiRemoteElementArray(), isBrowser(), isMultiRemoteBrowser(), isMock() and isMultiRemoteMock() keep their names and signatures, so their callers do not change.
• isStrictlyElementArray() also checks Array.isArray(): a chained $('a').$$('b') or a custom $$ command before await is a Promise with the same brand.
• A BrowsingContext has the constructor name Browser, so isBrowser() accepted it before. It still does, so the failure message does not change. [v8] feat: Support a WebdriverIO v10 BrowsingContext (tab, window, frame) in the browser matchers #2298 decides this (TODO(#2298)).
• No v9 fallback: v8 requires WebdriverIO v10 (build!: require WebdriverIO v10 #2299).

Fix: false pass with a not-awaited multi-remote $$()

In v10, a not-awaited $$() is the list itself, not a Promise. Until the list is loaded, it has then, and its length is a Promise. The old instanceof Promise check did not await it, so a not-awaited multi-remote $$() counted 0 elements: toBeElementsArrayOfSize(0) passed on a page with elements, and the element matchers failed with wait: 0. awaitElementOrArray() and awaitElementArray() now always await the received value. await gives back a value that is not a thenable, and it gives the same list, so a refetch still updates the user's list in place. This bug was there before this PR. WebdriverIO docs issue: webdriverio/webdriverio#15935.

Unit test mocks

The mocks now match WebdriverIO 10.0.0. Each mock has its brand. A not-awaited $() is a Promise with the element brand. A not-awaited $$(), multi-remote or not, is a list that loads later and throws on for...of until it is loaded. The tests that expected the v9 shape (a $$() that is a Promise) now expect the v10 shape.

Breaking change

An object without the wdio.kind brand is not a browser, element, element list or mock. Real WebdriverIO v10 objects have the brand. A hand-made fake in a user's own unit tests needs it: see docs/Migrations.md, "WebdriverIO objects are identified by their brand". An array of unbranded fake mocks now throws a TypeError, as any other value that is not a mock.

How you tested

• Unit tests (a new test fails before the fix)
  • pnpm run checks:all: 2574 passed, 40 skipped (the same skips as on main).
  • The tests for unbranded fakes, and for a browsing context with parent and getElement, failed before the brand change.
  • The not-awaited multi-remote $$() tests (toBeElementsArrayOfSize 2 and 0, toBeDisplayed with wait: 0) failed before the fix.
  • Guard tests fail without the line they protect: without Array.isArray() in isStrictlyElementArray(), the chained $().$$() test fails. If the failure message accepts a parent that is not loaded, the parent-walk test fails.
• pnpm run test:types: jasmine 37, jasmine-global-expect-async 40, jest 61 and mocha 123 passed. ts:declarations and ts:package passed.
• Playground run: pnpm run playgrounds:checks:all passed for the 5 playgrounds: browser-runner 1/1, jasmine 7/7, jest 39/39, mocha 7/7, and multi-remote 6/6 (Chrome + Firefox). The new multi-remote test "should count the elements of a not-awaited $$() at once, without a retry" failed with the build before the fix, and passes with it.
• Before writing the code, I checked the brands of 45 objects in real Chrome and Firefox sessions with WebdriverIO 10.0.0, single and multi-remote.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Refactors object type detection to use WebdriverIO v10 brand symbols.

The PR appears safe to merge; no actionable defect was found.

What we checked:

• Only fixed Promise methods run: Both branches allow only catch and finally on the Promise returned by settle.
• Lists load before counting: awaitElementArray awaits the received value before returning it. toBeElementsArrayOfSize waits for that result before reading the length or counting each browser's elements.

Summary

The PR identifies WebdriverIO objects through Symbol.for('wdio.kind') instead of their properties or constructor names.

• Always awaits received element lists before matchers use them, including multi-remote $$() results.
• Updates mocks and adds tests for unloaded lists, branded objects, and selector messages.
• Documents the required brand for hand-made test objects.
• No actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Received element or list"] --> B["Await received value"]
    B --> C{"Read wdio.kind"}
    C --> D["Single element: getElement"]
    C --> E["Single-browser list: getElements"]
    C --> F["Multi-remote element or list"]
    C --> G["Unrecognized value"]
    D --> H["Compare values"]
    E --> H
    F --> H
    H --> I["Refetch eligible lists on retry"]

Loading

_{Reviews (1) · Last reviewed commit: "refactor: find a loaded element by its b..."}