webdriverio 7.17.0 → 7.18.0

package/build/commands/element/click.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = __importDefault(require("@wdio/logger"));
+const log = (0, logger_1.default)('webdriverio/click');
+/**
+ *
+ * Click on an element.
+ *
+ * Note: This issues a WebDriver `click` command for the selected element, which generally scrolls to and then clicks the
+ * selected element. However, if you have fixed-position elements (such as a fixed header or footer) that cover up the
+ * selected element after it is scrolled within the viewport, the click will be issued at the given coordinates, but will
+ * be received by your fixed (overlaying) element. In these cased the following error is thrown:
+ *
+ * ```
+ * Element is not clickable at point (x, x). Other element would receive the click: ..."
+ * ```
+ *
+ * To work around this, try to find the overlaying element and remove it via `execute` command so it doesn't interfere
+ * the click. You also can try to scroll to the element yourself using `scroll` with an offset appropriate for your
+ * scenario.
+ *
+ * <example>
+    :example.html
+    <button id="myButton" onclick="document.getElementById('someText').innerHTML='I was clicked'">Click me</button>
+    <div id="someText">I was not clicked</div>
+    :click.js
+    it('should demonstrate the click command', async () => {
+        const myButton = await $('#myButton')
+        await myButton.click()
+        const myText = await $('#someText')
+        const text = await myText.getText()
+        assert(text === 'I was clicked') // true
+    })
+    :example.js
+    it('should fetch menu links and visit each page', async () => {
+        const links = await $$('#menu a')
+        await links.forEach(async (link) => {
+            await link.click()
+        })
+    })
+ * </example>
+ *
+ * <example>
+    :example.html
+    <button id="myButton">Click me</button>
+    :example.js
+    it('should demonstrate a click using an offset', async () => {
+        const myButton = await $('#myButton')
+        await myButton.click({ x: 30 }) // clicks 30 horizontal pixels away from location of the button (from center point of element)
+    })
+ * </example>
+ *
+ * <example>
+    :example.html
+    <button id="myButton">Click me</button>
+    :example.js
+    it('should demonstrate a right click passed as string', async () => {
+        const myButton = await $('#myButton')
+        await myButton.click({ button: 'right' }) // opens the contextmenu at the location of the button
+    })
+    it('should demonstrate a right click passed as number while adding an offset', async () => {
+        const myButton = await $('#myButton')
+        await myButton.click({ button: 2, x: 30, y: 40 }) // opens the contextmenu 30 horizontal and 40 vertical pixels away from location of the button (from the center of element)
+    })
+ * </example>
+ *
+ * @alias element.click
+ * @uses protocol/element, protocol/elementIdClick, protocol/performActions, protocol/positionClick
+ * @type action
+ * @param {ClickOptions=}     options        click options (optional)
+ * @param {string= | number=} options.button can be one of [0, "left", 1, "middle", 2, "right"] (optional)
+ * @param {number=}           options.x      Number (optional)
+ * @param {number=}           options.y      Number (optional)
+ */
+async function click(options) {
+    if (typeof options === 'undefined') {
+        return this.elementClick(this.elementId);
+    }
+    if (typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('Options must be an object');
+    }
+    let { button = 0, x: xoffset = 0, y: yoffset = 0 } = options || {};
+    if (typeof xoffset !== 'number'
+        || typeof yoffset !== 'number'
+        || !Number.isInteger(xoffset)
+        || !Number.isInteger(yoffset)) {
+        throw new TypeError('Coordinates must be integers');
+    }
+    if (button === 'left') {
+        button = 0;
+    }
+    if (button === 'middle') {
+        button = 1;
+    }
+    if (button === 'right') {
+        button = 2;
+    }
+    if (![0, 1, 2].includes(button)) {
+        throw new Error('Button type not supported.');
+    }
+    if (this.isW3C) {
+        await this.performActions([{
+                type: 'pointer',
+                id: 'pointer1',
+                parameters: {
+                    pointerType: 'mouse'
+                },
+                actions: [{
+                        type: 'pointerMove',
+                        origin: this,
+                        x: xoffset,
+                        y: yoffset
+                    }, {
+                        type: 'pointerDown',
+                        button
+                    }, {
+                        type: 'pointerUp',
+                        button
+                    }]
+            }]);
+        const err = await this.releaseActions().then(() => null, (err) => err);
+        if (err) {
+            log.warn(`Failed to call "releaseAction" command due to: ${err.message}, ignoring!`);
+        }
+        return;
+    }
+    const { width, height } = await this.getElementSize(this.elementId);
+    await this.moveToElement(this.elementId, xoffset + (width / 2), yoffset + (height / 2));
+    return this.positionClick(button);
+}
+exports.default = click;

package/build/commands/element/custom$$.d.ts

@@ -0,0 +1,28 @@
+import type { ElementArray } from '../../types';
+/**
+ *
+ * The `customs$$` allows you to use a custom strategy declared by using `browser.addLocatorStrategy`
+ *
+ * <example>
+    :example.js
+    it('should get all the plugin wrapper buttons', async () => {
+        await browser.url('https://webdriver.io')
+        await browser.addLocatorStrategy('myStrat', (selector) => {
+            return document.querySelectorAll(selector)
+        })
+
+        const pluginRowBlock = await browser.custom$('myStrat', '.pluginRowBlock')
+        const pluginWrapper = await pluginRowBlock.custom$$('myStrat', '.pluginWrapper')
+
+        console.log(pluginWrapper.length) // 4
+    })
+ * </example>
+ *
+ * @alias custom$$
+ * @param {String} strategyName
+ * @param {Any} strategyArguments
+ * @return {ElementArray}
+ */
+declare function custom$$(this: WebdriverIO.Element, strategyName: string, strategyArguments: string): Promise<ElementArray>;
+export default custom$$;
+//# sourceMappingURL=custom$$.d.ts.map

package/build/commands/element/custom$$.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom$$.d.ts","sourceRoot":"","sources":["../../../src/commands/element/custom$$.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAe,QAAQ,CACnB,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GAC1B,OAAO,CAAC,YAAY,CAAC,CAgCvB;AAED,eAAe,QAAQ,CAAA"}

package/build/commands/element/custom$$.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const getElementObject_1 = require("../../utils/getElementObject");
+const utils_1 = require("../../utils");
+const constants_1 = require("../../constants");
+/**
+ *
+ * The `customs$$` allows you to use a custom strategy declared by using `browser.addLocatorStrategy`
+ *
+ * <example>
+    :example.js
+    it('should get all the plugin wrapper buttons', async () => {
+        await browser.url('https://webdriver.io')
+        await browser.addLocatorStrategy('myStrat', (selector) => {
+            return document.querySelectorAll(selector)
+        })
+
+        const pluginRowBlock = await browser.custom$('myStrat', '.pluginRowBlock')
+        const pluginWrapper = await pluginRowBlock.custom$$('myStrat', '.pluginWrapper')
+
+        console.log(pluginWrapper.length) // 4
+    })
+ * </example>
+ *
+ * @alias custom$$
+ * @param {String} strategyName
+ * @param {Any} strategyArguments
+ * @return {ElementArray}
+ */
+async function custom$$(strategyName, strategyArguments) {
+    const browserObject = (0, utils_1.getBrowserObject)(this);
+    const strategy = browserObject.strategies.get(strategyName);
+    if (!strategy) {
+        /* istanbul ignore next */
+        throw Error('No strategy found for ' + strategyName);
+    }
+    /**
+     * fail if root element is not found, similar to:
+     * $('.notExisting').$('.someElem')
+     */
+    if (!this.elementId) {
+        throw Error(`Can't call custom$ on element with selector "${this.selector}" because element wasn't found`);
+    }
+    let res = await this.execute(strategy, strategyArguments, this);
+    /**
+     * if the user's script return just one element
+     * then we convert it to an array as this method
+     * should return multiple elements
+     */
+    if (!Array.isArray(res)) {
+        res = [res];
+    }
+    res = res.filter((el) => !!el && typeof el[constants_1.ELEMENT_KEY] === 'string');
+    const elements = res.length ? await getElementObject_1.getElements.call(this, strategy, res) : [];
+    return (0, utils_1.enhanceElementsArray)(elements, this, strategy, 'custom$$', [strategyArguments]);
+}
+exports.default = custom$$;

package/build/commands/element/custom$.d.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * The `custom$` allows you to use a custom strategy declared by using `browser.addLocatorStrategy`
+ *
+ * <example>
+    :example.js
+    it('should fetch the project title', async () => {
+        await browser.url('https://webdriver.io')
+        await browser.addLocatorStrategy('myStrat', (selector) => {
+            return document.querySelectorAll(selector)
+        })
+
+        const header = await browser.custom$('myStrat', 'header')
+        const projectTitle = await header.custom$('myStrat', '.projectTitle')
+
+        console.log(projectTitle.getText()) // WEBDRIVER I/O
+    })
+ * </example>
+ *
+ * @alias custom$
+ * @param {String} strategyName
+ * @param {Any} strategyArguments
+ * @return {Element}
+ */
+declare function custom$(this: WebdriverIO.Element, strategyName: string, strategyArguments: string): Promise<WebdriverIO.Element>;
+export default custom$;
+//# sourceMappingURL=custom$.d.ts.map

package/build/commands/element/custom$.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom$.d.ts","sourceRoot":"","sources":["../../../src/commands/element/custom$.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAe,OAAO,CAClB,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,gCAiC5B;AAED,eAAe,OAAO,CAAA"}

package/build/commands/element/custom$.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const getElementObject_1 = require("../../utils/getElementObject");
+const utils_1 = require("../../utils");
+const constants_1 = require("../../constants");
+/**
+ *
+ * The `custom$` allows you to use a custom strategy declared by using `browser.addLocatorStrategy`
+ *
+ * <example>
+    :example.js
+    it('should fetch the project title', async () => {
+        await browser.url('https://webdriver.io')
+        await browser.addLocatorStrategy('myStrat', (selector) => {
+            return document.querySelectorAll(selector)
+        })
+
+        const header = await browser.custom$('myStrat', 'header')
+        const projectTitle = await header.custom$('myStrat', '.projectTitle')
+
+        console.log(projectTitle.getText()) // WEBDRIVER I/O
+    })
+ * </example>
+ *
+ * @alias custom$
+ * @param {String} strategyName
+ * @param {Any} strategyArguments
+ * @return {Element}
+ */
+async function custom$(strategyName, strategyArguments) {
+    const browserObject = (0, utils_1.getBrowserObject)(this);
+    const strategy = browserObject.strategies.get(strategyName);
+    if (!strategy) {
+        throw Error('No strategy found for ' + strategyName);
+    }
+    /**
+     * fail if root element is not found, similar to:
+     * $('.notExisting').$('.someElem')
+     */
+    if (!this.elementId) {
+        throw Error(`Can't call custom$ on element with selector "${this.selector}" because element wasn't found`);
+    }
+    let res = await this.execute(strategy, strategyArguments, this);
+    /**
+     * if the user's script returns multiple elements
+     * then we just return the first one as this method
+     * is intended to return just one element
+     */
+    if (Array.isArray(res)) {
+        res = res[0];
+    }
+    if (res && typeof res[constants_1.ELEMENT_KEY] === 'string') {
+        return await getElementObject_1.getElement.call(this, strategy, res);
+    }
+    throw Error('Your locator strategy script must return an element');
+}
+exports.default = custom$;

package/build/commands/element/doubleClick.d.ts

@@ -0,0 +1,25 @@
+/**
+ *
+ * Double-click on an element.
+ *
+ * <example>
+    :example.html
+    <button id="myButton" ondblclick="document.getElementById('someText').innerHTML='I was dblclicked'">Click me</button>
+    <div id="someText">I was not clicked</div>
+    :doubleClick.js
+    it('should demonstrate the doubleClick command', async () => {
+        const myButton = await $('#myButton')
+        await myButton.doubleClick()
+
+        const value = await myButton.getText()
+        assert(value === 'I was dblclicked') // true
+    })
+ * </example>
+ *
+ * @alias element.doubleClick
+ * @uses protocol/element, protocol/moveTo, protocol/doDoubleClick, protocol/touchDoubleClick
+ * @type action
+ *
+ */
+export default function doubleClick(this: WebdriverIO.Element): Promise<void>;
+//# sourceMappingURL=doubleClick.d.ts.map

package/build/commands/element/doubleClick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doubleClick.d.ts","sourceRoot":"","sources":["../../../src/commands/element/doubleClick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAA8B,WAAW,CAAE,IAAI,EAAE,WAAW,CAAC,OAAO,iBAyBnE"}

package/build/commands/element/doubleClick.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ *
+ * Double-click on an element.
+ *
+ * <example>
+    :example.html
+    <button id="myButton" ondblclick="document.getElementById('someText').innerHTML='I was dblclicked'">Click me</button>
+    <div id="someText">I was not clicked</div>
+    :doubleClick.js
+    it('should demonstrate the doubleClick command', async () => {
+        const myButton = await $('#myButton')
+        await myButton.doubleClick()
+
+        const value = await myButton.getText()
+        assert(value === 'I was dblclicked') // true
+    })
+ * </example>
+ *
+ * @alias element.doubleClick
+ * @uses protocol/element, protocol/moveTo, protocol/doDoubleClick, protocol/touchDoubleClick
+ * @type action
+ *
+ */
+async function doubleClick() {
+    /**
+     * move to element
+     */
+    if (!this.isW3C) {
+        await this.moveTo();
+        return this.positionDoubleClick();
+    }
+    /**
+     * W3C way of handle the double click actions
+     */
+    return this.performActions([{
+            type: 'pointer',
+            id: 'pointer1',
+            parameters: { pointerType: 'mouse' },
+            actions: [
+                { type: 'pointerMove', origin: this, x: 0, y: 0 },
+                { type: 'pointerDown', button: 0 },
+                { type: 'pointerUp', button: 0 },
+                { type: 'pause', duration: 10 },
+                { type: 'pointerDown', button: 0 },
+                { type: 'pointerUp', button: 0 }
+            ]
+        }]);
+}
+exports.default = doubleClick;

package/build/commands/element/dragAndDrop.d.ts

@@ -0,0 +1,41 @@
+declare type DragAndDropOptions = {
+    duration?: number;
+};
+declare type ElementCoordinates = {
+    x?: number;
+    y?: number;
+};
+/**
+ *
+ * Drag an item to a destination element or position.
+ *
+ * :::info
+ *
+ * The functionality of this command highly depends on the way drag and drop is
+ * implemented in your app. If you experience issues please post your example
+ * in [#4134](https://github.com/webdriverio/webdriverio/issues/4134).
+ *
+ * :::
+ *
+ * <example>
+    :example.test.js
+    it('should demonstrate the dragAndDrop command', async () => {
+        const elem = await $('#someElem')
+        const target = await $('#someTarget')
+
+        // drag and drop to other element
+        await elem.dragAndDrop(target)
+
+        // drag and drop relative from current position
+        await elem.dragAndDrop({ x: 100, y: 200 })
+    })
+ * </example>
+ *
+ * @alias element.dragAndDrop
+ * @param {Element|DragAndDropCoordinate} target  destination element or object with x and y properties
+ * @param {DragAndDropOptions=} options           dragAndDrop command options
+ * @param {Number=}             options.duration  how long the drag should take place
+ */
+export default function dragAndDrop(this: WebdriverIO.Element, target: WebdriverIO.Element | ElementCoordinates, { duration }?: DragAndDropOptions): Promise<void>;
+export {};
+//# sourceMappingURL=dragAndDrop.d.ts.map

package/build/commands/element/dragAndDrop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dragAndDrop.d.ts","sourceRoot":"","sources":["../../../src/commands/element/dragAndDrop.ts"],"names":[],"mappings":"AAOA,aAAK,kBAAkB,GAAG;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,aAAK,kBAAkB,GAAG;IACtB,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAA8B,WAAW,CACrC,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,MAAM,EAAE,WAAW,CAAC,OAAO,GAAG,kBAAkB,EAChD,EAAE,QAAa,EAAE,GAAE,kBAAuB,iBAyE7C"}

package/build/commands/element/dragAndDrop.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const constants_1 = require("../../constants");
+const ACTION_BUTTON = 0;
+const sleep = (time = 0) => new Promise((resolve) => setTimeout(resolve, time));
+/**
+ *
+ * Drag an item to a destination element or position.
+ *
+ * :::info
+ *
+ * The functionality of this command highly depends on the way drag and drop is
+ * implemented in your app. If you experience issues please post your example
+ * in [#4134](https://github.com/webdriverio/webdriverio/issues/4134).
+ *
+ * :::
+ *
+ * <example>
+    :example.test.js
+    it('should demonstrate the dragAndDrop command', async () => {
+        const elem = await $('#someElem')
+        const target = await $('#someTarget')
+
+        // drag and drop to other element
+        await elem.dragAndDrop(target)
+
+        // drag and drop relative from current position
+        await elem.dragAndDrop({ x: 100, y: 200 })
+    })
+ * </example>
+ *
+ * @alias element.dragAndDrop
+ * @param {Element|DragAndDropCoordinate} target  destination element or object with x and y properties
+ * @param {DragAndDropOptions=} options           dragAndDrop command options
+ * @param {Number=}             options.duration  how long the drag should take place
+ */
+async function dragAndDrop(target, { duration = 10 } = {}) {
+    const moveToCoordinates = target;
+    const moveToElement = target;
+    /**
+     * fail if
+     */
+    if (
+    /**
+     * no target was specified
+     */
+    !target ||
+        (
+        /**
+         * target is not from type element
+         */
+        target.constructor.name !== 'Element' &&
+            /**
+             * and is also not an object with x and y number parameters
+             */
+            (typeof moveToCoordinates.x !== 'number' ||
+                typeof moveToCoordinates.y !== 'number'))) {
+        throw new Error('command dragAndDrop requires an WebdriverIO Element or and object with "x" and "y" variables as first parameter');
+    }
+    /**
+     * allow to specify an element or an x/y vector
+     */
+    const isMovingToElement = target.constructor.name === 'Element';
+    if (!this.isW3C) {
+        await this.moveTo();
+        await this.buttonDown(ACTION_BUTTON);
+        if (isMovingToElement) {
+            await moveToElement.moveTo();
+        }
+        else {
+            await this.moveToElement(null, moveToCoordinates.x, moveToCoordinates.y);
+        }
+        await sleep(duration);
+        return this.buttonUp(ACTION_BUTTON);
+    }
+    const sourceRef = { [constants_1.ELEMENT_KEY]: this[constants_1.ELEMENT_KEY] };
+    const targetRef = { [constants_1.ELEMENT_KEY]: moveToElement[constants_1.ELEMENT_KEY] };
+    const origin = sourceRef;
+    const targetOrigin = isMovingToElement ? targetRef : 'pointer';
+    const targetX = isMovingToElement ? 0 : moveToCoordinates.x;
+    const targetY = isMovingToElement ? 0 : moveToCoordinates.y;
+    /**
+     * W3C way of handle the drag and drop action
+     */
+    return this.performActions([{
+            type: 'pointer',
+            id: 'finger1',
+            parameters: { pointerType: 'mouse' },
+            actions: [
+                { type: 'pointerMove', duration: 0, origin, x: 0, y: 0 },
+                { type: 'pointerDown', button: ACTION_BUTTON },
+                { type: 'pause', duration: 10 },
+                { type: 'pointerMove', duration, origin: targetOrigin, x: targetX, y: targetY },
+                { type: 'pointerUp', button: ACTION_BUTTON }
+            ]
+        }]).then(() => this.releaseActions());
+}
+exports.default = dragAndDrop;

package/build/commands/element/getAttribute.d.ts

@@ -0,0 +1,28 @@
+/**
+ *
+ * Get an attribute from a DOM-element based on the attribute name.
+ *
+ * <example>
+    :index.html
+    <form action="/submit" method="post" class="loginForm">
+        <input type="text" name="name" placeholder="username"></input>
+        <input type="text" name="password" placeholder="password"></input>
+        <input type="submit" name="submit" value="submit"></input>
+    </form>
+    :getAttribute.js
+    it('should demonstrate the getAttribute command', async () => {
+        const form = await $('form')
+        const attr = await form.getAttribute('method')
+        console.log(attr) // outputs: "post"
+    })
+ * </example>
+ *
+ * @alias element.getAttribute
+ * @param {String} attributeName requested attribute
+ * @return {String|null} The value of the attribute, or null if it is not set on the element.
+ * @uses protocol/elements, protocol/elementIdAttribute
+ * @type property
+ *
+ */
+export default function getAttribute(this: WebdriverIO.Element, attributeName: string): Promise<string>;
+//# sourceMappingURL=getAttribute.d.ts.map

package/build/commands/element/getAttribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAttribute.d.ts","sourceRoot":"","sources":["../../../src/commands/element/getAttribute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAChC,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,aAAa,EAAE,MAAM,mBAGxB"}

package/build/commands/element/getAttribute.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ *
+ * Get an attribute from a DOM-element based on the attribute name.
+ *
+ * <example>
+    :index.html
+    <form action="/submit" method="post" class="loginForm">
+        <input type="text" name="name" placeholder="username"></input>
+        <input type="text" name="password" placeholder="password"></input>
+        <input type="submit" name="submit" value="submit"></input>
+    </form>
+    :getAttribute.js
+    it('should demonstrate the getAttribute command', async () => {
+        const form = await $('form')
+        const attr = await form.getAttribute('method')
+        console.log(attr) // outputs: "post"
+    })
+ * </example>
+ *
+ * @alias element.getAttribute
+ * @param {String} attributeName requested attribute
+ * @return {String|null} The value of the attribute, or null if it is not set on the element.
+ * @uses protocol/elements, protocol/elementIdAttribute
+ * @type property
+ *
+ */
+function getAttribute(attributeName) {
+    return this.getElementAttribute(this.elementId, attributeName);
+}
+exports.default = getAttribute;