expect-webdriverio 1.3.1 → 2.0.1

package/README.md

@@ -1,8 +1,8 @@
 # expect-webdriverio
 
-[![Build Status](https://travis-ci.org/webdriverio/expect-webdriverio.svg?branch=master)](https://travis-ci.org/webdriverio/expect-webdriverio) [![codecov](https://codecov.io/gh/webdriverio/expect-webdriverio/branch/master/graph/badge.svg)](https://codecov.io/gh/webdriverio/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)
 
-###### [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/Extend.md)
 
 > [WebdriverIO](https://webdriver.io/) Assertion library inspired by [expect](https://www.npmjs.com/package/expect)
 
@@ -24,7 +24,7 @@ NOTE: [WebdriverIO](https://github.com/webdriverio/webdriverio) `v5.16.11` or hi
 
 In your `wdio.conf.js`
 ```js
-beforeSession () { // before hook works as well
+before () { // not needed in WebdriverIO v6
     require('expect-webdriverio')
 },
 ```
@@ -39,464 +39,7 @@ See more [Examples](docs/Examples.md)
 
 ## API
 
-See available [Matchers](https://github.com/webdriverio/expect-webdriverio/blob/master/types/expect-webdriverio.d.ts#L64)
-
-Besides of 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.
-
-## Default Options
-
-```js
-{
-    wait: 2000, // ms to wait for expectation to succeed
-    interval: 100, // interval between attempts
-}
-```
-
-Set options like this:
-```js
-beforeSession () { // before hook works as well
-    require('expect-webdriverio').setOptions({ wait: 5000 })
-},
-```
-
-### Matcher Options
-
-Every matcher can take several options that allows you to modify the assertion:
-
-##### Command Options
-
-| Name | Type | Details |
-| ---- | ---- | ------- |
-| <code><var>wait</var></code> | number | time in ms to wait for expectation to succeed. Default: `3000` |
-| <code><var>interval</var></code> | number | interval between attempts. Default: `100` |
-| <code><var>message</var></code> | string | user message to prepend before assertion error |
-
-##### String Options
-
-This options can be applied in addition to the command options when strings are being asserted.
-
-| Name | Type | Details |
-| ---- | ---- | ------- |
-| <code><var>ignoreCase</var></code> | boolean | apply `toLowerCase` to both actual and expected values |
-| <code><var>trim</var></code> | boolean | apply `trim` to actual value |
-| <code><var>containing</var></code> | boolean | expect actual value to contain expected value, otherwise strict equal. |
-| <code><var>asString</var></code> | boolean | might be helpful to force converting property value to string |
-
-##### Number Options
-
-This options can be applied in addition to the command options when numbers are being asserted.
-
-| Name | Type | Details |
-| ---- | ---- | ------- |
-| <code><var>eq</var></code> | number | equals |
-| <code><var>lte</var></code> | number | less then equals |
-| <code><var>gte</var></code> | number | greater than or equals |
-
-## Browser Matchers
-
-### toHaveUrl
-
-Checks if browser is on a specific page.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-expect(browser).toHaveUrl('https://webdriver.io')
-```
-
-### toHaveUrlContaining
-
-Checks if browser is on a specific page and contains the given value in URL.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-expect(browser).toHaveUrlContaining('webdriver.io')
-```
-
-### toHaveTitle
-
-Checks if website has a specific title.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js')
-```
-
-### toHaveTitleContaining
-
-Checks if website has a specific title that contains the given value.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-expect(browser).toHaveTitleContaining('Next-gen browser and mobile automation test framework')
-```
-
-## Element Matchers
-
-### toBeDisplayed
-
-Calls [`isDisplayed`](/docs/api/element/isDisplayed.html) on given element.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toBeDisplayed()
-```
-
-### toBeVisible
-
-Same as `toBeDisplayed`.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toBeVisible()
-```
-
-### toExist
-
-Calls [`isExisting`](/docs/api/element/isExisting.html) on given element.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toExist()
-```
-
-### toBePresent
-
-Same as `toExist`.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toBePresent()
-```
-
-### toBeExisting
-
-Same as `toExist`.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toBeExisting()
-```
-
-### toBeFocused
-
-Checks if element has focus. This assertion only works in a web context.
-
-##### Usage
-
-```js
-const elem = $('#someElem')
-expect(elem).toBeFocused()
-```
-
-### toHaveAttribute
-
-Checks if an element has a certain attribute with a specific value.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveAttribute('class', 'form-control')
-```
-
-### toHaveAttr
-
-Same as `toHaveAttribute`.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveAttr('class', 'form-control')
-```
-
-### toHaveAttributeContaining
-
-Checks if an element has a certain attribute that contains a value.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveAttributeContaining('class', 'form')
-```
-
-### toHaveAttrContaining
-
-Same as `toHaveAttributeContaining`.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveAttrContaining('class', 'form')
-```
-
-### toHaveElementClass
-
-Checks if an element has a certain class name.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveElementClass('form-control', { message: 'Not a form control!', })
-```
-
-### toHaveElementClassContaining
-
-Checks if an element has a certain class name that contains provided value.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveElementClassContaining('form')
-```
-
-### toHaveElementProperty
-
-Checks if an element has a certain property.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toHaveElementProperty('height', 23)
-expect(elem).not.toHaveElementProperty('height', 0)
-```
-
-### toHaveValue
-
-Checks if an input element has a certain value.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveValue('user', { ignoreCase: true })
-```
-
-### toHaveValueContaining
-
-Checks if an input element contains a certain value.
-
-##### Usage
-
-```js
-const myInput = $('input')
-expect(myInput).toHaveValueContaining('us')
-```
-
-### toBeClickable
-
-Checks if an element can be clicked by calling [`isClickable`](/docs/api/element/isClickable.html) on the element.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeClickable()
-```
-
-### toBeDisabled
-
-Checks if an element is disabled by calling [`isEnabled`](/docs/api/element/isEnabled.html) on the element.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeDisabled()
-// same as
-expect(elem).not.toBeEnabled()
-```
-
-### toBeEnabled
-
-Checks if an element is enabled by calling [`isEnabled`](/docs/api/element/isEnabled.html) on the element.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeEnabled()
-// same as
-expect(elem).not.toBeDisabled()
-```
-
-### toBeSelected
-
-Checks if an element is enabled by calling [`isSelected`](/docs/api/element/isSelected.html) on the element.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeSelected()
-```
-
-### toBeChecked
-
-Same as `toBeSelected`.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeChecked()
-```
-
-### toHaveHref
-
-Checks if link element has a specific link target.
-
-##### Usage
-
-```js
-const link = $('a')
-expect(link).toHaveHref('https://webdriver.io')
-```
-
-### toHaveLink
-
-Same as `toHaveHref`.
-
-##### Usage
-
-```js
-const link = $('a')
-expect(link).toHaveLink('https://webdriver.io')
-```
-
-### toHaveHrefContaining
-
-Checks if link element contains a specific link target.
-
-##### Usage
-
-```js
-const link = $('a')
-expect(link).toHaveHrefContaining('webdriver.io')
-```
-
-### toHaveLinkContaining
-
-Same as `toHaveHrefContaining`.
-
-##### Usage
-
-```js
-const link = $('a')
-expect(link).toHaveLinkContaining('webdriver.io')
-```
-
-### toHaveId
-
-Checks if element has a specific `id` attribute.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toHaveId('elem')
-```
-
-### toHaveText
-
-Checks if element has a specific text.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-const elem = $('.tagline')
-expect(elem).toHaveText('Next-gen browser and mobile automation test framework for Node.js')
-```
-
-### toHaveTextContaining
-
-Checks if element contains a specific text.
-
-##### Usage
-
-```js
-browser.url('https://webdriver.io/')
-const elem = $('.tagline')
-expect(elem).toHaveTextContaining('browser and mobile automation test framework')
-```
-
-### toBeDisplayedInViewport
-
-Checks if an element is within the viewport by calling [`isDisplayedInViewport`](/docs/api/element/isDisplayedInViewport.html) on the element.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeDisplayedInViewport()
-```
-
-### toBeVisibleInViewport
-
-Same as `toBeDisplayedInViewport`.
-
-##### Usage
-
-```js
-const elem = $('#elem')
-expect(elem).toBeVisibleInViewport()
-```
-
-### toHaveChildren
-
-Checks amount of the element's children by calling `element.$('./*')` command.
-
-##### Usage
-
-```js
-const list = $('ul')
-expect(list).toHaveChildren() // the list has at least one item
-// same as
-expect(list).toHaveChildren({ gte: 1 })
-
-expect(list).toHaveChildren(3) // the list has 3 items
-// same as 
-expect(list).toHaveChildren({ eq: 3 })
-```
-
-### toBeElementsArrayOfSize
-
-Checks amount of fetched elements using [`$$`](/docs/api/browser/$$.html) command.
-
-##### Usage
-
-```js
-const listItems = $$('ul>li')
-expect(listItems).toBeElementsArrayOfSize(5) // 5 items in the list
-
-expect(listItems).toBeElementsArrayOfSize({ lte: 10 })
-// same as
-assert.ok(listItems.length <= 10)
-```
+Please see [API doc](docs/API.md)
 
 ## Error messages
 

package/jasmine.d.ts

@@ -2,5 +2,5 @@
 
 declare module jasmine {
     interface Matchers<T> extends ExpectWebdriverIO.Matchers<any, T> {}
-    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.Matchers<any, T> {}
+    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.Matchers<Promise<void>, T> {}
 }

package/lib/addMatchers.js

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addMatchers = exports.loadExpect = exports.isJasmine = void 0;
 let expectLib;
-exports.isJasmine = () => {
+const isJasmine = () => {
     return Boolean(global.jasmine && global.expect && global.expectAsync && global.jasmine.getEnv && global.jasmine.addMatchers && global.jasmine.addAsyncMatchers);
 };
-exports.loadExpect = () => {
+exports.isJasmine = isJasmine;
+const loadExpect = () => {
     try {
         return expectLib = require('expect');
     }
@@ -13,7 +14,8 @@ exports.loadExpect = () => {
         return console.error('Failed to load expect package. Make sure it has been installed: npm i expect');
     }
 };
-exports.addMatchers = () => {
+exports.loadExpect = loadExpect;
+const addMatchers = () => {
     if (global.expect === undefined) {
         if (!exports.loadExpect()) {
             return;
@@ -43,3 +45,4 @@ exports.addMatchers = () => {
         expectLib.addAsyncMatchers({ ...matchers });
     });
 };
+exports.addMatchers = addMatchers;

package/lib/matchers/element/toHaveElementProperty.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toHaveProperty = exports.toHaveElementProperty = exports.toHaveElementPropertyFn = void 0;
+exports.toHaveElementProperty = exports.toHaveElementPropertyFn = void 0;
 const utils_1 = require("../../utils");
 const expectAdapter_1 = require("../../util/expectAdapter");
 async function condition(el, property, value, options = {}) {
@@ -41,7 +41,7 @@ function toHaveElementPropertyFn(received, property, value, options = {}) {
         }
         return {
             pass,
-            message: () => message
+            message: () => message,
         };
     });
 }
@@ -50,8 +50,3 @@ function toHaveElementProperty(...args) {
     return expectAdapter_1.runExpect.call(this, toHaveElementPropertyFn, args);
 }
 exports.toHaveElementProperty = toHaveElementProperty;
-function toHaveProperty(...args) {
-    console.warn('expect(...).toHaveProperty is deprecated. Use toHaveElementProperty instead.');
-    return expectAdapter_1.runExpect.call(this, toHaveElementPropertyFn, args);
-}
-exports.toHaveProperty = toHaveProperty;

package/lib/matchers/element/toHaveText.js

@@ -5,6 +5,9 @@ const utils_1 = require("../../utils");
 const expectAdapter_1 = require("../../util/expectAdapter");
 async function condition(el, text, options) {
     const actualText = await el.getText();
+    if (Array.isArray(text)) {
+        return utils_1.compareTextWithArray(actualText, text, options);
+    }
     return utils_1.compareText(actualText, text, options);
 }
 function toHaveTextFn(received, text, options = {}) {

package/lib/matchers/mock/toBeRequested.js

@@ -1,23 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toBeRequested = void 0;
-const utils_1 = require("../../utils");
+const toBeRequestedTimes_1 = require("./toBeRequestedTimes");
 const expectAdapter_1 = require("../../util/expectAdapter");
 function toBeRequestedFn(received, options = {}) {
-    const isNot = this.isNot || false;
-    const { expectation = `called`, verb = 'be' } = this;
-    return browser.call(async () => {
-        let actual;
-        const pass = await utils_1.waitUntil(async () => {
-            actual = received.calls.length;
-            return actual > 0;
-        }, isNot, options);
-        const message = utils_1.enhanceError('mock', 0, actual, this, verb, expectation, '', options);
-        return {
-            pass,
-            message: () => message
-        };
-    });
+    return toBeRequestedTimes_1.toBeRequestedTimes.call({ ...(this || {}), expectation: 'called' }, received, { ...options, gte: 1 });
 }
 function toBeRequested(...args) {
     return expectAdapter_1.runExpect.call(this, toBeRequestedFn, args);

package/lib/matchers/mock/toBeRequestedTimes.js

@@ -1,21 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toBeRequestedTimes = void 0;
+exports.toBeRequestedTimes = exports.toBeRequestedTimesFn = void 0;
 const utils_1 = require("../../utils");
 const expectAdapter_1 = require("../../util/expectAdapter");
 const formatMessage_1 = require("../../util/formatMessage");
 function toBeRequestedTimesFn(received, times = {}, options = {}) {
     const isNot = this.isNot || false;
     const { expectation = `called${typeof times === 'number' ? ' ' + times : ''} time${times !== 1 ? 's' : ''}`, verb = 'be' } = this;
-    const eq = typeof times === 'number' ? times : times.eq;
-    const gte = typeof times === 'number' ? 1 : (times.gte || 1);
-    const lte = typeof times === 'number' ? 0 : (times.lte || 0);
+    if (typeof times === 'number') {
+        options.eq = times;
+    }
+    else if (typeof times === 'object') {
+        options = { ...options, ...times };
+    }
+    const eq = options.eq;
+    const gte = options.gte || 1;
+    const lte = options.lte || 0;
     return browser.call(async () => {
         let actual;
         const pass = await utils_1.waitUntil(async () => {
             actual = received.calls.length;
             return utils_1.compareNumbers(actual, gte, lte, eq);
-        }, isNot, options);
+        }, isNot, { ...options, wait: isNot ? 0 : options.wait });
         const error = formatMessage_1.numberError(gte, lte, eq);
         const message = utils_1.enhanceError('mock', error, actual, this, verb, expectation, '', options);
         return {
@@ -24,6 +30,7 @@ function toBeRequestedTimesFn(received, times = {}, options = {}) {
         };
     });
 }
+exports.toBeRequestedTimesFn = toBeRequestedTimesFn;
 function toBeRequestedTimes(...args) {
     return expectAdapter_1.runExpect.call(this, toBeRequestedTimesFn, args);
 }