codeceptjs 3.5.0 → 3.5.1-2.beta.7

package/docs/webapi/pressKeyWithKeyNormalization.mustache

@@ -1,60 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/refreshPage.mustache

@@ -1,6 +0,0 @@
-Reload the current page.
-
-```js
-I.refreshPage();
-```
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/resizeWindow.mustache

@@ -1,6 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/rightClick.mustache

@@ -1,14 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/saveElementScreenshot.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/saveScreenshot.mustache

@@ -1,12 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/say.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/scrollIntoView.mustache

@@ -1,11 +0,0 @@
-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} scrollIntoViewOptions see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/scrollPageToBottom.mustache

@@ -1,6 +0,0 @@
-Scroll page to the bottom.
-
-```js
-I.scrollPageToBottom();
-```
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/scrollPageToTop.mustache

@@ -1,6 +0,0 @@
-Scroll page to the top.
-
-```js
-I.scrollPageToTop();
-```
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/scrollTo.mustache

@@ -1,12 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/see.mustache

@@ -1,11 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeAttributesOnElements.mustache

@@ -1,9 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeCheckboxIsChecked.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeCookie.mustache

@@ -1,8 +0,0 @@
-Checks that cookie with given name exists.
-
-```js
-I.seeCookie('Auth');
-```
-
-@param {string} name cookie name.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeCssPropertiesOnElements.mustache

@@ -1,9 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeCurrentUrlEquals.mustache

@@ -1,11 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeElement.mustache

@@ -1,8 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeElementInDOM.mustache

@@ -1,8 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeInCurrentUrl.mustache

@@ -1,8 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeInField.mustache

@@ -1,12 +0,0 @@
-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 {string} value value to check.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeInPopup.mustache

@@ -1,8 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeInSource.mustache

@@ -1,7 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeInTitle.mustache

@@ -1,8 +0,0 @@
-Checks that title contains text.
-
-```js
-I.seeInTitle('Home Page');
-```
-
-@param {string} text text value to check.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeNumberOfElements.mustache

@@ -1,11 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeNumberOfVisibleElements.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeTextEquals.mustache

@@ -1,9 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/seeTitleEquals.mustache

@@ -1,8 +0,0 @@
-Checks that title is equal to provided one.
-
-```js
-I.seeTitleEquals('Test title.');
-```
-
-@param {string} text value to check.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/selectOption.mustache

@@ -1,21 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/setCookie.mustache

@@ -1,16 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/setGeoLocation.mustache

@@ -1,12 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/switchTo.mustache

@@ -1,9 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/switchToNextTab.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/switchToPreviousTab.mustache

@@ -1,10 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/type.mustache

@@ -1,21 +0,0 @@
-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 a _promise_ which is synchronized internally by recorder

package/docs/webapi/uncheckOption.mustache

@@ -1,13 +0,0 @@
-Unselects a checkbox or radio button.
-Element is located by label or name or CSS or XPath.
-
-The second parameter is a context (CSS or XPath locator) to narrow the search.
-
-```js
-I.uncheckOption('#agree');
-I.uncheckOption('I Agree to Terms and Conditions');
-I.uncheckOption('agree', '//form');
-```
-@param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/wait.mustache

@@ -1,8 +0,0 @@
-Pauses execution for a number of seconds.
-
-```js
-I.wait(2); // wait 2 secs
-```
-
-@param {number} sec number of second to wait.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForClickable.mustache

@@ -1,11 +0,0 @@
-Waits for element to be clickable (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitForClickable('.btn.continue');
-I.waitForClickable('.btn.continue', 5); // wait for 5 secs
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForDetached.mustache

@@ -1,10 +0,0 @@
-Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitForDetached('#popup');
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForElement.mustache

@@ -1,11 +0,0 @@
-Waits for element to be present on page (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitForElement('.btn.continue');
-I.waitForElement('.btn.continue', 5); // wait for 5 secs
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForEnabled.mustache

@@ -1,6 +0,0 @@
-Waits for element to become enabled (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec=1] (optional) time in seconds to wait, 1 by default.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForFunction.mustache

@@ -1,17 +0,0 @@
-Waits for a function to return true (waits for 1 sec by default).
-Running in browser context.
-
-```js
-I.waitForFunction(fn[, [args[, timeout]])
-```
-
-```js
-I.waitForFunction(() => window.requests == 0);
-I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
-I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
-```
-
-@param {string|function} fn to be executed in browser context.
-@param {any[]|number} [argsOrSec] (optional, `1` by default) arguments for function or seconds.
-@param {number} [sec] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForInvisible.mustache

@@ -1,10 +0,0 @@
-Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitForInvisible('#popup');
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForText.mustache

@@ -1,13 +0,0 @@
-Waits for a text to appear (by default waits for 1sec).
-Element can be located by CSS or XPath.
-Narrow down search results by providing context.
-
-```js
-I.waitForText('Thank you, form has been submitted');
-I.waitForText('Thank you, form has been submitted', 5, '#modal');
-```
-
-@param {string }text to wait for.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-@param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator.
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForValue.mustache

@@ -1,10 +0,0 @@
-Waits for the specified value to be in value attribute.
-
-```js
-I.waitForValue('//input', "GoodValue");
-```
-
-@param {LocatorOrString} field input field.
-@param {string }value expected value.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitForVisible.mustache

@@ -1,10 +0,0 @@
-Waits for an element to become visible on a page (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitForVisible('#popup');
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitInUrl.mustache

@@ -1,9 +0,0 @@
-Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
-
-```js
-I.waitInUrl('/info', 2);
-```
-
-@param {string} urlPart value to check.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitNumberOfVisibleElements.mustache

@@ -1,10 +0,0 @@
-Waits for a specified number of elements on the page.
-
-```js
-I.waitNumberOfVisibleElements('a', 3);
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} num number of elements.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder

package/docs/webapi/waitToHide.mustache

@@ -1,10 +0,0 @@
-Waits for an element to hide (by default waits for 1sec).
-Element can be located by CSS or XPath.
-
-```js
-I.waitToHide('#popup');
-```
-
-@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-⚠️ returns a _promise_ which is synchronized internally by recorder