diff --git a/docs/helpers/Playwright.md b/docs/helpers/Playwright.md index 55fab6c34..73d6b1384 100644 --- a/docs/helpers/Playwright.md +++ b/docs/helpers/Playwright.md @@ -508,6 +508,17 @@ Dismisses the active JavaScript popup, as created by window.alert|window.confirm ### checkOption +[Additional options][15] for check available as 3rd argument. + +Examples: + +```js +// click on element at position +I.checkOption('Agree', '.signup', { position: { x: 5, y: 5 } }) +``` + +> ⚠️ To avoid flakiness, option `force: true` is set by default + Selects a checkbox or radio button. Element is located by label or name or CSS or XPath. @@ -525,10 +536,7 @@ I.checkOption('agree', '//form'); - `context` **([string][9]? | [object][6])** (optional, `null` by default) element located by CSS | XPath | strict locator. - `options` -Returns **void** automatically synchronized promise through #recorder[Additional options][15] for check available as 3rd argument.Examples:```js -// click on element at position -I.checkOption('Agree', '.signup', { position: { x: 5, y: 5 } }) -```> ⚠️ To avoid flakiness, option `force: true` is set by default +Returns **void** automatically synchronized promise through #recorder ### clearCookie @@ -592,13 +600,19 @@ I.click({css: 'nav a.login'}); - `locator` **([string][9] | [object][6])** clickable link or button located by text, or any element located by CSS|XPath|strict locator. - `context` **([string][9]? | [object][6] | null)** (optional, `null` by default) element to search in CSS|XPath|Strict locator. -- `options` **any?** [Additional options][18] for click available as 3rd argument.Examples:```js - // click on element at position - I.click('canvas', '.model', { position: { x: 20, y: 40 } }) +- `options` **any?** [Additional options][18] for click available as 3rd argument. + +#### Examples - // make ctrl-click - I.click('.edit', null, { modifiers: ['Ctrl'] } ) - ``` +````javascript +```js +// click on element at position +I.click('canvas', '.model', { position: { x: 20, y: 40 } }) + +// make ctrl-click +I.click('.edit', null, { modifiers: ['Ctrl'] } ) +``` +```` Returns **void** automatically synchronized promise through #recorder @@ -812,6 +826,13 @@ Returns **void** automatically synchronized promise through #recorder ### dragAndDrop +```js +// specify coordinates for source position +I.dragAndDrop('img.src', 'img.dst', { sourcePosition: {x: 10, y: 10} }) +``` + +> When no option is set, custom drag and drop would be used, to use the dragAndDrop API from Playwright, please set options, for example `force: true` + Drag an item to a destination element. ```js @@ -822,10 +843,7 @@ I.dragAndDrop('#dragHandle', '#container'); - `srcElement` **([string][9] | [object][6])** located by CSS|XPath|strict locator. - `destElement` **([string][9] | [object][6])** located by CSS|XPath|strict locator. -- `options` **any?** [Additional options][19] can be passed as 3rd argument.```js - // specify coordinates for source position - I.dragAndDrop('img.src', 'img.dst', { sourcePosition: {x: 10, y: 10} }) - ```> When no option is set, custom drag and drop would be used, to use the dragAndDrop API from Playwright, please set options, for example `force: true` +- `options` **any?** [Additional options][19] can be passed as 3rd argument. Returns **void** automatically synchronized promise through #recorder @@ -860,8 +878,8 @@ Additional parameters of the function can be passed as an object argument: I.executeScript(({x, y}) => x + y, {x, y}); ``` -You can pass only one parameter into a function -but you can pass in array or object. +You can pass only one parameter into a function, +or you can pass in array or object. ```js I.executeScript(([x, y]) => x + y, [x, y]); @@ -1020,6 +1038,8 @@ Returns **[Promise][22]<[boolean][26]>** ### grabCookie +Returns cookie in JSON format. If name not passed returns all cookies for this domain. + Gets a cookie object by name. If none provided gets all cookies. Resumes test execution, so **should be used inside async function with `await`** operator. @@ -1033,7 +1053,7 @@ assert(cookie.value, '123456'); - `name` **[string][9]?** cookie name. -Returns **any** attribute valueReturns cookie in JSON format. If name not passed returns all cookies for this domain. +Returns **any** attribute value ### grabCssPropertyFrom @@ -1539,9 +1559,11 @@ I.openNewTab({ isMobile: true }); ### pressKey +_Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313][33]). + Presses a key in the browser (on a focused element). -_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][33]. +_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][34]. ```js I.pressKey('Backspace'); @@ -1602,7 +1624,7 @@ Some of the supported key names are: - `key` **([string][9] | [Array][10]<[string][9]>)** key or array of keys to press. -Returns **void** automatically synchronized promise through #recorder_Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313][34]). +Returns **void** automatically synchronized promise through #recorder ### pressKeyDown @@ -1672,6 +1694,18 @@ Returns **any** Promise ### resizeWindow +Unlike other drivers Playwright changes the size of a viewport, not the window! +Playwright does not control the window of a browser, so it can't adjust its real size. +It also can't maximize a window. + +Update configuration to change real window size on start: + +```js +// inside codecept.conf.js +// @codeceptjs/configure package must be installed +{ setWindowSize } = require('@codeceptjs/configure'); +``` + Resize the current window to provided width and height. First parameter can be set to `maximize`. @@ -1680,13 +1714,7 @@ First parameter can be set to `maximize`. - `width` **[number][20]** width in pixels or `maximize`. - `height` **[number][20]** height in pixels. -Returns **void** automatically synchronized promise through #recorderUnlike other drivers Playwright changes the size of a viewport, not the window! -Playwright does not control the window of a browser so it can't adjust its real size. -It also can't maximize a window.Update configuration to change real window size on start:```js -// inside codecept.conf.js -// @codeceptjs/configure package must be installed -{ setWindowSize } = require('@codeceptjs/configure'); -``` +Returns **void** automatically synchronized promise through #recorder ### restartBrowser @@ -2262,7 +2290,7 @@ I.switchToPreviousTab(2); 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`][33] is not an option. +_Note:_ Should be used when [`fillField`][34] is not an option. ```js // passing in a string @@ -2288,6 +2316,17 @@ Returns **void** automatically synchronized promise through #recorder ### uncheckOption +[Additional options][37] for uncheck available as 3rd argument. + +Examples: + +```js +// click on element at position +I.uncheckOption('Agree', '.signup', { position: { x: 5, y: 5 } }) +``` + +> ⚠️ To avoid flakiness, option `force: true` is set by default + Unselects a checkbox or radio button. Element is located by label or name or CSS or XPath. @@ -2305,10 +2344,7 @@ I.uncheckOption('agree', '//form'); - `context` **([string][9]? | [object][6])** (optional, `null` by default) element located by CSS | XPath | strict locator. - `options` -Returns **void** automatically synchronized promise through #recorder[Additional options][37] for uncheck available as 3rd argument.Examples:```js -// click on element at position -I.uncheckOption('Agree', '.signup', { position: { x: 5, y: 5 } }) -```> ⚠️ To avoid flakiness, option `force: true` is set by default +Returns **void** automatically synchronized promise through #recorder ### usePlaywrightTo @@ -2328,7 +2364,7 @@ I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => { #### Parameters - `description` **[string][9]** used to show in logs. -- `fn` **[function][21]** async function that executed with Playwright helper as argumen +- `fn` **[function][21]** async function that executed with Playwright helper as arguments ### wait @@ -2532,6 +2568,8 @@ Returns **void** automatically synchronized promise through #recorder ### waitForVisible +This method accepts [React selectors][43]. + Waits for an element to become visible on a page (by default waits for 1sec). Element can be located by CSS or XPath. @@ -2544,7 +2582,7 @@ I.waitForVisible('#popup'); - `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator. - `sec` **[number][20]** (optional, `1` by default) time in seconds to wait -Returns **void** automatically synchronized promise through #recorderThis method accepts [React selectors][43]. +Returns **void** automatically synchronized promise through #recorder ### waitInUrl @@ -2673,9 +2711,9 @@ Returns **void** automatically synchronized promise through #recorder [32]: https://github.com/microsoft/playwright/blob/main/docs/api.md#browsernewpageoptions -[33]: #fillfield +[33]: https://github.com/GoogleChrome/puppeteer/issues/1313 -[34]: https://github.com/GoogleChrome/puppeteer/issues/1313 +[34]: #fillfield [35]: #click diff --git a/docs/helpers/Puppeteer.md b/docs/helpers/Puppeteer.md index eecff835e..5f86202a8 100644 --- a/docs/helpers/Puppeteer.md +++ b/docs/helpers/Puppeteer.md @@ -44,7 +44,7 @@ Type: [object][4] - `disableScreenshots` **[boolean][20]?** don't save screenshot on failure. - `fullPageScreenshots` **[boolean][20]?** make full page screenshots on failure. - `uniqueScreenshotNames` **[boolean][20]?** option to prevent screenshot override if you have scenarios with the same name in different suites. -- `trace` **[boolean][20]?** record [tracing information][25] with screenshots. +- `trace` **[boolean][20]?** record [tracing information][24] with screenshots. - `keepTraceForPassedTests` **[boolean][20]?** save trace for passed tests. - `keepBrowserState` **[boolean][20]?** keep browser state between tests when `restart` is set to false. - `keepCookies` **[boolean][20]?** keep cookies between tests when `restart` is set to false. @@ -57,7 +57,7 @@ Type: [object][4] - `userAgent` **[string][6]?** user-agent string. - `manualStart` **[boolean][20]?** do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`. - `browser` **[string][6]?** can be changed to `firefox` when using [puppeteer-firefox][2]. -- `chrome` **[object][4]?** pass additional [Puppeteer run options][26]. +- `chrome` **[object][4]?** pass additional [Puppeteer run options][25]. - `highlightElement` **[boolean][20]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). @@ -211,7 +211,7 @@ This action supports [React locators](https://codecept.io/react#locators) ### _locateCheckable -Find a checkbox by providing human readable text: +Find a checkbox by providing human-readable text: NOTE: Assumes the checkable element exists ```js @@ -225,7 +225,7 @@ this.helpers['Puppeteer']._locateCheckable('I agree with terms and conditions'). ### _locateClickable -Find a clickable element by providing human readable text: +Find a clickable element by providing human-readable text: ```js this.helpers['Puppeteer']._locateClickable('Next page').then // ... @@ -237,7 +237,7 @@ this.helpers['Puppeteer']._locateClickable('Next page').then // ... ### _locateFields -Find field elements by providing human readable text: +Find field elements by providing human-readable text: ```js this.helpers['Puppeteer']._locateFields('Your email').then // ... @@ -324,6 +324,8 @@ This action supports [React locators](https://codecept.io/react#locators) ### attachFile +> ⚠ There is an [issue with file upload in Puppeteer 2.1.0 & 2.1.1][7], downgrade to 2.0.0 if you face it. + Attaches a file to element located by label, name, CSS or XPath Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located). File will be uploaded to remote system (if tests are running remotely). @@ -338,7 +340,7 @@ I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); - `locator` **([string][6] | [object][4])** field located by label|name|CSS|XPath|strict locator. - `pathToFile` **[string][6]** local file path relative to codecept.conf.ts or codecept.conf.js config file. -Returns **void** automatically synchronized promise through #recorder> ⚠ There is an [issue with file upload in Puppeteer 2.1.0 & 2.1.1][7], downgrade to 2.0.0 if you face it. +Returns **void** automatically synchronized promise through #recorder ### blur @@ -718,6 +720,7 @@ This action supports [React locators](https://codecept.io/react#locators) ### executeAsyncScript +Asynchronous scripts can also be executed with `executeScript` if a function returns a Promise. Executes async script on page. Provided function should execute a passed callback (as first argument) to signal it is finished. @@ -744,10 +747,12 @@ let val = await I.executeAsyncScript(function(url, done) { - `args` **...any** to be passed to function. - `fn` **([string][6] | [function][12])** function to be executed in browser context. -Returns **[Promise][13]<any>** script return valueAsynchronous scripts can also be executed with `executeScript` if a function returns a Promise. +Returns **[Promise][13]<any>** script return value ### executeScript +If a function returns a Promise, tt will wait for its resolution. + Executes sync script on a page. Pass arguments to function as additional parameters. Will return execution result to a test. @@ -777,7 +782,7 @@ let date = await I.executeScript(function(el) { - `args` **...any** to be passed to function. - `fn` **([string][6] | [function][12])** function to be executed in browser context. -Returns **[Promise][13]<any>** script return valueIf a function returns a Promise It will wait for it resolution. +Returns **[Promise][13]<any>** script return value ### fillField @@ -1236,7 +1241,7 @@ Returns **[Promise][13]<any>** WebElement of being used Web helper Sets a directory to where save files. Allows to test file downloads. Should be used with [FileSystem helper][16] to check that file were downloaded correctly. -By default files are saved to `output/downloads`. +By default, files are saved to `output/downloads`. This directory is cleaned on every `handleDownloads` call, to ensure no old files are kept. ```js @@ -1282,9 +1287,11 @@ I.openNewTab(); ### pressKey +_Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313][17]). + Presses a key in the browser (on a focused element). -_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][17]. +_Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][18]. ```js I.pressKey('Backspace'); @@ -1345,7 +1352,7 @@ Some of the supported key names are: - `key` **([string][6] | [Array][15]<[string][6]>)** key or array of keys to press. -Returns **void** automatically synchronized promise through #recorder_Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313][18]). +Returns **void** automatically synchronized promise through #recorder ### pressKeyDown @@ -1395,6 +1402,10 @@ Returns **void** automatically synchronized promise through #recorder ### resizeWindow +Unlike other drivers Puppeteer changes the size of a viewport, not the window! +Puppeteer does not control the window of a browser, so it can't adjust its real size. +It also can't maximize a window. + Resize the current window to provided width and height. First parameter can be set to `maximize`. @@ -1403,9 +1414,7 @@ First parameter can be set to `maximize`. - `width` **[number][10]** width in pixels or `maximize`. - `height` **[number][10]** height in pixels. -Returns **void** automatically synchronized promise through #recorderUnlike other drivers Puppeteer changes the size of a viewport, not the window! -Puppeteer does not control the window of a browser so it can't adjust its real size. -It also can't maximize a window. +Returns **void** automatically synchronized promise through #recorder ### rightClick @@ -1898,7 +1907,7 @@ I.switchToPreviousTab(2); 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`][17] is not an option. +_Note:_ Should be used when [`fillField`][18] is not an option. ```js // passing in a string @@ -2084,9 +2093,9 @@ Returns **void** automatically synchronized promise through #recorder ### waitForNavigation -Waits for navigation to finish. By default takes configured `waitForNavigation` option. +Waits for navigation to finish. By default, takes configured `waitForNavigation` option. -See [Pupeteer's reference][23] +See [Puppeteer's reference][23] #### Parameters @@ -2169,7 +2178,11 @@ I.waitForVisible('#popup'); - `locator` **([string][6] | [object][4])** element located by CSS|XPath|strict locator. - `sec` **[number][10]** (optional, `1` by default) time in seconds to wait -Returns **void** automatically synchronized promise through #recorderThis method accepts [React selectors][24]. +Returns **void** automatically synchronized promise through #recorder + + +This action supports [React locators](https://codecept.io/react#locators) + ### waitInUrl @@ -2270,9 +2283,9 @@ Returns **void** automatically synchronized promise through #recorder [16]: https://codecept.io/helpers/FileSystem -[17]: #fillfield +[17]: https://github.com/GoogleChrome/puppeteer/issues/1313 -[18]: https://github.com/GoogleChrome/puppeteer/issues/1313 +[18]: #fillfield [19]: #click @@ -2284,8 +2297,6 @@ Returns **void** automatically synchronized promise through #recorder [23]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions -[24]: https://codecept.io/react - -[25]: https://pptr.dev/api/puppeteer.tracing +[24]: https://pptr.dev/api/puppeteer.tracing -[26]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions +[25]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions diff --git a/docs/helpers/WebDriver.md b/docs/helpers/WebDriver.md index aa92f4abf..f0b40a105 100644 --- a/docs/helpers/WebDriver.md +++ b/docs/helpers/WebDriver.md @@ -482,6 +482,8 @@ This action supports [React locators](https://codecept.io/react#locators) ### attachFile +Appium: not tested + Attaches a file to element located by label, name, CSS or XPath Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located). File will be uploaded to remote system (if tests are running remotely). @@ -496,7 +498,7 @@ I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); - `locator` **([string][17] | [object][16])** field located by label|name|CSS|XPath|strict locator. - `pathToFile` **[string][17]** local file path relative to codecept.conf.ts or codecept.conf.js config file. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### blur @@ -525,10 +527,11 @@ Returns **void** automatically synchronized promise through #recorder ### cancelPopup -Dismisses the active JavaScript popup, as created by window.alert|window.confirm|window.prompt. +Dismisses the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`. ### checkOption +Appium: not tested Selects a checkbox or radio button. Element is located by label or name or CSS or XPath. @@ -545,7 +548,7 @@ I.checkOption('agree', '//form'); - `field` **([string][17] | [object][16])** checkbox located by label | name | CSS | XPath | strict locator. - `context` **([string][17]? | [object][16])** (optional, `null` by default) element located by CSS | XPath | strict locator. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### clearCookie @@ -671,6 +674,7 @@ This action supports [React locators](https://codecept.io/react#locators) ### dontSeeCheckboxIsChecked +Appium: not tested Verifies that the specified checkbox is not checked. ```js @@ -683,7 +687,7 @@ I.dontSeeCheckboxIsChecked('agree'); // located by name - `field` **([string][17] | [object][16])** located by label|name|CSS|XPath|strict locator. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### dontSeeCookie @@ -828,6 +832,7 @@ This action supports [React locators](https://codecept.io/react#locators) ### dragAndDrop +Appium: not tested Drag an item to a destination element. ```js @@ -839,7 +844,7 @@ I.dragAndDrop('#dragHandle', '#container'); - `srcElement` **([string][17] | [object][16])** located by CSS|XPath|strict locator. - `destElement` **([string][17] | [object][16])** located by CSS|XPath|strict locator. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### dragSlider @@ -890,6 +895,8 @@ Returns **[Promise][25]<any>** script return value ### executeScript +Wraps [execute][26] command. + Executes sync script on a page. Pass arguments to function as additional parameters. Will return execution result to a test. @@ -919,7 +926,7 @@ let date = await I.executeScript(function(el) { - `args` **...any** to be passed to function. - `fn` **([string][17] | [function][24])** function to be executed in browser context. -Returns **[Promise][25]<any>** script return valueWraps [execute][26] command. +Returns **[Promise][25]<any>** script return value ### fillField @@ -1419,6 +1426,8 @@ Returns **void** automatically synchronized promise through #recorder ### pressKey +_Note:_ In case a text field or textarea is focused be aware that some browsers do not respect active modifier when combining modifier keys with other keys. + Presses a key in the browser (on a focused element). _Hint:_ For populating text field or textarea, it is recommended to use [`fillField`][30]. @@ -1482,7 +1491,7 @@ Some of the supported key names are: - `key` **([string][17] | [Array][28]<[string][17]>)** key or array of keys to press. -Returns **void** automatically synchronized promise through #recorder_Note:_ In case a text field or textarea is focused be aware that some browsers do not respect active modifier when combining modifier keys with other keys. +Returns **void** automatically synchronized promise through #recorder ### pressKeyDown @@ -1532,6 +1541,8 @@ Returns **void** automatically synchronized promise through #recorder ### resizeWindow +Appium: not tested in web, in apps doesn't work + Resize the current window to provided width and height. First parameter can be set to `maximize`. @@ -1540,7 +1551,7 @@ First parameter can be set to `maximize`. - `width` **[number][22]** width in pixels or `maximize`. - `height` **[number][22]** height in pixels. -Returns **void** automatically synchronized promise through #recorderAppium: not tested in web, in apps doesn't work +Returns **void** automatically synchronized promise through #recorder ### rightClick @@ -1720,6 +1731,7 @@ Returns **void** automatically synchronized promise through #recorder ### seeCheckboxIsChecked +Appium: not tested Verifies that the specified checkbox is checked. ```js @@ -1732,7 +1744,7 @@ I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'}); - `field` **([string][17] | [object][16])** located by label|name|CSS|XPath|strict locator. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### seeCookie @@ -1983,6 +1995,7 @@ Returns **void** automatically synchronized promise through #recorder ### setCookie +Uses Selenium's JSON [cookie format][34]. Sets cookie(s). Can be a single cookie object or an array of cookies: @@ -2001,8 +2014,7 @@ I.setCookie([ - `cookie` **(Cookie | [Array][28]<Cookie>)** a cookie object or array of cookie objects. -Returns **void** automatically synchronized promise through #recorderUses Selenium's JSON [cookie -format][34]. +Returns **void** automatically synchronized promise through #recorder ### setGeoLocation @@ -2116,6 +2128,7 @@ Returns **void** automatically synchronized promise through #recorder ### uncheckOption +Appium: not tested Unselects a checkbox or radio button. Element is located by label or name or CSS or XPath. @@ -2132,7 +2145,7 @@ I.uncheckOption('agree', '//form'); - `field` **([string][17] | [object][16])** checkbox located by label | name | CSS | XPath | strict locator. - `context` **([string][17]? | [object][16])** (optional, `null` by default) element located by CSS | XPath | strict locator. -Returns **void** automatically synchronized promise through #recorderAppium: not tested +Returns **void** automatically synchronized promise through #recorder ### useWebDriverTo diff --git a/lib/helper/Playwright.js b/lib/helper/Playwright.js index 714b20c14..00dc49e56 100644 --- a/lib/helper/Playwright.js +++ b/lib/helper/Playwright.js @@ -666,7 +666,7 @@ class Playwright extends Helper { * ``` * * @param {string} description used to show in logs. - * @param {function} fn async function that executed with Playwright helper as argumen + * @param {function} fn async function that executed with Playwright helper as arguments */ usePlaywrightTo(description, fn) { return this._useTo(...arguments); @@ -946,10 +946,9 @@ class Playwright extends Helper { } /** - * {{> resizeWindow }} * * Unlike other drivers Playwright changes the size of a viewport, not the window! - * Playwright does not control the window of a browser so it can't adjust its real size. + * Playwright does not control the window of a browser, so it can't adjust its real size. * It also can't maximize a window. * * Update configuration to change real window size on start: @@ -959,6 +958,8 @@ class Playwright extends Helper { * // @codeceptjs/configure package must be installed * { setWindowSize } = require('@codeceptjs/configure'); * ```` + * + * {{> resizeWindow }} */ async resizeWindow(width, height) { if (width === 'maximize') { @@ -1058,8 +1059,6 @@ class Playwright extends Helper { } /** - * {{> dragAndDrop }} - * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-page#page-drag-and-drop) can be passed as 3rd argument. * * ```js * // specify coordinates for source position @@ -1067,6 +1066,10 @@ class Playwright extends Helper { * ``` * * > When no option is set, custom drag and drop would be used, to use the dragAndDrop API from Playwright, please set options, for example `force: true` + * + * {{> dragAndDrop }} + * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-page#page-drag-and-drop) can be passed as 3rd argument. + * */ async dragAndDrop(srcElement, destElement, options) { const src = new Locator(srcElement); @@ -1514,7 +1517,7 @@ class Playwright extends Helper { * * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-page#page-click) for click available as 3rd argument. * - * Examples: + * @example * * ```js * // click on element at position @@ -1547,8 +1550,6 @@ class Playwright extends Helper { /** * {{> doubleClick }} - * - * */ async doubleClick(locator, context = null) { return proceedClick.call(this, locator, context, { clickCount: 2 }); @@ -1556,15 +1557,12 @@ class Playwright extends Helper { /** * {{> rightClick }} - * - * */ async rightClick(locator, context = null) { return proceedClick.call(this, locator, context, { button: 'right' }); } /** - * {{> checkOption }} * * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-check) for check available as 3rd argument. * @@ -1575,6 +1573,9 @@ class Playwright extends Helper { * I.checkOption('Agree', '.signup', { position: { x: 5, y: 5 } }) * ``` * > ⚠️ To avoid flakiness, option `force: true` is set by default + * + * {{> checkOption }} + * */ async checkOption(field, context = null, options = { force: true }) { const elm = await this._locateCheckable(field, context); @@ -1583,7 +1584,6 @@ class Playwright extends Helper { } /** - * {{> uncheckOption }} * * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck) for uncheck available as 3rd argument. * @@ -1594,6 +1594,8 @@ class Playwright extends Helper { * I.uncheckOption('Agree', '.signup', { position: { x: 5, y: 5 } }) * ``` * > ⚠️ To avoid flakiness, option `force: true` is set by default + * + * {{> uncheckOption }} */ async uncheckOption(field, context = null, options = { force: true }) { const elm = await this._locateCheckable(field, context); @@ -1634,9 +1636,10 @@ class Playwright extends Helper { } /** - * {{> pressKeyWithKeyNormalization }} * * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)). + * + * {{> pressKeyWithKeyNormalization }} */ async pressKey(key) { const modifiers = []; @@ -1728,8 +1731,6 @@ class Playwright extends Helper { /** * {{> appendField }} - * - * */ async appendField(field, value) { const els = await findFields.call(this, field); @@ -1953,9 +1954,9 @@ class Playwright extends Helper { } /** - * {{> grabCookie }} - * * Returns cookie in JSON format. If name not passed returns all cookies for this domain. + * + * {{> grabCookie }} */ async grabCookie(name) { const cookies = await this.browserContext.cookies(); @@ -1986,8 +1987,8 @@ class Playwright extends Helper { * ```js * I.executeScript(({x, y}) => x + y, {x, y}); * ``` - * You can pass only one parameter into a function - * but you can pass in array or object. + * You can pass only one parameter into a function, + * or you can pass in array or object. * * ```js * I.executeScript(([x, y]) => x + y, [x, y]); @@ -2493,9 +2494,9 @@ class Playwright extends Helper { } /** - * {{> waitForVisible }} - * * This method accepts [React selectors](https://codecept.io/react). + * + * {{> waitForVisible }} */ async waitForVisible(locator, sec) { const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout; @@ -3260,7 +3261,7 @@ class Playwright extends Helper { /** * Returns all URLs of all network requests recorded so far during execution of test scenario. * - * @return {string} List of URLs recorded as a string, seperaeted by new lines after each URL + * @return {string} List of URLs recorded as a string, separated by new lines after each URL * @private */ _getTrafficDump() { diff --git a/lib/helper/Puppeteer.js b/lib/helper/Puppeteer.js index 41f2fd44a..7eda2b4b0 100644 --- a/lib/helper/Puppeteer.js +++ b/lib/helper/Puppeteer.js @@ -684,11 +684,13 @@ class Puppeteer extends Helper { } /** - * {{> resizeWindow }} * * Unlike other drivers Puppeteer changes the size of a viewport, not the window! - * Puppeteer does not control the window of a browser so it can't adjust its real size. + * Puppeteer does not control the window of a browser, so it can't adjust its real size. * It also can't maximize a window. + * + * {{> resizeWindow }} + * */ async resizeWindow(width, height) { if (width === 'maximize') { @@ -880,7 +882,7 @@ class Puppeteer extends Helper { } /** - * Find a checkbox by providing human readable text: + * Find a checkbox by providing human-readable text: * NOTE: Assumes the checkable element exists * * ```js @@ -895,7 +897,7 @@ class Puppeteer extends Helper { } /** - * Find a clickable element by providing human readable text: + * Find a clickable element by providing human-readable text: * * ```js * this.helpers['Puppeteer']._locateClickable('Next page').then // ... @@ -907,7 +909,7 @@ class Puppeteer extends Helper { } /** - * Find field elements by providing human readable text: + * Find field elements by providing human-readable text: * * ```js * this.helpers['Puppeteer']._locateFields('Your email').then // ... @@ -1119,7 +1121,7 @@ class Puppeteer extends Helper { * Sets a directory to where save files. Allows to test file downloads. * Should be used with [FileSystem helper](https://codecept.io/helpers/FileSystem) to check that file were downloaded correctly. * - * By default files are saved to `output/downloads`. + * By default, files are saved to `output/downloads`. * This directory is cleaned on every `handleDownloads` call, to ensure no old files are kept. * * ```js @@ -1291,9 +1293,9 @@ class Puppeteer extends Helper { } /** - * {{> pressKeyWithKeyNormalization }} - * * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)). + * + * {{> pressKeyWithKeyNormalization }} */ async pressKey(key) { const modifiers = []; @@ -1395,9 +1397,9 @@ class Puppeteer extends Helper { } /** - * {{> attachFile }} - * * > ⚠ There is an [issue with file upload in Puppeteer 2.1.0 & 2.1.1](https://github.com/puppeteer/puppeteer/issues/5420), downgrade to 2.0.0 if you face it. + * + * {{> attachFile }} */ async attachFile(locator, pathToFile) { const file = path.join(global.codecept_dir, pathToFile); @@ -1628,9 +1630,9 @@ class Puppeteer extends Helper { } /** - * {{> executeScript }} + * If a function returns a Promise, tt will wait for its resolution. * - * If a function returns a Promise It will wait for it resolution. + * {{> executeScript }} */ async executeScript(...args) { let context = this.page; @@ -1641,9 +1643,8 @@ class Puppeteer extends Helper { } /** - * {{> executeAsyncScript }} - * * Asynchronous scripts can also be executed with `executeScript` if a function returns a Promise. + * {{> executeAsyncScript }} */ async executeAsyncScript(...args) { const asyncFn = function () { @@ -2092,7 +2093,7 @@ class Puppeteer extends Helper { /** * {{> waitForVisible }} * - * This method accepts [React selectors](https://codecept.io/react). + * {{ react }} */ async waitForVisible(locator, sec) { const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout; @@ -2321,9 +2322,9 @@ class Puppeteer extends Helper { } /** - * Waits for navigation to finish. By default takes configured `waitForNavigation` option. + * Waits for navigation to finish. By default, takes configured `waitForNavigation` option. * - * See [Pupeteer's reference](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions) + * See [Puppeteer's reference](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions) * * @param {*} opts */ diff --git a/lib/helper/WebDriver.js b/lib/helper/WebDriver.js index 9fdcafb5a..5da7ce8a1 100644 --- a/lib/helper/WebDriver.js +++ b/lib/helper/WebDriver.js @@ -1104,8 +1104,9 @@ class WebDriver extends Helper { } /** - * {{> attachFile }} * Appium: not tested + * + * {{> attachFile }} */ async attachFile(locator, pathToFile) { let file = path.join(global.codecept_dir, pathToFile); @@ -1132,8 +1133,8 @@ class WebDriver extends Helper { } /** - * {{> checkOption }} * Appium: not tested + * {{> checkOption }} */ async checkOption(field, context = null) { const clickMethod = this.browser.isMobile && !this.browser.isW3C ? 'touchClick' : 'elementClick'; @@ -1152,8 +1153,8 @@ class WebDriver extends Helper { } /** - * {{> uncheckOption }} * Appium: not tested + * {{> uncheckOption }} */ async uncheckOption(field, context = null) { const clickMethod = this.browser.isMobile && !this.browser.isW3C ? 'touchClick' : 'elementClick'; @@ -1370,16 +1371,16 @@ class WebDriver extends Helper { } /** - * {{> seeCheckboxIsChecked }} * Appium: not tested + * {{> seeCheckboxIsChecked }} */ async seeCheckboxIsChecked(field) { return proceedSeeCheckbox.call(this, 'assert', field); } /** - * {{> dontSeeCheckboxIsChecked }} * Appium: not tested + * {{> dontSeeCheckboxIsChecked }} */ async dontSeeCheckboxIsChecked(field) { return proceedSeeCheckbox.call(this, 'negate', field); @@ -1606,10 +1607,9 @@ class WebDriver extends Helper { } /** - * {{> executeScript }} - * - * * Wraps [execute](http://webdriver.io/api/protocol/execute.html) command. + * + * {{> executeScript }} */ executeScript(...args) { return this.browser.execute.apply(this.browser, args); @@ -1731,11 +1731,8 @@ class WebDriver extends Helper { } /** + * Uses Selenium's JSON [cookie format](https://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object). * {{> setCookie }} - * - * - * Uses Selenium's JSON [cookie - * format](https://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object). */ async setCookie(cookie) { return this.browser.setCookies(cookie); @@ -1788,7 +1785,7 @@ class WebDriver extends Helper { } /** - * Dismisses the active JavaScript popup, as created by window.alert|window.confirm|window.prompt. + * Dismisses the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`. * */ async cancelPopup() { @@ -1862,9 +1859,9 @@ class WebDriver extends Helper { } /** - * {{> pressKeyWithKeyNormalization }} - * * _Note:_ In case a text field or textarea is focused be aware that some browsers do not respect active modifier when combining modifier keys with other keys. + * + * {{> pressKeyWithKeyNormalization }} */ async pressKey(key) { const modifiers = []; @@ -1923,8 +1920,9 @@ class WebDriver extends Helper { } /** - * {{> resizeWindow }} * Appium: not tested in web, in apps doesn't work + * + * {{> resizeWindow }} */ async resizeWindow(width, height) { return this._resizeBrowserWindow(this.browser, width, height); @@ -1976,8 +1974,8 @@ class WebDriver extends Helper { } /** - * {{> dragAndDrop }} * Appium: not tested + * {{> dragAndDrop }} */ async dragAndDrop(srcElement, destElement) { let sourceEl = await this._locate(srcElement);