Enhanced expect wdio typing

.npmignore

@@ -3,6 +3,7 @@
 !lib/**/*.js
 !types/**/*.d.ts
 !jasmine.d.ts
+!jasmine-wdio-expect-async.d.ts
 !jest.d.ts
 !LICENSE
 !package.json

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)
 

docs/API.md

@@ -111,6 +111,11 @@ When set to `true` (default), the service will automatically assert all soft ass
 
 This is useful if you want full control over when soft assertions are verified or if you want to handle soft assertion failures in a custom way.
 
+### Known limitations
+
+For Jasmine, using `wdio-jasmine-framework` will give a better plug-and-play experiences, else without it, the soft assertion service and custom matchers might not work/be registered correctly.
+Moreover, if Jasmine augmentation is used, the soft assertion function are not exposed in the typing, but could still work depending of your configuration. See [this issue](https://github.com/webdriverio/expect-webdriverio/issues/1893) for more details.
+
 ## Default Options
 
 These default options below are connected to the [`waitforTimeout`](https://webdriver.io/docs/options#waitfortimeout) and [`waitforInterval`](https://webdriver.io/docs/options#waitforinterval) options set in the config.
@@ -667,7 +672,7 @@ await expect(mock).toBeRequestedTimes({ gte: 5, lte: 10 }) // request called at
 
 Checks that mock was called according to the expected options.
 
-Most of the options supports expect/jasmine partial matchers like [expect.objectContaining](https://jestjs.io/docs/en/expect#expectobjectcontainingobject)
+Most of the options supports expect/jasmine partial matchers like [expect.objectContaining](https://jestjs.io/docs/expect#expectobjectcontainingobject)
 
 ##### Usage
 
@@ -858,7 +863,7 @@ await expect(elem).toHaveElementClass(/Container/i)
 
 ## Default Matchers
 
-In addition to the `expect-webdriverio` matchers you can use builtin Jest's [expect](https://jestjs.io/docs/en/expect) assertions or [expect/expectAsync](https://jasmine.github.io/api/3.5/global.html#expect) for Jasmine.
+In addition to the `expect-webdriverio` matchers you can use builtin Jest's [expect](https://jestjs.io/docs/expect) assertions or [expect/expectAsync](https://jasmine.github.io/api/edge/global.html#expect) for Jasmine.
 
 ## Asymmetric Matchers
 

docs/Extend.md → docs/CustomMatchers.md

@@ -2,8 +2,8 @@
 
 Similar to how `expect-webdriverio` extends Jasmine/Jest matchers it's possible to add custom matchers.
 
-- Jasmine see [custom matchers](https://jasmine.github.io/2.5/custom_matcher.html) doc
-- Everyone else see Jest's [expect.extend](https://jestjs.io/docs/en/expect#expectextendmatchers)
+- [Jasmine](https://jasmine.github.io/) see [custom matchers](https://jasmine.github.io/tutorials/custom_matchers) doc
+- Everyone else see [Jest's expect.extend](https://jestjs.io/docs/expect#expectextendmatchers)
 
 Custom matchers should be added in wdio `before` hook
 

docs/Examples.md

@@ -50,7 +50,7 @@ describe('suite', () => {
 WebdriverIO test runner
 - Mocha https://github.com/mgrybyk/webdriverio-devtools
 - Cucumber https://gitlab.com/bar_foo/wdio-cucumber-typescript
-- Jasmine https://github.com/mgrybyk/wdio-jasmine-boilerplate
+- Jasmine https://github.com/webdriverio/jasmine-boilerplate
 
 Standalone
 - Jest https://github.com/erwinheitzman/jest-webdriverio-standalone-boilerplate

docs/Framework.md

@@ -0,0 +1,261 @@
+# Expect-WebDriverIO Framework
+
+Expect-WebDriverIO is inspired by [`expect`](https://www.npmjs.com/package/expect) but also extends it. Therefore, we can use everything provided by the expect API with some WebDriverIO enhancements.
+  - Note: Yes, this is a package of Jest but it is usable without Jest.
+
+## Compatibility
+
+We can pair `expect-webdriverio` with [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), and [Jasmine](https://jasmine.github.io/) and even [Cucumber](https://www.npmjs.com/package/@cucumber/cucumber)
+
+It is highly recommended to use it with a [WDIO Testrunner](https://webdriver.io/docs/clioptions) which provides additional auto-configuration for a plug-and-play experience.
+
+When used <u>**outside of [WDIO Testrunner](https://webdriver.io/docs/clioptions)**</u>, types need to be added to your [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html), and some additional configuration for WDIO matchers, soft assertions, and snapshot service is required.
+
+### Jest
+We can use `expect-webdriverio` with [Jest](https://jestjs.io/) using [`@jest/globals`](https://www.npmjs.com/package/@jest/globals) alone (preferred) and optionally [`@types/jest`](https://www.npmjs.com/package/@types/jest) (which has global ambient support).
+  - Note: Jest maintainers do not support [`@types/jest`](https://www.npmjs.com/package/@types/jest). If this library gets out of date or has problems, support might be dropped.
+  - Note: With Jest, the matchers `toMatchSnapshot` and `toMatchInlineSnapshot` are overloaded. To resolve the types correctly, `expect-webdriverio/jest` must be last.
+
+#### With `@jest/globals`
+When paired only with [`@jest/globals`](https://www.npmjs.com/package/@jest/globals), we should `import` the `expect` function from `expect-webdriverio`.
+
+```ts
+import { expect } from 'expect-webdriverio'
+import { describe, it, expect as jestExpect } from '@jest/globals'
+
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expect(browser).toHaveUrl('https://example.com')
+    })
+})        
+```
+
+No `types` are expected in `tsconfig.json`.
+Optionally, to avoid needing `import { expect } from 'expect-webdriverio'`, you can use the following:
+```json
+{
+  "compilerOptions": {
+    "types": ["expect-webdriverio/expect-global"]
+  }
+}
+```   
+##### Augmenting `@jest/globals` JestMatchers
+Multiple attempts were made to augment `@jest/globals` to support `expect-webdriverio` matchers directly on JestMatchers. However, no namespace is available to augment it; therefore, only module augmentation can be used. This method does not allow adding matchers with the `extends` keyword; instead, they need to be added directly in the interface of the module declaration augmentation, which would create a lot of code duplication.
+
+This [Jest issue](https://github.com/jestjs/jest/issues/12424) seems to target this problem, but it is still in progress.
+
+
+#### With `@types/jest`
+When also paired with [`@types/jest`](https://www.npmjs.com/package/@types/jest), no imports are required. Global ambient types are already defined correctly and you can simply use Jest's `expect` directly.
+
+If you are NOT using WDIO Testrunner, some prerequisite configuration is required.
+
+Option 1: Replace the expect globally with the `expect-webdriverio` one:
+```ts
+import { expect } from "expect-webdriverio";
+(globalThis as any).expect = expect;
+```
+
+Option 2: Reconfigure Jest's expect with the custom matchers and the soft assertion:
+```ts
+// Configure the custom matchers:
+import { expect } from "@jest/globals";
+import { matchers } from "expect-webdriverio";
+
+beforeAll(async () => { 
+    expect.extend(matchers as Record<string, any>);
+});
+```
+
+[Optional] For the soft assertion, the `createSoftExpect` is currently not correctly exposed but the below works:
+```ts
+// @ts-ignore
+import * as createSoftExpect from "expect-webdriverio/lib/softExpect";
+
+beforeAll(async () => {
+  Object.defineProperty(expect, "soft", {
+    value: <T = unknown>(actual: T) => createSoftExpect.default(actual),
+  });
+
+  // Add soft assertions utility methods
+  Object.defineProperty(expect, "getSoftFailures", {
+    value: (testId?: string) => SoftAssertService.getInstance().getFailures(testId),
+  });
+
+  Object.defineProperty(expect, "assertSoftFailures", {
+    value: (testId?: string) => SoftAssertService.getInstance().assertNoFailures(testId),
+  });
+
+  Object.defineProperty(expect, "clearSoftFailures", {
+    value: (testId?: string) => SoftAssertService.getInstance().clearFailures(testId),
+  });
+});
+```
+
+Then as shown below, no imports are required and we can use WDIO matchers directly on Jest's `expect`:
+```ts
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expect(browser).toHaveUrl('https://example.com')
+    })
+})     
+```
+
+Expected in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+        "@types/jest",
+        "expect-webdriverio/jest" // Must be last for overloaded matchers `toMatchSnapshot` and `toMatchInlineSnapshot` 
+      ]
+  }
+}
+```
+
+### Mocha
+When paired with [Mocha](https://mochajs.org/), it can be used without (standalone) or with [`chai`](https://www.chaijs.com/) (or any other assertion library).
+
+#### Standalone
+No import is required; everything is set globally.
+
+```ts
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expect(browser).toHaveUrl('https://example.com')
+    })
+})     
+```
+
+Expected in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+        "@types/mocha",
+        "expect-webdriverio/expect-global"
+      ]
+  }
+}
+```
+
+#### Chai
+`expect-webdriverio` can coexist with the [Chai](https://www.chaijs.com/) assertion library by importing both libraries explicitly.
+See also this [documentation](https://webdriver.io/docs/assertion/#migrating-from-chai).
+
+### Jasmine
+When paired with [Jasmine](https://jasmine.github.io/), [`@wdio/jasmine-framework`](https://www.npmjs.com/package/@wdio/jasmine-framework) is also required to configure it correctly, as it needs to force `expect` to be `expectAsync` and also register the WDIO matchers with `addAsyncMatcher` since `expect-webdriverio` only supports the Jest-style `expect.extend` version.
+
+The types `expect-webdriverio/jasmine` are still offered but are subject to removal or being moved into `@wdio/jasmine-framework`. The usage of `expectAsync` is also subject to future removal.
+
+#### Jasmine `expectAsync`
+When not using `@wdio/globals/types` or having `@types/jasmine` before it, the Jasmine expect is shown as the global ambient type. Therefore, when also defining `expect-webdriverio/jasmine`, we can use WDIO custom matchers on the `expectAsync`.
+  - Note: Without `@wdio/jasmine-framework`, matchers will need to be registered manually.
+
+```ts
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expectAsync(browser).toHaveUrl('https://example.com')
+
+        await expectAsync(true).toBe(true)
+    })
+})     
+```
+
+Expected in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+        "@types/jasmine",
+        "expect-webdriverio/jasmine"
+      ]
+  }
+}
+```
+
+#### Global `expectAsync` force as `expect`
+When the global ambiant is the `expect` of wdio but forced to be `expectAsync` under the hood, like when using `@wdio/jasmine-framework`, then even the basic matchers need to be awaited 
+
+```ts
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expect(browser).toHaveUrl('https://example.com')
+
+        // Even basic matchers requires expect since they are promises underneath
+        await expect(true).toBe(true)
+    })
+})     
+```
+
+Expected in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@wdio/globals/types",
+      "@wdio/jasmine-framework",
+      "@types/jasmine",
+      "expect-webdriverio/jasmine-wdio-expect-async", // Force expect to return Promises
+      ]
+  }
+}
+```
+
+#### `expect` of `expect-webdriverio`
+It is preferable to use the `expect` from `expect-webdriverio` to guarantee future compatibility. 
+
+```ts
+// Required if we do not force the 'expect-webdriverio' expect globally with `"expect-webdriverio/expect-global"`
+import { expect as wdioExpect } from 'expect-webdriverio'
+
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await wdioExpect(browser).toHaveUrl('https://example.com')
+
+        // No required await
+        wdioExpect(true).toBe(true)        
+    })
+})     
+
+
+Expected in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+        "@types/jasmine",
+        // "expect-webdriverio/expect-global", // Optional to have the global ambient expect the one of wdio
+      ]
+  }
+}
+```
+
+
+#### Asymmetric matchers
+Asymmetric matchers have limited support. Even though `jasmine.stringContaining` does not produce a typing error, it may not work even with `@wdio/jasmine-framework`. However, the example below should work:
+
+```ts
+describe('My tests', async () => {
+
+    it('should verify my browser to have the expected url', async () => {
+        await expectAsync(browser).toHaveUrl(wdioExpect.stringContaining('WebdriverIO'))
+    })
+})     
+```
+
+
+### Jest & Jasmine Augmentation Notes
+
+If you are already using Jest or Jasmine globally, using `import { expect } from 'expect-webdriverio'` is the most compatible approach, even though augmentation exists.
+It is recommended to build your project using this approach instead of relying on augmentation, to ensure future compatibility and avoid augmentation limitations. See [this issue](https://github.com/webdriverio/expect-webdriverio/issues/1893) for more information.
+
+### Cucumber
+
+More details to come. In short, when paired with `@wdio/cucumber-framework`, you can use WDIO's expect with Cucumber and even [Gherkin](https://www.npmjs.com/package/@cucumber/gherkin).

docs/Types.md

@@ -1,14 +1,17 @@
+# Types Definition
 ## TypeScript
 
 If you are using the [WDIO Testrunner](https://webdriver.io/docs/clioptions) everything will be automatically setup. Just follow the [setup guide](https://webdriver.io/docs/typescript#framework-setup) from the docs. However if you run WebdriverIO with a different testrunner or in a simple Node.js script you will need to add `expect-webdriverio` to `types` in the `tsconfig.json`.
 
-- `"expect-webdriverio"` for everyone except of Jasmine/Jest users.
-- `"expect-webdriverio/jasmine"` Jasmine
-- `"expect-webdriverio/jest"` Jest
+- `"expect-webdriverio"` for everyone except Jasmine/Jest users.
+- `"expect-webdriverio/jasmine"` for [Jasmine](https://jasmine.github.io/)
+- `"expect-webdriverio/jest"` for [Jest](https://jestjs.io/)
+- `"expect-webdriverio/expect-global"` // Optional, if you wish to use expect of `expect-webdriverio` globally without explicit import
+  - Note: Same as the former `"expect-webdriverio/types"`, now deprecated!
 
 ## JavaScript (VSCode)
 
-It's required to create `jsconfig.json` in project root and refer to the type definitions to make autocompletion work in vanilla js.
+It's required to create [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig) in project root and refer to the type definitions to make autocompletion work in vanilla js.
 
 ```json
 {
@@ -19,3 +22,15 @@ It's required to create `jsconfig.json` in project root and refer to the type de
   ]
 }
 ```
+
+## Jasmine special case
+[Jasmine](https://jasmine.github.io/) is different from [Jest](https://jestjs.io/) or the standard `expect` definition since it supports promises using `expectAsync` which makes it quite challenging.
+
+Even though this library by itself is not fully Jasmine-ready, it offers the types of the matcher only on the `AsyncMatcher` since using `jasmine.expect` does not work out-of-the-box. However, if you are pulling on the `expect` of `expect-webdriverio`, you will be able to have the WebDriverIO matcher types on `expect`. 
+
+Support of `expectAsync` keyword is subject to change and may be dropped in the future!
+
+### Dependency on `@wdio/jasmine-framework`
+As mentioned above, this library alone is not working with Jasmine. It is required to manually do some tweaks, or it is strongly recommended to also pair it with `@wdio/jasmine-framework`. See [Framework.md](Framework.md) for more information.
+
+When using [`@wdio/jasmine-framework`](https://www.npmjs.com/package/@wdio/jasmine-framework), since it replaces `jasmine.expect` with `jasmine.expectAsync`, then matchers are usable on the keyword `expect`, but still typing on `expect` directly from [Jasmine](https://jasmine.github.io/) namespace is not supported as of today!

jasmine-wdio-expect-async.d.ts

@@ -0,0 +1,23 @@
+/// <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>
+    }
+}