expect-webdriverio 5.5.0 → 5.6.0

package/README.md

@@ -1,7 +1,7 @@
 # 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/Extend.md)
+###### [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)
 

package/jasmine-wdio-expect-async.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="./types/expect-webdriverio.d.ts"/>
+
+/**
+ * Overrides the default wdio `expect` for Jasmine case specifically since the `expect` is now completely asynchronous which is not the case under Jest or standalone.
+ */
+declare namespace ExpectWebdriverIO {
+    interface Expect extends ExpectWebdriverIO.AsymmetricMatchers, ExpectLibInverse<ExpectWebdriverIO.InverseAsymmetricMatchers>, WdioExpect {
+        /**
+         * The `expect` function is used every time you want to test a value.
+         * You will rarely call `expect` by itself.
+         *
+         * expect function declaration contains two generics:
+         *  - T: the type of the actual value, e.g. any type, not just WebdriverIO.Browser or WebdriverIO.Element
+         *  - R: the type of the return value, e.g. Promise<void> or void
+         *
+         * Note: The function must stay here in the namespace to overwrite correctly the expect function from the expect library.
+         *
+         * @param actual The value to apply matchers against.
+         */
+        <T = unknown>(actual: T): ExpectWebdriverIO.MatchersAndInverse<Promise<void>, T>
+    }
+}

package/jasmine.d.ts

@@ -1,6 +1,27 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
 declare namespace jasmine {
+
+    /**
+     * Async matchers for Jasmine to allow the typing of `expectAsync` with WebDriverIO matchers.
+     * T is the type of the actual value
+     * U is the type of the expected value
+     * Both T,U must stay named as they are to override the default `AsyncMatchers` type from Jasmine.
+     *
+     * We force Matchers to return a `Promise<void>` since Jasmine's `expectAsync` expects a promise in all cases (different from Jest)
+     */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.Matchers<Promise<void>, T> {}
-}
+    interface AsyncMatchers<T, U> extends Omit<ExpectWebdriverIO.Matchers<Promise<void>, T>, 'toMatchSnapshot' | 'toMatchInlineSnapshot'> {
+        /**
+         * snapshot matcher
+         * @param label optional snapshot label
+         */
+        toMatchSnapshot(label?: string): Promise<void>;
+        /**
+         * inline snapshot matcher
+         * @param snapshot snapshot string (autogenerated if not specified)
+         * @param label optional snapshot label
+         */
+        toMatchInlineSnapshot(snapshot?: string, label?: string): Promise<void>;
+    }
+}

package/jest.d.ts

@@ -1,5 +1,37 @@
 /// <reference types="./types/expect-webdriverio.d.ts"/>
 
+/**
+ * Augment the Jest namespace to include the matchers from expect-webdriverio.
+ * When Jest Library is used, it specifies `expect-webdriverio/jest` for this file in the tsconfig.json's types.
+ */
+
 declare namespace jest {
-    interface Matchers<R, T> extends ExpectWebdriverIO.Matchers<R, T> { }
-}
+
+    interface Matchers<R extends void | Promise<void>, T> extends ExpectWebdriverIO.Matchers<R, T> {
+
+        /**
+         * Below are overloaded Jest's matchers not part of `expect` but of `jest-snapshot`.
+         * @see https://github.com/jestjs/jest/blob/73dbef5d2d3195a1e55fb254c54cce70d3036252/packages/jest-snapshot/src/types.ts#L37
+         *
+         *  Note: We need to define them below so that they are correctly typed overloaded.
+         *  Else even when extending `WdioJestOverloadedMatchers` we have typing errors.
+         */
+
+        /**
+         * snapshot matcher
+         * @param label optional snapshot label
+         */
+        toMatchSnapshot(label?: string): T extends WdioPromiseLike ? Promise<void> : void;
+
+        /**
+         * inline snapshot matcher
+         * @param snapshot snapshot string (autogenerated if not specified)
+         * @param label optional snapshot label
+         */
+        toMatchInlineSnapshot(snapshot?: string, label?: string): T extends WdioPromiseLike ? Promise<void> : void;
+    }
+
+    interface Expect extends ExpectWebdriverIO.Expect {}
+
+    interface InverseAsymmetricMatchers extends ExpectWebdriverIO.AsymmetricMatchers {}
+}

package/lib/matchers/element/toHaveClass.js

@@ -1,12 +1,12 @@
 import { DEFAULT_OPTIONS } from '../../constants.js';
-import { compareText, compareTextWithArray, enhanceError, executeCommand, isAsymmeyricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
+import { compareText, compareTextWithArray, enhanceError, executeCommand, isAsymmetricMatcher, waitUntil, wrapExpectedWithArray } from '../../utils.js';
 import { toHaveAttributeAndValue } from './toHaveAttribute.js';
 async function condition(el, attribute, value, options) {
     const actualClass = await el.getAttribute(attribute);
     if (typeof actualClass !== 'string') {
         return { result: false };
     }
-    if (isAsymmeyricMatcher(value)) {
+    if (isAsymmetricMatcher(value)) {
         return compareText(actualClass, value, options);
     }
     const classes = actualClass.split(' ');

package/lib/matchers/snapshot.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { expect } from 'expect';
 import { stripSnapshotIndentation } from '@vitest/snapshot';
-import { SnapshotService } from '../snapshot.js';
+import { SnapshotService } from '../snapshot';
 function returnSnapshotError(snapshotError) {
     try {
         expect(snapshotError.actual).toBe(snapshotError.expected);

package/lib/snapshot.js

@@ -1,43 +1,29 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _WebdriverIOSnapshotEnvironment_resolveSnapshotPath, _SnapshotService_instances, _SnapshotService_currentFilePath, _SnapshotService_currentTestName, _SnapshotService_options, _SnapshotService_snapshotResults, _SnapshotService_snapshotClient, _SnapshotService_isEqual;
 import { expect } from '@wdio/globals';
 import { SnapshotClient } from '@vitest/snapshot';
 import { NodeSnapshotEnvironment } from '@vitest/snapshot/environment';
 let service;
 class WebdriverIOSnapshotEnvironment extends NodeSnapshotEnvironment {
+    #resolveSnapshotPath;
     constructor(resolveSnapshotPath) {
         super({});
-        _WebdriverIOSnapshotEnvironment_resolveSnapshotPath.set(this, void 0);
-        __classPrivateFieldSet(this, _WebdriverIOSnapshotEnvironment_resolveSnapshotPath, resolveSnapshotPath, "f");
+        this.#resolveSnapshotPath = resolveSnapshotPath;
     }
     async resolvePath(filepath) {
-        if (__classPrivateFieldGet(this, _WebdriverIOSnapshotEnvironment_resolveSnapshotPath, "f")) {
-            return __classPrivateFieldGet(this, _WebdriverIOSnapshotEnvironment_resolveSnapshotPath, "f").call(this, filepath, '.snap');
+        if (this.#resolveSnapshotPath) {
+            return this.#resolveSnapshotPath(filepath, '.snap');
         }
         return super.resolvePath(filepath);
     }
 }
-_WebdriverIOSnapshotEnvironment_resolveSnapshotPath = new WeakMap();
 export class SnapshotService {
+    #currentFilePath;
+    #currentTestName;
+    #options;
+    #snapshotResults = [];
+    #snapshotClient = new SnapshotClient({
+        isEqual: this.#isEqual.bind(this),
+    });
     constructor(options) {
-        _SnapshotService_instances.add(this);
-        _SnapshotService_currentFilePath.set(this, void 0);
-        _SnapshotService_currentTestName.set(this, void 0);
-        _SnapshotService_options.set(this, void 0);
-        _SnapshotService_snapshotResults.set(this, []);
-        _SnapshotService_snapshotClient.set(this, new SnapshotClient({
-            isEqual: __classPrivateFieldGet(this, _SnapshotService_instances, "m", _SnapshotService_isEqual).bind(this),
-        }));
         const updateSnapshot = (Boolean(process.env.CI) && !options?.updateState)
             ? 'none'
             : options?.updateState
@@ -48,45 +34,54 @@ export class SnapshotService {
             escapeString: false,
             ...options.snapshotFormat
         } : undefined;
-        __classPrivateFieldSet(this, _SnapshotService_options, {
+        this.#options = {
             updateSnapshot,
             snapshotEnvironment: new WebdriverIOSnapshotEnvironment(options?.resolveSnapshotPath),
             ...(snapshotFormatConfig && { snapshotFormat: snapshotFormatConfig })
-        }, "f");
+        };
     }
     get currentFilePath() {
-        return __classPrivateFieldGet(this, _SnapshotService_currentFilePath, "f");
+        return this.#currentFilePath;
     }
     get currentTestName() {
-        return __classPrivateFieldGet(this, _SnapshotService_currentTestName, "f");
+        return this.#currentTestName;
     }
     get client() {
-        return __classPrivateFieldGet(this, _SnapshotService_snapshotClient, "f");
+        return this.#snapshotClient;
     }
     get results() {
-        return __classPrivateFieldGet(this, _SnapshotService_snapshotResults, "f");
+        return this.#snapshotResults;
     }
     async beforeTest(test) {
-        __classPrivateFieldSet(this, _SnapshotService_currentFilePath, test.file, "f");
-        __classPrivateFieldSet(this, _SnapshotService_currentTestName, `${test.parent} > ${test.title}`, "f");
-        await __classPrivateFieldGet(this, _SnapshotService_snapshotClient, "f").setup(test.file, __classPrivateFieldGet(this, _SnapshotService_options, "f"));
+        this.#currentFilePath = test.file;
+        this.#currentTestName = `${test.parent} > ${test.title}`;
+        await this.#snapshotClient.setup(test.file, this.#options);
     }
     async beforeStep(step, scenario) {
         const file = scenario.uri;
         const testName = `${scenario.name} > ${step.text}`;
-        __classPrivateFieldSet(this, _SnapshotService_currentFilePath, file, "f");
-        __classPrivateFieldSet(this, _SnapshotService_currentTestName, testName, "f");
-        await __classPrivateFieldGet(this, _SnapshotService_snapshotClient, "f").setup(file, __classPrivateFieldGet(this, _SnapshotService_options, "f"));
+        this.#currentFilePath = file;
+        this.#currentTestName = testName;
+        await this.#snapshotClient.setup(file, this.#options);
     }
     async after() {
-        if (!__classPrivateFieldGet(this, _SnapshotService_currentFilePath, "f")) {
+        if (!this.#currentFilePath) {
             return;
         }
-        const result = await __classPrivateFieldGet(this, _SnapshotService_snapshotClient, "f").finish(__classPrivateFieldGet(this, _SnapshotService_currentFilePath, "f"));
+        const result = await this.#snapshotClient.finish(this.#currentFilePath);
         if (!result) {
             return;
         }
-        __classPrivateFieldGet(this, _SnapshotService_snapshotResults, "f").push(result);
+        this.#snapshotResults.push(result);
+    }
+    #isEqual(received, expected) {
+        try {
+            expect(received).toBe(expected);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     static initiate(options) {
         if (!service) {
@@ -95,12 +90,3 @@ export class SnapshotService {
         return service;
     }
 }
-_SnapshotService_currentFilePath = new WeakMap(), _SnapshotService_currentTestName = new WeakMap(), _SnapshotService_options = new WeakMap(), _SnapshotService_snapshotResults = new WeakMap(), _SnapshotService_snapshotClient = new WeakMap(), _SnapshotService_instances = new WeakSet(), _SnapshotService_isEqual = function _SnapshotService_isEqual(received, expected) {
-    try {
-        expect(received).toBe(expected);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};

package/lib/softAssert.js

@@ -1,8 +1,8 @@
 export class SoftAssertService {
-    constructor() {
-        this.failureMap = new Map();
-        this.currentTest = null;
-    }
+    static instance;
+    failureMap = new Map();
+    currentTest = null;
+    constructor() { }
     static getInstance() {
         if (!SoftAssertService.instance) {
             SoftAssertService.instance = new SoftAssertService();

package/lib/softAssertService.js

@@ -1,5 +1,7 @@
 import { SoftAssertService } from './softAssert.js';
 export class SoftAssertionService {
+    softAssertService;
+    options;
     constructor(serviceOptions) {
         this.softAssertService = SoftAssertService.getInstance();
         this.options = {

package/lib/utils.js

@@ -7,8 +7,8 @@ import { enhanceError, enhanceErrorBe, numberError } from './util/formatMessage.
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const asymmetricMatcher = typeof Symbol === 'function' && Symbol.for
     ? Symbol.for('jest.asymmetricMatcher')
-    : 1267621;
-export function isAsymmeyricMatcher(expected) {
+    : 0x13_57_a5;
+export function isAsymmetricMatcher(expected) {
     return (typeof expected === 'object' &&
         expected &&
         '$$typeof' in expected &&
@@ -17,7 +17,7 @@ export function isAsymmeyricMatcher(expected) {
         Boolean(expected.asymmetricMatch));
 }
 function isStringContainingMatcher(expected) {
-    return isAsymmeyricMatcher(expected) && ['StringContaining', 'StringNotContaining'].includes(expected.toString());
+    return isAsymmetricMatcher(expected) && ['StringContaining', 'StringNotContaining'].includes(expected.toString());
 }
 const waitUntil = async (condition, isNot = false, { wait = DEFAULT_OPTIONS.wait, interval = DEFAULT_OPTIONS.interval } = {}) => {
     if (wait === 0) {
@@ -108,7 +108,7 @@ export const compareText = (actual, expected, { ignoreCase = false, trim = true,
                 : expect.not.stringContaining(expected.sample?.toString().toLowerCase()));
         }
     }
-    if (isAsymmeyricMatcher(expected)) {
+    if (isAsymmetricMatcher(expected)) {
         const result = expected.asymmetricMatch(actual);
         return {
             value: actual,
@@ -181,7 +181,7 @@ export const compareTextWithArray = (actual, expectedArray, { ignoreCase = false
         if (expected instanceof RegExp) {
             return !!actual.match(expected);
         }
-        if (isAsymmeyricMatcher(expected)) {
+        if (isAsymmetricMatcher(expected)) {
             return expected.asymmetricMatch(actual);
         }
         if (containing) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expect-webdriverio",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "author": "Mykola Grybyk <mykola.grybyk@gmail.com>",
   "description": "WebdriverIO Assertion Library",
   "license": "MIT",
@@ -23,7 +23,7 @@
   "exports": {
     ".": [
       {
-        "types": "./types/standalone.d.ts",
+        "types": "./types/expect-webdriverio.d.ts",
         "import": "./lib/index.js"
       },
       "./lib/index.js"
@@ -33,54 +33,64 @@
         "types": "./jest.d.ts"
       }
     ],
-    "./types": "./types/jest-global.d.ts"
+    "./jasmine": [
+      {
+        "types": "./jasmine.d.ts"
+      }
+    ],
+    "./types": "./types/expect-global.d.ts",
+    "./expect-global": "./types/expect-global.d.ts"
   },
-  "types": "./types/standalone.d.ts",
+  "types": "./types/expect-webdriverio.d.ts",
   "typeScriptVersion": "3.8.3",
   "engines": {
-    "node": ">=18 || >=20 || >=22"
+    "node": ">=20"
   },
   "scripts": {
     "build": "run-s clean compile",
     "clean": "run-p clean:*",
     "clean:build": "rimraf ./lib",
-    "clean:tests": "rimraf test-types/**/node_modules && rimraf test-types/**/dist",
     "compile": "tsc --build tsconfig.build.json",
-    "tsc:root-types": "tsc jasmine.d.ts jest.d.ts",
+    "tsc:root-types": "node types-checks-filter-out-node_modules.js",
     "test": "run-s test:*",
     "test:tsc": "tsc --project tsconfig.json --noEmit",
     "test:lint": "eslint .",
     "test:unit": "vitest --run",
-    "test:types": "node test-types/copy && npm run ts && npm run clean:tests && npm run tsc:root-types",
-    "ts": "run-s ts:*",
-    "ts:default": "cd test-types/default && tsc -p ./tsconfig.json --incremental",
-    "ts:jest": "cd test-types/jest && tsc -p ./tsconfig.json --incremental",
-    "ts:jasmine": "cd test-types/jasmine && tsc -p ./tsconfig.json --incremental",
+    "test:types": "npm run ts && npm run tsc:root-types",
+    "ts": "run-s ts:* ts:*:*",
+    "ts:jest:@jest/global": "cd test-types/jest-@jest_global && tsc --project ./tsconfig.json",
+    "ts:jest:@types-jest": "cd test-types/jest-@types_jest && tsc --project ./tsconfig.json",
+    "ts:mocha": "cd test-types/mocha && tsc --project ./tsconfig.json",
+    "ts:jasmine": "cd test-types/jasmine && tsc --project ./tsconfig.json",
+    "ts:jasmine-async": "cd test-types/jasmine-async && tsc --project ./tsconfig.json",
     "watch": "npm run compile -- --watch",
     "prepare": "husky install"
   },
   "dependencies": {
-    "@vitest/snapshot": "^4.0.12",
+    "@vitest/snapshot": "^4.0.16",
     "deep-eql": "^5.0.2",
     "expect": "^30.2.0",
     "jest-matcher-utils": "^30.2.0"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",
+    "@types/jasmine": "^5.1.8",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
-    "@vitest/coverage-v8": "^4.0.12",
+    "@types/mocha": "^10.0.10",
+    "@jest/globals": "^30.2.0",
+    "@vitest/coverage-v8": "^4.0.16",
     "@wdio/eslint": "^0.1.2",
     "@wdio/types": "^9.20.0",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.2",
     "husky": "^9.1.7",
     "npm-run-all2": "^8.0.4",
-    "release-it": "^19.0.6",
+    "release-it": "^19.1.0",
     "rimraf": "^6.1.2",
     "shelljs": "^0.10.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.12",
-    "webdriverio": "^9.20.1"
+    "vitest": "^4.0.16",
+    "webdriverio": "^9.21.0"
   },
   "peerDependencies": {
     "@wdio/globals": "^9.0.0",

package/types/expect-global.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="./expect-webdriverio.d.ts"/>
+
+/**
+ * Global declaration file for WebdriverIO's Expect library to force the expect.
+ * Required when used in standalone mode (mocha) or to override the one of Jasmine
+ */
+
+//// @ts-expect-error: IDE might flags this one but just does be concerned by it. This way the `tsc:root-types` can pass!
+declare const expect: ExpectWebdriverIO.Expect
+
+declare namespace NodeJS {
+    interface Global {
+        expect: ExpectWebdriverIO.Expect
+    }
+}