diff --git a/docs/helpers/Playwright.md b/docs/helpers/Playwright.md index eb9acba61..3ca755434 100644 --- a/docs/helpers/Playwright.md +++ b/docs/helpers/Playwright.md @@ -39,46 +39,47 @@ Using playwright-core package, will prevent the download of browser binaries and This helper should be configured in codecept.conf.(js|ts) -Type: [object][5] +Type: [object][6] ### Properties -- `url` **[string][8]?** base url of website to be tested +- `url` **[string][9]?** base url of website to be tested - `browser` **(`"chromium"` | `"firefox"` | `"webkit"` | `"electron"`)?** a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium. -- `show` **[boolean][25]?** show browser window. -- `restart` **([string][8] | [boolean][25])?** restart strategy between tests. Possible values:- 'context' or **false** - restarts [browser context][43] but keeps running browser. Recommended by Playwright team to keep tests isolated. +- `show` **[boolean][26]?** show browser window. +- `restart` **([string][9] | [boolean][26])?** restart strategy between tests. Possible values:- 'context' or **false** - restarts [browser context][44] but keeps running browser. Recommended by Playwright team to keep tests isolated. - 'browser' or **true** - closes browser and opens it again between tests. - 'session' or 'keep' - keeps browser context and session, but cleans up cookies and localStorage between tests. The fastest option when running tests in windowed mode. Works with `keepCookies` and `keepBrowserState` options. This behavior was default before CodeceptJS 3.1 -- `timeout` **[number][19]?** - [timeout][44] in ms of all Playwright actions . -- `disableScreenshots` **[boolean][25]?** don't save screenshot on failure. +- `timeout` **[number][20]?** - [timeout][45] in ms of all Playwright actions . +- `disableScreenshots` **[boolean][26]?** don't save screenshot on failure. - `emulate` **any?** browser in device emulation mode. -- `video` **[boolean][25]?** enables video recording for failed tests; videos are saved into `output/videos` folder -- `keepVideoForPassedTests` **[boolean][25]?** save videos for passed tests; videos are saved into `output/videos` folder -- `trace` **[boolean][25]?** record [tracing information][45] with screenshots and snapshots. -- `keepTraceForPassedTests` **[boolean][25]?** save trace for passed tests. -- `fullPageScreenshots` **[boolean][25]?** make full page screenshots on failure. -- `uniqueScreenshotNames` **[boolean][25]?** option to prevent screenshot override if you have scenarios with the same name in different suites. -- `keepBrowserState` **[boolean][25]?** keep browser state between tests when `restart` is set to 'session'. -- `keepCookies` **[boolean][25]?** keep cookies between tests when `restart` is set to 'session'. -- `waitForAction` **[number][19]?** how long to wait after click, doubleClick or PressKey actions in ms. Default: 100. -- `waitForNavigation` **(`"load"` | `"domcontentloaded"` | `"commit"`)?** When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `commit`. Choose one of those options is possible. See [Playwright API][41]. -- `pressKeyDelay` **[number][19]?** Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField -- `getPageTimeout` **[number][19]?** config option to set maximum navigation time in milliseconds. -- `waitForTimeout` **[number][19]?** default wait* timeout in ms. Default: 1000. -- `basicAuth` **[object][5]?** the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} -- `windowSize` **[string][8]?** default window size. Set a dimension like `640x480`. +- `video` **[boolean][26]?** enables video recording for failed tests; videos are saved into `output/videos` folder +- `keepVideoForPassedTests` **[boolean][26]?** save videos for passed tests; videos are saved into `output/videos` folder +- `trace` **[boolean][26]?** record [tracing information][46] with screenshots and snapshots. +- `keepTraceForPassedTests` **[boolean][26]?** save trace for passed tests. +- `fullPageScreenshots` **[boolean][26]?** make full page screenshots on failure. +- `uniqueScreenshotNames` **[boolean][26]?** option to prevent screenshot override if you have scenarios with the same name in different suites. +- `keepBrowserState` **[boolean][26]?** keep browser state between tests when `restart` is set to 'session'. +- `keepCookies` **[boolean][26]?** keep cookies between tests when `restart` is set to 'session'. +- `waitForAction` **[number][20]?** how long to wait after click, doubleClick or PressKey actions in ms. Default: 100. +- `waitForNavigation` **(`"load"` | `"domcontentloaded"` | `"commit"`)?** When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `commit`. Choose one of those options is possible. See [Playwright API][42]. +- `pressKeyDelay` **[number][20]?** Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField +- `getPageTimeout` **[number][20]?** config option to set maximum navigation time in milliseconds. +- `waitForTimeout` **[number][20]?** default wait* timeout in ms. Default: 1000. +- `basicAuth` **[object][6]?** the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} +- `windowSize` **[string][9]?** default window size. Set a dimension like `640x480`. - `colorScheme` **(`"dark"` | `"light"` | `"no-preference"`)?** default color scheme. Possible values: `dark` | `light` | `no-preference`. -- `userAgent` **[string][8]?** user-agent string. -- `locale` **[string][8]?** locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ... -- `manualStart` **[boolean][25]?** do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`. -- `chromium` **[object][5]?** pass additional chromium options -- `firefox` **[object][5]?** pass additional firefox options -- `electron` **[object][5]?** (pass additional electron options -- `channel` **any?** (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge][46]. -- `ignoreLog` **[Array][9]<[string][8]>?** An array with console message types that are not logged to debug log. Default value is `['warning', 'log']`. E.g. you can set `[]` to log all messages. See all possible [values][47]. -- `ignoreHTTPSErrors` **[boolean][25]?** Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false` -- `bypassCSP` **[boolean][25]?** bypass Content Security Policy or CSP -- `highlightElement` **[boolean][25]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). +- `userAgent` **[string][9]?** user-agent string. +- `locale` **[string][9]?** locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ... +- `manualStart` **[boolean][26]?** do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`. +- `chromium` **[object][6]?** pass additional chromium options +- `firefox` **[object][6]?** pass additional firefox options +- `electron` **[object][6]?** (pass additional electron options +- `channel` **any?** (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge][47]. +- `ignoreLog` **[Array][10]<[string][9]>?** An array with console message types that are not logged to debug log. Default value is `['warning', 'log']`. E.g. you can set `[]` to log all messages. See all possible [values][48]. +- `ignoreHTTPSErrors` **[boolean][26]?** Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false` +- `bypassCSP` **[boolean][26]?** bypass Content Security Policy or CSP +- `highlightElement` **[boolean][26]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). +- `recordHar` **[object][6]?** record HAR and will be saved to `output/har`. See more of [HAR options][3]. @@ -99,6 +100,19 @@ Traces will be saved to `output/trace` - `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder - `keepTraceForPassedTests`: - save trace for passed tests +#### HAR Recording Customization + +A HAR file is an HTTP Archive file that contains a record of all the network requests that are made when a page is loaded. +It contains information about the request and response headers, cookies, content, timings, and more. You can use HAR files to mock network requests in your tests. +HAR will be saved to `output/har`. More info could be found here [https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har][3]. + + ... + recordHar: { + mode: 'minimal', // possible values: 'minimal'|'full'. + content: 'embed' // possible values: "omit"|"embed"|"attach". + } + ... + #### Example #1: Wait for 0 network connections. ```js @@ -142,7 +156,7 @@ Traces will be saved to `output/trace` } ``` -#### Example #4: Connect to remote browser by specifying [websocket endpoint][3] +#### Example #4: Connect to remote browser by specifying [websocket endpoint][4] ```js { @@ -160,7 +174,7 @@ Traces will be saved to `output/trace` #### Example #5: Testing with Chromium extensions -[official docs][4] +[official docs][5] ```js { @@ -283,7 +297,7 @@ Usually it should be run from a custom helper after call of `_startBrowser()` #### Parameters -- `contextOptions` **[object][5]?** See [https://playwright.dev/docs/api/class-browser#browser-new-context][6] +- `contextOptions` **[object][6]?** See [https://playwright.dev/docs/api/class-browser#browser-new-context][7] ### _getPageUrl @@ -359,13 +373,13 @@ Set current page #### Parameters -- `page` **[object][5]** page to set +- `page` **[object][6]** page to set ### acceptPopup Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt. Don't confuse popups with modal windows, as created by [various -libraries][7]. +libraries][8]. ### amAcceptingPopups @@ -402,7 +416,7 @@ I.amOnPage('/login'); // opens a login page #### Parameters -- `url` **[string][8]** url path or global url. +- `url` **[string][9]** url path or global url. Returns **void** automatically synchronized promise through #recorder @@ -419,8 +433,8 @@ I.appendField('password', secret('123456')); #### Parameters -- `field` **([string][8] | [object][5])** located by label|name|CSS|XPath|strict locator -- `value` **[string][8]** text value to append. +- `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator +- `value` **[string][9]** text value to append. Returns **void** automatically synchronized promise through #recorder @@ -437,8 +451,8 @@ I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); #### Parameters -- `locator` **([string][8] | [object][5])** field located by label|name|CSS|XPath|strict locator. -- `pathToFile` **[string][8]** local file path relative to codecept.conf.ts or codecept.conf.js config file. +- `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator. +- `pathToFile` **[string][9]** local file path relative to codecept.conf.ts or codecept.conf.js config file. Returns **void** automatically synchronized promise through #recorder @@ -461,12 +475,12 @@ I.blockTraffic(['http://example.com/css/style.css', 'http://example.com/css/*.cs #### Parameters -- `urls` **([string][8] | [Array][9] | [RegExp][10])** URL or a list of URLs to block . URL can contain * for wildcards. Example: [https://www.example.com**][11] to block all traffic for that domain. Regexp are also supported. +- `urls` **([string][9] | [Array][10] | [RegExp][11])** URL or a list of URLs to block . URL can contain * for wildcards. Example: [https://www.example.com**][12] to block all traffic for that domain. Regexp are also supported. ### blur Remove focus from a text input, button, etc. -Calls [blur][12] on the element. +Calls [blur][13] on the element. Examples: @@ -483,8 +497,8 @@ I.dontSee('#add-to-cart-btn'); #### Parameters -- `locator` **([string][8] | [object][5])** field located by label|name|CSS|XPath|strict locator. -- `options` **any?** Playwright only: [Additional options][13] for available options object as 2nd argument. +- `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator. +- `options` **any?** Playwright only: [Additional options][14] for available options object as 2nd argument. Returns **void** automatically synchronized promise through #recorder @@ -507,11 +521,11 @@ I.checkOption('agree', '//form'); #### Parameters -- `field` **([string][8] | [object][5])** checkbox located by label | name | CSS | XPath | strict locator. -- `context` **([string][8]? | [object][5])** (optional, `null` by default) element located by CSS | XPath | strict locator. +- `field` **([string][9] | [object][6])** checkbox located by label | name | CSS | XPath | strict locator. +- `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][14] for check available as 3rd argument.Examples:```js +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 @@ -528,7 +542,7 @@ I.clearCookie('test'); // Playwright currently doesn't support clear a particula #### Parameters -- `cookie` **[string][8]?** (optional, `null` by default) cookie name +- `cookie` **[string][9]?** (optional, `null` by default) cookie name ### clearField @@ -543,12 +557,12 @@ I.clearField('.text-area') I.clearField('#submit', { force: true }) ``` -Use `force` to bypass the [actionability][15] checks. +Use `force` to bypass the [actionability][16] checks. #### Parameters -- `locator` **([string][8] | [object][5])** field located by label|name|CSS|XPath|strict locator. -- `options` **any?** [Additional options][16] for available options object as 2nd argument. +- `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator. +- `options` **any?** [Additional options][17] for available options object as 2nd argument. ### click @@ -576,9 +590,9 @@ I.click({css: 'nav a.login'}); #### Parameters -- `locator` **([string][8] | [object][5])** clickable link or button located by text, or any element located by CSS|XPath|strict locator. -- `context` **([string][8]? | [object][5] | null)** (optional, `null` by default) element to search in CSS|XPath|Strict locator. -- `options` **any?** [Additional options][17] for click available as 3rd argument.Examples:```js +- `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 } }) @@ -625,8 +639,8 @@ I.dontSee('Login', '.nav'); // no login inside .nav element #### Parameters -- `text` **[string][8]** which is not present. -- `context` **([string][8] | [object][5])?** (optional) element located by CSS|XPath|strict locator in which to perfrom search. +- `text` **[string][9]** which is not present. +- `context` **([string][9] | [object][6])?** (optional) element located by CSS|XPath|strict locator in which to perfrom search. Returns **void** automatically synchronized promise through #recorder @@ -642,7 +656,7 @@ I.dontSeeCheckboxIsChecked('agree'); // located by name #### Parameters -- `field` **([string][8] | [object][5])** located by label|name|CSS|XPath|strict locator. +- `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator. Returns **void** automatically synchronized promise through #recorder @@ -656,7 +670,7 @@ I.dontSeeCookie('auth'); // no auth cookie #### Parameters -- `name` **[string][8]** cookie name. +- `name` **[string][9]** cookie name. Returns **void** automatically synchronized promise through #recorder @@ -672,7 +686,7 @@ I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also #### Parameters -- `url` **[string][8]** value to check. +- `url` **[string][9]** value to check. Returns **void** automatically synchronized promise through #recorder @@ -686,7 +700,7 @@ I.dontSeeElement('.modal'); // modal is not shown #### Parameters -- `locator` **([string][8] | [object][5])** located by CSS|XPath|Strict locator. +- `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. Returns **void** automatically synchronized promise through #recorder @@ -700,7 +714,7 @@ I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or #### Parameters -- `locator` **([string][8] | [object][5])** located by CSS|XPath|Strict locator. +- `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. Returns **void** automatically synchronized promise through #recorder @@ -710,7 +724,7 @@ Checks that current url does not contain a provided fragment. #### Parameters -- `url` **[string][8]** value to check. +- `url` **[string][9]** value to check. Returns **void** automatically synchronized promise through #recorder @@ -726,8 +740,8 @@ I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS #### Parameters -- `field` **([string][8] | [object][5])** located by label|name|CSS|XPath|strict locator. -- `value` **([string][8] | [object][5])** value to check. +- `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator. +- `value` **([string][9] | [object][6])** value to check. Returns **void** automatically synchronized promise through #recorder @@ -742,7 +756,7 @@ I.dontSeeInSource('