expect-webdriverio 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Mykola Grybyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# 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)
+
+> [WebdriverIO](https://webdriver.io/) Assertion library inspired by [expect](https://www.npmjs.com/package/expect)
+
+## Key Features
+
+- [waits](#default-options) for expectation to succeed
+- detailed [error messages](#error-messages)
+- works in Mocha, Cucumber, Jest, Jasmine
+- builtin [types](docs/Types.md) for TypeScript and JS autocompletion
+
+## Installation
+
+1. `npm install expect` (**Jasmine** and **Jest** users should skip this step)
+2. `npm install expect-webdriverio`
+
+NOTE: [WebdriverIO](https://github.com/webdriverio/webdriverio) `v5.16.11` or higher is required!
+
+## Usage
+
+In your `wdio.conf.js`
+```js
+before () { // not needed in WebdriverIO v6
+    require('expect-webdriverio')
+},
+```
+
+In your test
+```js
+const $button = $('button')
+expect($button).toBeDisplayed()
+```
+
+See more [Examples](docs/Examples.md)
+
+## API
+
+Please see [API doc](docs/API.md)
+
+## Error messages
+
+Error messages are informative out of the box and contain:
+
+- full element selector, like `$('form').$('input')`
+- actual and expected values
+- highlight the difference (texts assertions)
+
+![toHaveText](/docs/img/errors/text.png?raw=true "toHaveText")
+![toHaveElementClass](/docs/img/errors/class.png?raw=true "toHaveElementClass")
+
+## What's next?
+
+First of all, **feel free to raise an issue with your suggestions or help with PR!**
+
+### Planned
+
+- css matcher
+- size matcher
+- cookie / localStorage matchers?
+- text regex matchers
+- multiremote support (if requested)

package/jasmine.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="expect-webdriverio/types/expect-webdriverio"/>
+
+declare module jasmine {
+    interface Matchers<T> extends ExpectWebdriverIO.Matchers<any, T> {}
+    interface AsyncMatchers<T, U> extends ExpectWebdriverIO.Matchers<Promise<void>, T> {}
+}

package/jest.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="expect-webdriverio/types/expect-webdriverio"/>
+
+declare namespace jest {
+    interface Matchers<R, T> extends ExpectWebdriverIO.Matchers<R, T> { }
+}

package/lib/addMatchers.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMatchers = exports.loadExpect = exports.isJasmine = void 0;
+let expectLib;
+const isJasmine = () => {
+    return Boolean(global.jasmine && global.expect && global.expectAsync && global.jasmine.getEnv && global.jasmine.addMatchers && global.jasmine.addAsyncMatchers);
+};
+exports.isJasmine = isJasmine;
+const loadExpect = () => {
+    try {
+        return expectLib = require('expect');
+    }
+    catch (err) {
+        return console.error('Failed to load expect package. Make sure it has been installed: npm i expect');
+    }
+};
+exports.loadExpect = loadExpect;
+const addMatchers = () => {
+    if (global.expect === undefined) {
+        if (!exports.loadExpect()) {
+            return;
+        }
+        global.expect = expectLib;
+    }
+    else {
+        expectLib = global.expect;
+    }
+    if (!global.expect.extend && !exports.isJasmine()) {
+        if (!exports.loadExpect()) {
+            return;
+        }
+        global.expectWdio = expectLib;
+        console.warn('Warning! Unsupported expect lib is used.\n' +
+            "Only Jasmine >= 3.3.0 and Jest's expect are supported.\n" +
+            "expect-webdriverio is assigned to global.expectWdio");
+    }
+    require('./options').setDefaultOptions;
+    const matchers = require('./matchers').default;
+    if (expectLib.extend) {
+        return expectLib.extend({ ...matchers });
+    }
+    expectLib = global.jasmine;
+    return expectLib.getEnv().beforeAll(function addExpectWebdriverIOMatchers() {
+        expectLib.addAsyncMatchers({ ...matchers });
+        global.expect = global.expectAsync;
+    });
+};
+exports.addMatchers = addMatchers;

package/lib/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setOptions = void 0;
+const addMatchers_1 = require("./addMatchers");
+addMatchers_1.addMatchers();
+exports.setOptions = require('./options').setDefaultOptions;

package/lib/jasmineUtils.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isImmutableUnorderedSet = exports.isImmutableUnorderedKeyed = exports.hasProperty = exports.isUndefined = exports.fnNameFor = exports.isA = exports.equals = void 0;
+function equals(a, b, customTesters, strictCheck) {
+    customTesters = customTesters || [];
+    return eq(a, b, [], [], customTesters, strictCheck ? hasKey : hasDefinedKey);
+}
+exports.equals = equals;
+const functionToString = Function.prototype.toString;
+function isAsymmetric(obj) {
+    return !!obj && isA('Function', obj.asymmetricMatch);
+}
+function asymmetricMatch(a, b) {
+    var asymmetricA = isAsymmetric(a), asymmetricB = isAsymmetric(b);
+    if (asymmetricA && asymmetricB) {
+        return undefined;
+    }
+    if (asymmetricA) {
+        return a.asymmetricMatch(b);
+    }
+    if (asymmetricB) {
+        return b.asymmetricMatch(a);
+    }
+}
+function eq(a, b, aStack, bStack, customTesters, hasKey) {
+    var result = true;
+    var asymmetricResult = asymmetricMatch(a, b);
+    if (asymmetricResult !== undefined) {
+        return asymmetricResult;
+    }
+    for (var i = 0; i < customTesters.length; i++) {
+        var customTesterResult = customTesters[i](a, b);
+        if (customTesterResult !== undefined) {
+            return customTesterResult;
+        }
+    }
+    if (a instanceof Error && b instanceof Error) {
+        return a.message == b.message;
+    }
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (a === null || b === null) {
+        return a === b;
+    }
+    var className = Object.prototype.toString.call(a);
+    if (className != Object.prototype.toString.call(b)) {
+        return false;
+    }
+    switch (className) {
+        case '[object Boolean]':
+        case '[object String]':
+        case '[object Number]':
+            if (typeof a !== typeof b) {
+                return false;
+            }
+            else if (typeof a !== 'object' && typeof b !== 'object') {
+                return Object.is(a, b);
+            }
+            else {
+                return Object.is(a.valueOf(), b.valueOf());
+            }
+        case '[object Date]':
+            return +a == +b;
+        case '[object RegExp]':
+            return a.source === b.source && a.flags === b.flags;
+    }
+    if (typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    if (isDomNode(a) && isDomNode(b)) {
+        return a.isEqualNode(b);
+    }
+    var length = aStack.length;
+    while (length--) {
+        if (aStack[length] === a) {
+            return bStack[length] === b;
+        }
+        else if (bStack[length] === b) {
+            return false;
+        }
+    }
+    aStack.push(a);
+    bStack.push(b);
+    var size = 0;
+    if (className == '[object Array]') {
+        size = a.length;
+        if (size !== b.length) {
+            return false;
+        }
+        while (size--) {
+            result = eq(a[size], b[size], aStack, bStack, customTesters, hasKey);
+            if (!result) {
+                return false;
+            }
+        }
+    }
+    var aKeys = keys(a, className == '[object Array]', hasKey), key;
+    size = aKeys.length;
+    if (keys(b, className == '[object Array]', hasKey).length !== size) {
+        return false;
+    }
+    while (size--) {
+        key = aKeys[size];
+        result =
+            hasKey(b, key) &&
+                eq(a[key], b[key], aStack, bStack, customTesters, hasKey);
+        if (!result) {
+            return false;
+        }
+    }
+    aStack.pop();
+    bStack.pop();
+    return result;
+}
+function keys(obj, isArray, hasKey) {
+    var allKeys = (function (o) {
+        var keys = [];
+        for (var key in o) {
+            if (hasKey(o, key)) {
+                keys.push(key);
+            }
+        }
+        return keys.concat(Object.getOwnPropertySymbols(o).filter(symbol => Object.getOwnPropertyDescriptor(o, symbol)
+            .enumerable));
+    })(obj);
+    if (!isArray) {
+        return allKeys;
+    }
+    var extraKeys = [];
+    if (allKeys.length === 0) {
+        return allKeys;
+    }
+    for (var x = 0; x < allKeys.length; x++) {
+        if (typeof allKeys[x] === 'symbol' || !allKeys[x].match(/^[0-9]+$/)) {
+            extraKeys.push(allKeys[x]);
+        }
+    }
+    return extraKeys;
+}
+function hasDefinedKey(obj, key) {
+    return hasKey(obj, key) && obj[key] !== undefined;
+}
+function hasKey(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function isA(typeName, value) {
+    return Object.prototype.toString.apply(value) === '[object ' + typeName + ']';
+}
+exports.isA = isA;
+function isDomNode(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        typeof obj.nodeType === 'number' &&
+        typeof obj.nodeName === 'string' &&
+        typeof obj.isEqualNode === 'function');
+}
+function fnNameFor(func) {
+    if (func.name) {
+        return func.name;
+    }
+    const matches = functionToString
+        .call(func)
+        .match(/^(?:async)?\s*function\s*\*?\s*([\w$]+)\s*\(/);
+    return matches ? matches[1] : '<anonymous>';
+}
+exports.fnNameFor = fnNameFor;
+function isUndefined(obj) {
+    return obj === void 0;
+}
+exports.isUndefined = isUndefined;
+function getPrototype(obj) {
+    if (Object.getPrototypeOf) {
+        return Object.getPrototypeOf(obj);
+    }
+    if (obj.constructor.prototype == obj) {
+        return null;
+    }
+    return obj.constructor.prototype;
+}
+function hasProperty(obj, property) {
+    if (!obj) {
+        return false;
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, property)) {
+        return true;
+    }
+    return hasProperty(getPrototype(obj), property);
+}
+exports.hasProperty = hasProperty;
+const IS_KEYED_SENTINEL = '@@__IMMUTABLE_KEYED__@@';
+const IS_SET_SENTINEL = '@@__IMMUTABLE_SET__@@';
+const IS_ORDERED_SENTINEL = '@@__IMMUTABLE_ORDERED__@@';
+function isImmutableUnorderedKeyed(maybeKeyed) {
+    return !!(maybeKeyed &&
+        maybeKeyed[IS_KEYED_SENTINEL] &&
+        !maybeKeyed[IS_ORDERED_SENTINEL]);
+}
+exports.isImmutableUnorderedKeyed = isImmutableUnorderedKeyed;
+function isImmutableUnorderedSet(maybeSet) {
+    return !!(maybeSet &&
+        maybeSet[IS_SET_SENTINEL] &&
+        !maybeSet[IS_ORDERED_SENTINEL]);
+}
+exports.isImmutableUnorderedSet = isImmutableUnorderedSet;

package/lib/matchers/browser/toHaveTitle.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHaveTitle = exports.toHaveTitleFn = void 0;
+const expectAdapter_1 = require("../../util/expectAdapter");
+const utils_1 = require("../../utils");
+function toHaveTitleFn(browser, title, options = {}) {
+    const isNot = this.isNot;
+    const { expectation = 'title', verb = 'have' } = this;
+    return browser.call(async () => {
+        let actual;
+        const pass = await utils_1.waitUntil(async () => {
+            actual = await browser.getTitle();
+            return utils_1.compareText(actual, title, options).result;
+        }, isNot, options);
+        const message = utils_1.enhanceError('window', title, actual, this, verb, expectation, '', options);
+        return {
+            pass,
+            message: () => message
+        };
+    });
+}
+exports.toHaveTitleFn = toHaveTitleFn;
+function toHaveTitle(...args) {
+    return expectAdapter_1.runExpect.call(this, toHaveTitleFn, args);
+}
+exports.toHaveTitle = toHaveTitle;

package/lib/matchers/browser/toHaveTitleContaining.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHaveTitleContaining = void 0;
+const expectAdapter_1 = require("../../util/expectAdapter");
+const toHaveTitle_1 = require("./toHaveTitle");
+function toHaveTitleContainingFn(browser, title, options = {}) {
+    return toHaveTitle_1.toHaveTitleFn.call(this, browser, title, {
+        ...options,
+        containing: true
+    });
+}
+function toHaveTitleContaining(...args) {
+    return expectAdapter_1.runExpect.call(this, toHaveTitleContainingFn, args);
+}
+exports.toHaveTitleContaining = toHaveTitleContaining;

package/lib/matchers/browser/toHaveUrl.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHaveUrl = exports.toHaveUrlFn = void 0;
+const expectAdapter_1 = require("../../util/expectAdapter");
+const utils_1 = require("../../utils");
+function toHaveUrlFn(browser, url, options = {}) {
+    const isNot = this.isNot;
+    const { expectation = 'url', verb = 'have' } = this;
+    return browser.call(async () => {
+        let actual;
+        const pass = await utils_1.waitUntil(async () => {
+            actual = await browser.getUrl();
+            return utils_1.compareText(actual, url, options).result;
+        }, isNot, options);
+        const message = utils_1.enhanceError('window', url, actual, this, verb, expectation, '', options);
+        return {
+            pass,
+            message: () => message
+        };
+    });
+}
+exports.toHaveUrlFn = toHaveUrlFn;
+function toHaveUrl(...args) {
+    return expectAdapter_1.runExpect.call(this, toHaveUrlFn, args);
+}
+exports.toHaveUrl = toHaveUrl;

package/lib/matchers/browser/toHaveUrlContaining.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHaveUrlContaining = void 0;
+const expectAdapter_1 = require("../../util/expectAdapter");
+const toHaveUrl_1 = require("./toHaveUrl");
+function toHaveUrlContainingFn(browser, url, options = {}) {
+    return toHaveUrl_1.toHaveUrlFn.call(this, browser, url, {
+        ...options,
+        containing: true
+    });
+}
+function toHaveUrlContaining(...args) {
+    return expectAdapter_1.runExpect.call(this, toHaveUrlContainingFn, args);
+}
+exports.toHaveUrlContaining = toHaveUrlContaining;

package/lib/matchers/element/toBeClickable.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeClickable = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeClickableFn(received, options = {}) {
+    this.expectation = this.expectation || 'clickable';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, async (el) => {
+            try {
+                return el.isClickable();
+            }
+            catch (_a) {
+                return false;
+            }
+        }, options);
+        return result;
+    });
+}
+function toBeClickable(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeClickableFn, args);
+}
+exports.toBeClickable = toBeClickable;

package/lib/matchers/element/toBeDisabled.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeDisabled = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeDisabledFn(received, options = {}) {
+    this.expectation = this.expectation || 'disabled';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, async (el) => !await el.isEnabled(), options);
+        return result;
+    });
+}
+function toBeDisabled(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeDisabledFn, args);
+}
+exports.toBeDisabled = toBeDisabled;

package/lib/matchers/element/toBeDisplayed.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeDisplayed = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeDisplayedFn(received, options = {}) {
+    this.expectation = this.expectation || 'displayed';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, async (el) => {
+            try {
+                return el.isDisplayed();
+            }
+            catch (_a) {
+                return false;
+            }
+        }, options);
+        return result;
+    });
+}
+function toBeDisplayed(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeDisplayedFn, args);
+}
+exports.toBeDisplayed = toBeDisplayed;

package/lib/matchers/element/toBeDisplayedInViewport.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeDisplayedInViewport = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeDisplayedInViewportFn(received, options = {}) {
+    this.expectation = this.expectation || 'displayed in viewport';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, async (el) => {
+            try {
+                return el.isDisplayedInViewport();
+            }
+            catch (_a) {
+                return false;
+            }
+        }, options);
+        return result;
+    });
+}
+function toBeDisplayedInViewport(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeDisplayedInViewportFn, args);
+}
+exports.toBeDisplayedInViewport = toBeDisplayedInViewport;

package/lib/matchers/element/toBeEnabled.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeEnabled = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeEnabledFn(received, options = {}) {
+    this.expectation = this.expectation || 'enabled';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, el => el.isEnabled(), options);
+        return result;
+    });
+}
+function toBeEnabled(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeEnabledFn, args);
+}
+exports.toBeEnabled = toBeEnabled;

package/lib/matchers/element/toBeExisting.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBePresent = exports.toBeExisting = exports.toExist = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toExistFn(received, options = {}) {
+    this.expectation = this.expectation || 'exist';
+    this.verb = this.verb || '';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, async (el) => {
+            try {
+                return el.isExisting();
+            }
+            catch (_a) {
+                return false;
+            }
+        }, options);
+        return result;
+    });
+}
+function toExist(...args) {
+    return expectAdapter_1.runExpect.call(this, toExistFn, args);
+}
+exports.toExist = toExist;
+function toBeExisting(el, options) {
+    return utils_1.aliasFn.call(this, toExist, { verb: 'be', expectation: 'existing' }, el, options);
+}
+exports.toBeExisting = toBeExisting;
+function toBePresent(el, options) {
+    return utils_1.aliasFn.call(this, toExist, { verb: 'be', expectation: 'present' }, el, options);
+}
+exports.toBePresent = toBePresent;

package/lib/matchers/element/toBeFocused.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeFocused = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeFocusedFn(received, options = {}) {
+    this.expectation = this.expectation || 'focused';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, el => el.isFocused(), options);
+        return result;
+    });
+}
+function toBeFocused(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeFocusedFn, args);
+}
+exports.toBeFocused = toBeFocused;

package/lib/matchers/element/toBeSelected.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBeChecked = exports.toBeSelected = void 0;
+const utils_1 = require("../../utils");
+const expectAdapter_1 = require("../../util/expectAdapter");
+function toBeSelectedFn(received, options = {}) {
+    this.expectation = this.expectation || 'selected';
+    return browser.call(async () => {
+        const result = await utils_1.executeCommandBe.call(this, received, el => el.isSelected(), options);
+        return result;
+    });
+}
+function toBeSelected(...args) {
+    return expectAdapter_1.runExpect.call(this, toBeSelectedFn, args);
+}
+exports.toBeSelected = toBeSelected;
+function toBeChecked(el, options) {
+    const context = expectAdapter_1.getContext(this);
+    context.expectation = 'checked';
+    return toBeSelected.call(context, el, options);
+}
+exports.toBeChecked = toBeChecked;