fix: .not should also wait for conditions (Breaking changes of issue 1982) (#2014)

* Revert "fix: isNot was not always properly considered (#1983)"

This reverts commit 084d4a6.

* Documents clearly today `.not` behavior

* Keep useful changes

* Add clear waitUntil UT + add integrated test representing the issue

* Keep relevant comment

* More stable tests

 sometimes when run too fast, it triggers conditions one more time than expected

* Apply suggestions from code review

* Update test/matchers.test.ts

Author: dprevost-LMI

docs/API.md

@@ -880,6 +880,29 @@ await expect(elem).toHaveElementClass(/Container/i)
 
 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.
 
+## Modifiers
+
+WebdriverIO supports usage of modifiers as `.not` and it will wait until the reverse condition is meet
+
+```ts
+// Wait until the element is no longer present
+await expect(element).not.toBeDisplayed()
+
+// Wait until the text is no more 'some title'
+await expect(browser).not.toHaveTitle('some title')
+```
+
+In case immediate assertion is required, use `{ wait: 0 }`
+```ts
+// Ensure element is not present right now
+await expect(element).not.toBeDisplayed({ wait: 0 })
+
+// Ensure the text is not 'some title' right now
+await expect(browser).not.toHaveTitle('some title', { wait: 0 })
+```
+
+Note: You can pair `.not` with asymmetric matchers, but to enable the wait-until behavior, `.not` must be used directly on the `expect()` call. 
+
 ## Asymmetric Matchers
 
 WebdriverIO supports usage of asymmetric matchers wherever you compare text values, e.g.:

src/matchers/browser/toHaveClipboardText.ts

@@ -10,6 +10,7 @@ export async function toHaveClipboardText(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'clipboard text', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -27,7 +28,7 @@ export async function toHaveClipboardText(
             .catch((err) => log.warn(`Couldn't set clipboard permissions: ${err}`))
         actual = await browser.execute(() => window.navigator.clipboard.readText())
         return compareText(actual, expectedValue, options).result
-    }, options)
+    }, isNot, options)
 
     const message = enhanceError('browser', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {

src/matchers/browser/toHaveTitle.ts

@@ -6,6 +6,7 @@ export async function toHaveTitle(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'title', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -19,7 +20,7 @@ export async function toHaveTitle(
         actual = await browser.getTitle()
 
         return compareText(actual, expectedValue, options).result
-    }, options)
+    }, isNot, options)
 
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {

src/matchers/browser/toHaveUrl.ts

@@ -6,6 +6,7 @@ export async function toHaveUrl(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'url', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -19,7 +20,7 @@ export async function toHaveUrl(
         actual = await browser.getUrl()
 
         return compareText(actual, expectedValue, options).result
-    }, options)
+    }, isNot, options)
 
     const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {

src/matchers/element/toHaveAttribute.ts

@@ -27,6 +27,7 @@ async function conditionAttrAndValue(el: WebdriverIO.Element, attribute: string,
 }
 
 export async function toHaveAttributeAndValue(received: WdioElementMaybePromise, attribute: string, value: string | RegExp | WdioAsymmetricMatcher<string>, options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS) {
+    const isNot = this.isNot
     const { expectation = 'attribute', verb = 'have' } = this
 
     let el = await received?.getElement()
@@ -37,7 +38,7 @@ export async function toHaveAttributeAndValue(received: WdioElementMaybePromise,
         attr = result.values
 
         return result.success
-    }, options)
+    }, isNot, options)
 
     const expected = wrapExpectedWithArray(el, attr, value)
     const message = enhanceError(el, expected, attr, this, verb, expectation, attribute, options)
@@ -48,8 +49,9 @@ export async function toHaveAttributeAndValue(received: WdioElementMaybePromise,
     } as ExpectWebdriverIO.AssertionResult
 }
 
-async function toHaveAttributeFn(received: WdioElementMaybePromise, attribute: string, options: ExpectWebdriverIO.StringOptions) {
-    const { expectation = 'attribute', verb = 'have', isNot } = this
+async function toHaveAttributeFn(received: WdioElementMaybePromise, attribute: string) {
+    const isNot = this.isNot
+    const { expectation = 'attribute', verb = 'have' } = this
 
     let el = await received?.getElement()
 
@@ -58,9 +60,9 @@ async function toHaveAttributeFn(received: WdioElementMaybePromise, attribute: s
         el = result.el as WebdriverIO.Element
 
         return result.success
-    }, options)
+    }, isNot, {})
 
-    const message = enhanceError(el, !isNot, pass, this, verb, expectation, attribute, options)
+    const message = enhanceError(el, !isNot, pass, this, verb, expectation, attribute, {})
 
     return {
         pass,
@@ -84,7 +86,7 @@ export async function toHaveAttribute(
         // Name and value is passed in e.g. el.toHaveAttribute('attr', 'value', (opts))
         ? await toHaveAttributeAndValue.call(this, received, attribute, value, options)
         // Only name is passed in e.g. el.toHaveAttribute('attr')
-        : await toHaveAttributeFn.call(this, received, attribute, options)
+        : await toHaveAttributeFn.call(this, received, attribute)
 
     await options.afterAssertion?.({
         matcherName: 'toHaveAttribute',

src/matchers/element/toHaveChildren.ts

@@ -35,6 +35,7 @@ export async function toHaveChildren(
     expectedValue?: number | ExpectWebdriverIO.NumberOptions,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'children', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -55,7 +56,7 @@ export async function toHaveChildren(
         children = result.values
 
         return result.success
-    }, { ...numberOptions, ...options })
+    }, isNot, { ...numberOptions, ...options })
 
     const error = numberError(numberOptions)
     const expectedArray = wrapExpectedWithArray(el, children, error)

src/matchers/element/toHaveClass.ts

@@ -42,6 +42,7 @@ export async function toHaveElementClass(
     expectedValue: string | RegExp | Array<string | RegExp> | WdioAsymmetricMatcher<string>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'class', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -61,7 +62,7 @@ export async function toHaveElementClass(
         attr = result.values
 
         return result.success
-    }, options)
+    }, isNot, options)
 
     const message = enhanceError(el, wrapExpectedWithArray(el, attr, expectedValue), attr, this, verb, expectation, '', options)
     const result: ExpectWebdriverIO.AssertionResult = {

src/matchers/element/toHaveComputedLabel.ts

@@ -26,6 +26,7 @@ export async function toHaveComputedLabel(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string> | Array<string | RegExp>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'computed label', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -45,6 +46,7 @@ export async function toHaveComputedLabel(
 
             return result.success
         },
+        isNot,
         options
     )
 

src/matchers/element/toHaveComputedRole.ts

@@ -26,6 +26,7 @@ export async function toHaveComputedRole(
     expectedValue: string | RegExp | WdioAsymmetricMatcher<string> | Array<string | RegExp>,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
+    const isNot = this.isNot
     const { expectation = 'computed role', verb = 'have' } = this
 
     await options.beforeAssertion?.({
@@ -45,6 +46,7 @@ export async function toHaveComputedRole(
 
             return result.success
         },
+        isNot,
         options
     )
 

src/matchers/element/toHaveElementProperty.ts

@@ -42,7 +42,8 @@ export async function toHaveElementProperty(
     value?: string | RegExp | WdioAsymmetricMatcher<string> | null,
     options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
 ) {
-    const { expectation = 'property', verb = 'have', isNot } = this
+    const isNot = this.isNot
+    const { expectation = 'property', verb = 'have' } = this
 
     await options.beforeAssertion?.({
         matcherName: 'toHaveElementProperty',
@@ -60,6 +61,7 @@ export async function toHaveElementProperty(
 
             return result.success
         },
+        isNot,
         options
     )