codeceptjs 3.5.13-beta.1 → 3.5.13-beta.2

package/docs/webapi/grabPageScrollPosition.mustache

@@ -0,0 +1,8 @@
+Retrieves a page scroll position and returns it to test.
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+let { x, y } = await I.grabPageScrollPosition();
+```
+
+@returns {Promise<PageScrollPosition>} scroll position

package/docs/webapi/grabPopupText.mustache

@@ -0,0 +1,5 @@
+Grab the text within the popup. If no popup is visible then it will return null.
+```js
+await I.grabPopupText();
+```
+@returns {Promise<string>}

package/docs/webapi/grabSource.mustache

@@ -0,0 +1,8 @@
+Retrieves page source and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let pageSource = await I.grabSource();
+```
+
+@returns {Promise<string>} source code

package/docs/webapi/grabTextFrom.mustache

@@ -0,0 +1,10 @@
+Retrieves a text from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let pin = await I.grabTextFrom('#pin');
+```
+If multiple elements found returns first element.
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<string>} attribute value

package/docs/webapi/grabTextFromAll.mustache

@@ -0,0 +1,9 @@
+Retrieves all texts from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let pins = await I.grabTextFromAll('#pin li');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<string[]>} attribute value

package/docs/webapi/grabTitle.mustache

@@ -0,0 +1,8 @@
+Retrieves a page title and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let title = await I.grabTitle();
+```
+
+@returns {Promise<string>} title

package/docs/webapi/grabValueFrom.mustache

@@ -0,0 +1,9 @@
+Retrieves a value from a form element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+If more than one element is found - value of first element is returned.
+
+```js
+let email = await I.grabValueFrom('input[name=email]');
+```
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@returns {Promise<string>} attribute value

package/docs/webapi/grabValueFromAll.mustache

@@ -0,0 +1,8 @@
+Retrieves an array of value from a form located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let inputs = await I.grabValueFromAll('//form/input');
+```
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@returns {Promise<string[]>} attribute value

package/docs/webapi/grabWebElement.mustache

@@ -0,0 +1,9 @@
+Grab WebElement for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElement = await I.grabWebElement('#button');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<*>} WebElement of being used Web helper

package/docs/webapi/grabWebElements.mustache

@@ -0,0 +1,9 @@
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<*>} WebElement of being used Web helper

package/docs/webapi/moveCursorTo.mustache

@@ -0,0 +1,12 @@
+Moves cursor to element matched by locator.
+Extra shift can be set with offsetX and offsetY options.
+
+```js
+I.moveCursorTo('.tooltip');
+I.moveCursorTo('#submit', 5,5);
+```
+
+@param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+@param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/openNewTab.mustache

@@ -0,0 +1,7 @@
+Open new tab and switch to it.
+
+```js
+I.openNewTab();
+```
+
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/pressKey.mustache

@@ -0,0 +1,12 @@
+Presses a key on a focused element.
+Special keys like 'Enter', 'Control', [etc](https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value)
+will be replaced with corresponding unicode.
+If modifier key is used (Control, Command, Alt, Shift) in array, it will be released afterwards.
+
+```js
+I.pressKey('Enter');
+I.pressKey(['Control','a']);
+```
+
+@param {string|string[]} key key or array of keys to press.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/pressKeyDown.mustache

@@ -0,0 +1,12 @@
+Presses a key in the browser and leaves it in a down state.
+
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`](#click)).
+
+```js
+I.pressKeyDown('Control');
+I.click('#element');
+I.pressKeyUp('Control');
+```
+
+@param {string} key name of key to press down.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/pressKeyUp.mustache

@@ -0,0 +1,12 @@
+Releases a key in the browser which was previously set to a down state.
+
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`](#click)).
+
+```js
+I.pressKeyDown('Control');
+I.click('#element');
+I.pressKeyUp('Control');
+```
+
+@param {string} key name of key to release.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/pressKeyWithKeyNormalization.mustache

@@ -0,0 +1,60 @@
+Presses a key in the browser (on a focused element).
+
+_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`](#fillfield).
+
+```js
+I.pressKey('Backspace');
+```
+
+To press a key in combination with modifier keys, pass the sequence as an array. All modifier keys (`'Alt'`, `'Control'`, `'Meta'`, `'Shift'`) will be released afterwards.
+
+```js
+I.pressKey(['Control', 'Z']);
+```
+
+For specifying operation modifier key based on operating system it is suggested to use `'CommandOrControl'`.
+This will press `'Command'` (also known as `'Meta'`) on macOS machines and `'Control'` on non-macOS machines.
+
+```js
+I.pressKey(['CommandOrControl', 'Z']);
+```
+
+Some of the supported key names are:
+- `'AltLeft'` or `'Alt'`
+- `'AltRight'`
+- `'ArrowDown'`
+- `'ArrowLeft'`
+- `'ArrowRight'`
+- `'ArrowUp'`
+- `'Backspace'`
+- `'Clear'`
+- `'ControlLeft'` or `'Control'`
+- `'ControlRight'`
+- `'Command'`
+- `'CommandOrControl'`
+- `'Delete'`
+- `'End'`
+- `'Enter'`
+- `'Escape'`
+- `'F1'` to `'F12'`
+- `'Home'`
+- `'Insert'`
+- `'MetaLeft'` or `'Meta'`
+- `'MetaRight'`
+- `'Numpad0'` to `'Numpad9'`
+- `'NumpadAdd'`
+- `'NumpadDecimal'`
+- `'NumpadDivide'`
+- `'NumpadMultiply'`
+- `'NumpadSubtract'`
+- `'PageDown'`
+- `'PageUp'`
+- `'Pause'`
+- `'Return'`
+- `'ShiftLeft'` or `'Shift'`
+- `'ShiftRight'`
+- `'Space'`
+- `'Tab'`
+
+@param {string|string[]} key key or array of keys to press.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/refreshPage.mustache

@@ -0,0 +1,6 @@
+Reload the current page.
+
+```js
+I.refreshPage();
+```
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/resizeWindow.mustache

@@ -0,0 +1,6 @@
+Resize the current window to provided width and height.
+First parameter can be set to `maximize`.
+
+@param {number} width width in pixels or `maximize`.
+@param {number} height height in pixels.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/rightClick.mustache

@@ -0,0 +1,14 @@
+Performs right click on a clickable element matched by semantic locator, CSS or XPath.
+
+```js
+// right click element with id el
+I.rightClick('#el');
+// right click link or button with text "Click me"
+I.rightClick('Click me');
+// right click button with text "Click me" inside .context
+I.rightClick('Click me', '.context');
+```
+
+@param {CodeceptJS.LocatorOrString} locator clickable element located by CSS|XPath|strict locator.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/saveElementScreenshot.mustache

@@ -0,0 +1,10 @@
+Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Filename is relative to output folder.
+
+```js
+I.saveElementScreenshot(`#submit`,'debug.png');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {string} fileName file name to save.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/saveScreenshot.mustache

@@ -0,0 +1,12 @@
+Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Filename is relative to output folder.
+Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
+
+```js
+I.saveScreenshot('debug.png');
+I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
+```
+
+@param {string} fileName file name to save.
+@param {boolean} [fullPage=false] (optional, `false` by default) flag to enable fullscreen screenshot mode.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/say.mustache

@@ -0,0 +1,10 @@
+Print a text in console log
+
+```js
+I.say('This is red', 'red'); //red is used
+I.say('This is blue', 'blue'); //blue is used
+I.say('This is by default'); //cyan is used
+```
+@param {string} text expected on console log.
+@param {string} [color='cyan'] color you want to use.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/scrollIntoView.mustache

@@ -0,0 +1,11 @@
+Scroll element into viewport.
+
+```js
+I.scrollIntoView('#submit');
+I.scrollIntoView('#submit', true);
+I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "center" });
+```
+
+@param {LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {ScrollIntoViewOptions|boolean} scrollIntoViewOptions either alignToTop=true|false or scrollIntoViewOptions. See https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/scrollPageToBottom.mustache

@@ -0,0 +1,6 @@
+Scroll page to the bottom.
+
+```js
+I.scrollPageToBottom();
+```
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/scrollPageToTop.mustache

@@ -0,0 +1,6 @@
+Scroll page to the top.
+
+```js
+I.scrollPageToTop();
+```
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/scrollTo.mustache

@@ -0,0 +1,12 @@
+Scrolls to element matched by locator.
+Extra shift can be set with offsetX and offsetY options.
+
+```js
+I.scrollTo('footer');
+I.scrollTo('#submit', 5, 5);
+```
+
+@param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+@param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/see.mustache

@@ -0,0 +1,11 @@
+Checks that a page contains a visible text.
+Use context parameter to narrow down the search.
+
+```js
+I.see('Welcome'); // text welcome on a page
+I.see('Welcome', '.content'); // text inside .content div
+I.see('Register', {css: 'form.register'}); // use strict locator
+```
+@param {string} text expected on page.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeAttributesOnElements.mustache

@@ -0,0 +1,9 @@
+Checks that all elements with given locator have given attributes.
+
+```js
+I.seeAttributesOnElements('//form', { method: "post"});
+```
+
+@param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {object} attributes attributes and their values to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeCheckboxIsChecked.mustache

@@ -0,0 +1,10 @@
+Verifies that the specified checkbox is checked.
+
+```js
+I.seeCheckboxIsChecked('Agree');
+I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
+I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
+```
+
+@param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeCookie.mustache

@@ -0,0 +1,8 @@
+Checks that cookie with given name exists.
+
+```js
+I.seeCookie('Auth');
+```
+
+@param {string} name cookie name.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeCssPropertiesOnElements.mustache

@@ -0,0 +1,9 @@
+Checks that all elements with given locator have given CSS properties.
+
+```js
+I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
+```
+
+@param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {object} cssProperties object with CSS properties and their values to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeCurrentUrlEquals.mustache

@@ -0,0 +1,11 @@
+Checks that current url is equal to provided one.
+If a relative url provided, a configured url will be prepended to it.
+So both examples will work:
+
+```js
+I.seeCurrentUrlEquals('/register');
+I.seeCurrentUrlEquals('http://my.site.com/register');
+```
+
+@param {string} url value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeElement.mustache

@@ -0,0 +1,8 @@
+Checks that a given Element is visible
+Element is located by CSS or XPath.
+
+```js
+I.seeElement('#modal');
+```
+@param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeElementInDOM.mustache

@@ -0,0 +1,8 @@
+Checks that a given Element is present in the DOM
+Element is located by CSS or XPath.
+
+```js
+I.seeElementInDOM('#modal');
+```
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInCurrentUrl.mustache

@@ -0,0 +1,8 @@
+Checks that current url contains a provided fragment.
+
+```js
+I.seeInCurrentUrl('/register'); // we are on registration page
+```
+
+@param {string} url a fragment to check
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInField.mustache

@@ -0,0 +1,12 @@
+Checks that the given input field or textarea equals to given value.
+For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
+
+```js
+I.seeInField('Username', 'davert');
+I.seeInField({css: 'form textarea'},'Type your comment here');
+I.seeInField('form input[type=hidden]','hidden_value');
+I.seeInField('#searchform input','Search');
+```
+@param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+@param {CodeceptJS.StringOrSecret} value value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInPopup.mustache

@@ -0,0 +1,8 @@
+Checks that the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`, contains the
+given string.
+
+```js
+I.seeInPopup('Popup text');
+```
+@param {string} text value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInSource.mustache

@@ -0,0 +1,7 @@
+Checks that the current page contains the given string in its raw source code.
+
+```js
+I.seeInSource('<h1>Green eggs &amp; ham</h1>');
+```
+@param {string} text value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInTitle.mustache

@@ -0,0 +1,8 @@
+Checks that title contains text.
+
+```js
+I.seeInTitle('Home Page');
+```
+
+@param {string} text text value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeNumberOfElements.mustache

@@ -0,0 +1,11 @@
+Asserts that an element appears a given number of times in the DOM.
+Element is located by label or name or CSS or XPath.
+
+
+```js
+I.seeNumberOfElements('#submitBtn', 1);
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} num number of elements.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeNumberOfVisibleElements.mustache

@@ -0,0 +1,10 @@
+Asserts that an element is visible a given number of times.
+Element is located by CSS or XPath.
+
+```js
+I.seeNumberOfVisibleElements('.buttons', 3);
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} num number of elements.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeTextEquals.mustache

@@ -0,0 +1,9 @@
+Checks that text is equal to provided one.
+
+```js
+I.seeTextEquals('text', 'h1');
+```
+
+@param {string} text element value to check.
+@param {CodeceptJS.LocatorOrString?} [context=null]  element located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeTitleEquals.mustache

@@ -0,0 +1,8 @@
+Checks that title is equal to provided one.
+
+```js
+I.seeTitleEquals('Test title.');
+```
+
+@param {string} text value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/selectOption.mustache

@@ -0,0 +1,21 @@
+Selects an option in a drop-down select.
+Field is searched by label | name | CSS | XPath.
+Option is selected by visible text or by value.
+
+```js
+I.selectOption('Choose Plan', 'Monthly'); // select by label
+I.selectOption('subscription', 'Monthly'); // match option by text
+I.selectOption('subscription', '0'); // or by value
+I.selectOption('//form/select[@name=account]','Premium');
+I.selectOption('form select[name=account]', 'Premium');
+I.selectOption({css: 'form select[name=account]'}, 'Premium');
+```
+
+Provide an array for the second argument to select multiple options.
+
+```js
+I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+```
+@param {LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
+@param {string|Array<*>} option visible text or value of option.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/setCookie.mustache

@@ -0,0 +1,16 @@
+Sets cookie(s).
+
+Can be a single cookie object or an array of cookies:
+
+```js
+I.setCookie({name: 'auth', value: true});
+
+// as array
+I.setCookie([
+  {name: 'auth', value: true},
+  {name: 'agree', value: true}
+]);
+```
+
+@param {Cookie|Array<Cookie>} cookie a cookie object or array of cookie objects.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/setGeoLocation.mustache

@@ -0,0 +1,12 @@
+Set the current geo location
+
+
+```js
+I.setGeoLocation(121.21, 11.56);
+I.setGeoLocation(121.21, 11.56, 10);
+```
+
+@param {number} latitude to set.
+@param {number} longitude to set
+@param {number=} altitude (optional, null by default) to set
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/switchTo.mustache

@@ -0,0 +1,9 @@
+Switches frame or in case of null locator reverts to parent.
+
+```js
+I.switchTo('iframe'); // switch to first iframe
+I.switchTo(); // switch back to main page
+```
+
+@param {?CodeceptJS.LocatorOrString} [locator=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/switchToNextTab.mustache

@@ -0,0 +1,10 @@
+Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
+
+```js
+I.switchToNextTab();
+I.switchToNextTab(2);
+```
+
+@param {number} [num] (optional) number of tabs to switch forward, default: 1.
+@param {number | null} [sec] (optional) time in seconds to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/switchToPreviousTab.mustache

@@ -0,0 +1,10 @@
+Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
+
+```js
+I.switchToPreviousTab();
+I.switchToPreviousTab(2);
+```
+
+@param {number} [num] (optional) number of tabs to switch backward, default: 1.
+@param {number?} [sec] (optional) time in seconds to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/type.mustache

@@ -0,0 +1,21 @@
+Types out the given text into an active field.
+To slow down typing use a second parameter, to set interval between key presses.
+_Note:_ Should be used when [`fillField`](#fillfield) is not an option.
+
+```js
+// passing in a string
+I.type('Type this out.');
+
+// typing values with a 100ms interval
+I.type('4141555311111111', 100);
+
+// passing in an array
+I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
+```
+
+@param {string|string[]} key or array of keys to type.
+@param {?number} [delay=null] (optional) delay in ms between key presses
+@returns {void} automatically synchronized promise through #recorder