Document more findings around soft assertions

Doc soft limitation

Author: dprevost-LMI

docs/Framework.md

@@ -68,10 +68,33 @@ beforeAll(async () => {
     expect.extend(matchers as Record<string, any>);
 });
 ```
-For the soft assertion, it needs to expose the `createSoftExpect` first.
 
+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),
+  });
+});
+```
 
-As shown below, no imports are required and we can use WDIO matchers directly on Jest's `expect`:
+Then as shown below, no imports are required and we can use WDIO matchers directly on Jest's `expect`:
 ```ts
 describe('My tests', async () => {
 

src/softExpect.ts

@@ -87,7 +87,6 @@ const createSoftMatcher = <T>(
                 expectChain = expectChain.rejects
             }
 
-            // TODO ddprevost might need to review this await since not all expect requires to be awaited
             return await ((expectChain as unknown) as Record<string, (...args: unknown[]) => ExpectWebdriverIO.AsyncAssertionResult>)[matcherName](...args)
 
         } catch (error) {

test/softAssertions.test.ts

@@ -7,7 +7,7 @@ vi.mock('@wdio/globals')
 
 describe('Soft Assertions', () => {
     // Setup a mock element for testing
-    let el: any
+    let el: ChainablePromiseElement
 
     beforeEach(async () => {
         el = $('sel')
@@ -106,6 +106,20 @@ describe('Soft Assertions', () => {
             // Should be no failures now
             expect(expectWdio.getSoftFailures().length).toBe(0)
         })
+
+        // TODO: Soft are currently not supporting basic matchers like toBe or toEqual.To fix one day!
+        it.skip('should support basic text matching', async () => {
+            const softService = SoftAssertService.getInstance()
+            softService.setCurrentTest('test-7', 'test name', 'test file')
+            const text = await el.getText()
+
+            expectWdio.soft(text).toEqual('!Actual Text')
+
+            const failures = expectWdio.getSoftFailures()
+            expect(failures.length).toBe(1)
+            expect(failures[0].matcherName).toBe('toHaveText')
+        })
+
     })
 
     describe('SoftAssertService hooks', () => {

types/expect-webdriverio.d.ts

@@ -418,6 +418,7 @@ interface WdioCustomExpect {
      * Creates a soft assertion wrapper around standard expect
      * Soft assertions record failures but don't throw errors immediately
      * All failures are collected and reported at the end of the test
+     * Note: Until fixed, soft only support wdio custom matchers, and not the `expect` library matchers. Moreover, it is always returns a Promise.
      */
     soft<T = unknown>(actual: T): T extends PromiseLike<unknown> ? ExpectWebdriverIO.MatchersAndInverse<Promise<void>, T> & ExpectWebdriverIO.PromiseMatchers<T> : ExpectWebdriverIO.MatchersAndInverse<void, T>;