expect-webdriverio 6.0.4 → 6.0.6

package/README.md

@@ -1,17 +1,16 @@
 # expect-webdriverio [![Test](https://github.com/webdriverio/expect-webdriverio/actions/workflows/test.yml/badge.svg)](https://github.com/webdriverio/expect-webdriverio/actions/workflows/test.yml)
 
-
 ###### [API](docs/API.md) | [TypeScript / JS Autocomplete](docs/Types.md) | [Examples](docs/Examples.md) | [Extending Matchers](docs/CustomMatchers.md)
 
-> [WebdriverIO](https://webdriver.io/) Assertion library inspired by [expect](https://www.npmjs.com/package/expect)
+> [WebdriverIO](https://webdriver.io/) assertion library inspired by [expect](https://www.npmjs.com/package/expect)
 
 ## Key Features
 
-- [Waits](#default-options) for expectation to succeed
-- Support single element & multi-elements
+- [Waits](#default-options) for expectations to succeed
+- Supports single element `$()` & multiple elements `$$()`
 - Detailed [error messages](#error-messages)
-- Works in Mocha, Cucumber, Jest, Jasmine
-- Builtin [types](docs/Types.md) for TypeScript and JS autocompletion
+- Works in Mocha, Cucumber, Jest, and Jasmine
+- Built-in [types](docs/Types.md) for TypeScript and JS autocompletion
 
 ## Installation
 
@@ -22,24 +21,28 @@
    - **Cucumber**: `npm install @wdio/cucumber-framework`
    - **Jest**: No adapter needed — see [Jest Framework section](docs/Framework.md#jest)
 
-NOTE: [WebdriverIO](https://github.com/webdriverio/webdriverio) `v9.0.0` or higher is required!
+**Note:** [WebdriverIO](https://github.com/webdriverio/webdriverio) `v9.0.0` or higher is required!
 
 ## Usage
 
 ### Using WebdriverIO Testrunner
 
-If you run your tests through the [WDIO testrunner](https://webdriver.io/docs/clioptions) no additional setup is needed. WebdriverIO initialises `expect-webdriverio` and makes `expect` available in the global scope. So you can use it directly in your tests:
+If you run your tests through the [WDIO testrunner](https://webdriver.io/docs/clioptions), no additional setup is needed. WebdriverIO initializes `expect-webdriverio` and makes `expect` available in the global scope so you can use it directly in your tests:
 
 ```js
-const button = await $('button')
-await expect(button).toBeDisplayed()
+await expect($('button')).toBeDisplayed()
+await expect($$('buttons')).toBeDisplayed()
 ```
 
-See more [Examples](docs/Examples.md)
+See more [Examples](docs/Examples.md).
+
+#### Local & Browser Runners
+- **Local Runner**: Fully compatible. You can leverage your test framework adapter as mentioned above.
+- **Browser Runner**: Designed for component frameworks like React, Preact, Vue.js, Svelte, and SolidJS, with a few known limitations. For details, see the [Browser Runner Framework section](docs/Framework.md#browser-runner).
 
-### Using in a standalone script
+### Using in Standalone Mode
 
-If you embed WebdriverIO in a standalone (without `@wdio/globals`), make sure you import `expect-webdriverio` before you use it anywhere.
+If you use WebdriverIO in standalone mode (without `@wdio/globals`), make sure you import `expect-webdriverio` before using it anywhere.
 
 ```js
 import { remote } from 'webdriverio'
@@ -63,24 +66,24 @@ import { expect } from 'expect-webdriverio'
 
 ## API
 
-Please see [API doc](docs/API.md)
+Please see the [API documentation](docs/API.md).
 
-## Error messages
+## Error Messages
 
 Error messages are informative out of the box and contain:
 
-- full element selector, like `$('form').$('input')`
-- actual and expected values
-- highlight the difference (texts assertions)
+- Full element selector, like `$('form')`
+- Actual and expected values
+- Highlighted differences (text assertions)
 
 ![toHaveText](/docs/img/errors/text.png?raw=true "toHaveText")
 ![toHaveElementClass](/docs/img/errors/class.png?raw=true "toHaveElementClass")
 
-## What's next?
+## What's Next?
 
-First of all, **feel free to raise an issue with your suggestions or help with PR!**
+First of all, **feel free to raise an issue with your suggestions or help with PRs!**
 
 ### Planned
 
-- cookie
-- multiremote support (coming)
+- Cookie matchers
+- Multiremote support (in progress)

package/lib/matchers/asymmetrics/oneOf.js

@@ -1,6 +1,9 @@
 import { compareTextWithArray } from '../../utils.js';
 import { WdioAsymmetricMatchers } from './asymmetricsUtils.js';
+const ONE_OF_TAG = 'expect-webdriverio.oneOf';
+const ONE_OF_SYMBOL = Symbol.for(ONE_OF_TAG);
 export class OneOfMatcher extends WdioAsymmetricMatchers {
+    [ONE_OF_SYMBOL] = true;
     options = {};
     constructor(...sample) {
         super(sample);
@@ -49,3 +52,6 @@ export class OneOfMatcher extends WdioAsymmetricMatchers {
 export function oneOf(...sample) {
     return new OneOfMatcher(...sample);
 }
+export function isOneOfMatcher(oneOfMatcher) {
+    return oneOfMatcher instanceof OneOfMatcher || oneOfMatcher?.[ONE_OF_SYMBOL] === true;
+}

package/lib/matchers/element/toHaveAttribute.js

@@ -3,7 +3,7 @@ import { executeCommandWithStrategy } from '../../util/executeCommand.js';
 import { compareText, enhanceError, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { expect as wdioExpect } from '../../index.js';
 import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
-import { OneOfMatcher } from '../asymmetrics/oneOf.js';
+import { isOneOfMatcher } from '../asymmetrics/oneOf.js';
 async function conditionAttributeValueMatchWithExpected(el, attribute, expectedValue, options) {
     const attributeValue = await el.getAttribute(attribute);
     if (typeof attributeValue !== 'string' || expectedValue === undefined || expectedValue === null) {
@@ -12,7 +12,7 @@ async function conditionAttributeValueMatchWithExpected(el, attribute, expectedV
         }
         return { success: attributeValue === expectedValue, actual: attributeValue };
     }
-    else if (expectedValue instanceof OneOfMatcher) {
+    else if (isOneOfMatcher(expectedValue)) {
         return { success: expectedValue.asymmetricMatch(attributeValue), actual: attributeValue };
     }
     return compareText(attributeValue, expectedValue, options);

package/lib/matchers/element/toHaveElementProperty.js

@@ -3,7 +3,7 @@ import { executeCommandWithStrategy } from '../../util/executeCommand.js';
 import { expect as wdioExpect } from '../../index.js';
 import { compareText, enhanceError, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { buildWdioAsymmetricMatchersWithOptions } from '../asymmetrics/asymmetricsUtils.js';
-import { OneOfMatcher } from '../asymmetrics/oneOf.js';
+import { isOneOfMatcher } from '../asymmetrics/oneOf.js';
 async function condition(el, property, expectedValue, options = DEFAULT_OPTIONS) {
     const { asString = false } = options;
     const propertyValue = await el.getProperty(property);
@@ -13,7 +13,7 @@ async function condition(el, property, expectedValue, options = DEFAULT_OPTIONS)
         }
         return { success: propertyValue === expectedValue, actual: propertyValue };
     }
-    else if (expectedValue instanceof OneOfMatcher) {
+    else if (isOneOfMatcher(expectedValue)) {
         return { success: expectedValue.asymmetricMatch(propertyValue), actual: propertyValue };
     }
     return compareText(propertyValue.toString(), expectedValue, options);

package/lib/matchers/modifiers/some.js

@@ -11,5 +11,5 @@ export function some(elements) {
     return new SomeElementsWrapper(elements);
 }
 export function isSomeWrapper(value) {
-    return value instanceof SomeElementsWrapper;
+    return value instanceof SomeElementsWrapper || value?.[SOME_SYMBOL] === true;
 }

package/lib/utils.js

@@ -5,7 +5,7 @@ import { executeCommandWithStrategy } from './util/executeCommand.js';
 import { enhanceError, enhanceErrorBe } from './util/formatMessage.js';
 import { waitUntil } from './util/waitUntil.js';
 import { DEFAULT_FEATURE_FLAGS } from './constants.js';
-import { OneOfMatcher } from './matchers/asymmetrics/oneOf.js';
+import { isOneOfMatcher, OneOfMatcher } from './matchers/asymmetrics/oneOf.js';
 export function isJasmineStringAsymmetricMatcher(expected) {
     return isAsymmetricMatcher(expected) && !('toAsymmetricMatcher' in expected) && 'jasmineToString' in expected && typeof expected.jasmineToString === 'function';
 }
@@ -88,7 +88,7 @@ export const compareTextOrArray = (actualText, expectedTexts, options) => {
         return { actual: actualText, success: false };
     }
     if (Array.isArray(expectedTexts)) {
-        if (expectedTexts.some((expected) => expected instanceof OneOfMatcher)) {
+        if (expectedTexts.some((expected) => isOneOfMatcher(expected))) {
             throw new Error('OneOf is not supported in array under legacy behavior. Please enable `useToHaveTextStrictMultiElementsCompareStrategy` feature flag to use the new strict index based matching strategy with `expect.oneOf()`.');
         }
         else {
@@ -96,7 +96,7 @@ export const compareTextOrArray = (actualText, expectedTexts, options) => {
             expectedTexts = new OneOfMatcher(...expectedTexts).withOptions(options);
         }
     }
-    if (expectedTexts instanceof OneOfMatcher) {
+    if (isOneOfMatcher(expectedTexts)) {
         return { success: expectedTexts.asymmetricMatch(actualText), actual: actualText };
     }
     const compareResults = compareText(actualText, expectedTexts, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expect-webdriverio",
-  "version": "6.0.4",
+  "version": "6.0.6",
   "author": "Mykola Grybyk <mykola.grybyk@gmail.com>",
   "description": "WebdriverIO Assertion Library",
   "license": "MIT",
@@ -92,9 +92,9 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^4.1.10",
-    "@vitest/eslint-plugin": "^1.6.26",
+    "@vitest/eslint-plugin": "^1.6.27",
     "@wdio/eslint": "^0.1.3",
-    "@wdio/types": "^9.30.1",
+    "@wdio/types": "^9.31.1",
     "eslint": "^9.39.5",
     "husky": "^9.1.7",
     "npm-run-all2": "^9.0.3",

package/types/expect-webdriverio.d.ts

@@ -22,7 +22,7 @@ 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>
+type WdioSome<T> = import('expect-webdriverio/api').WdioSome<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> = {
@@ -1274,6 +1274,9 @@ declare module 'expect-webdriverio' {
  * Required since importing from 'expect-webdriverio' can trigger double initialization.
  */
 declare module 'expect-webdriverio/api' {
+    export interface WdioSome<T> {
+        readonly elements: T
+    }
     /**
      * Quantifier modifier. Wraps a `$$()` result so that the matcher passes
      * when at least one element satisfies the condition (∃ semantics).