diff --git a/CHANGELOG.md b/CHANGELOG.md index aaf20ea14..9ffca95f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4003,7 +4003,7 @@ This change allows using auto-completion when running a specific test. - PageObjects simplified to remove `_init()` extra method. Try updated generators and see [updated guide](https://codecept.io/pageobjects/#pageobject). - [Puppeteer] [Multiple sessions](https://codecept.io/acceptance/#multiple-sessions) enabled. Requires Puppeteer >= 1.5 - [Puppeteer] Stability improvement. Waits for for `load` event on page load. This strategy can be changed in config: - - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions) + - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md) - `getPageTimeout` config option to set maximum navigation time in milliseconds. Default is 30 seconds. - `waitForNavigation` method added. Explicitly waits for navigation to be finished. - [WebDriverIO][Protractor][Puppeteer][Nightmare] **Possible BC** `grabTextFrom` unified. Return a text for single matched element and an array of texts for multiple elements. @@ -4087,7 +4087,7 @@ Scenario('this test should throw error', I => { - Added Chinese translation ("zh-CN" and "zh-TW") by @TechQuery. - Fixed running tests from a different folder specified by `-c` option. - [Puppeteer] Added support for hash handling in URL by @gavoja. -- [Puppeteer] Fixed setting viewport size by @gavoja. See [Puppeteer issue](https://github.com/GoogleChrome/puppeteer/issues/1183) +- [Puppeteer] Fixed setting viewport size by @gavoja. See [Puppeteer issue](https://github.com/puppeteer/puppeteer/issues/1183) ## 1.1.7 diff --git a/docs/changelog.md b/docs/changelog.md index 1b27678ad..95f2c9cd2 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -3837,7 +3837,7 @@ This change allows using auto-completion when running a specific test. - PageObjects simplified to remove `_init()` extra method. Try updated generators and see [updated guide](https://codecept.io/pageobjects/#pageobject). - **[Puppeteer]** [Multiple sessions](https://codecept.io/acceptance/#multiple-sessions) enabled. Requires Puppeteer >= 1.5 - **[Puppeteer]** Stability improvement. Waits for for `load` event on page load. This strategy can be changed in config: - - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions) + - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md) - `getPageTimeout` config option to set maximum navigation time in milliseconds. Default is 30 seconds. - `waitForNavigation` method added. Explicitly waits for navigation to be finished. - [WebDriverIO][Protractor][Puppeteer][Nightmare] **Possible BC** `grabTextFrom` unified. Return a text for single matched element and an array of texts for multiple elements. @@ -3921,7 +3921,7 @@ Scenario('this test should throw error', I => { - Added Chinese translation ("zh-CN" and "zh-TW") by **[TechQuery](https://github.com/TechQuery)**. - Fixed running tests from a different folder specified by `-c` option. - **[Puppeteer]** Added support for hash handling in URL by **[gavoja](https://github.com/gavoja)**. -- **[Puppeteer]** Fixed setting viewport size by **[gavoja](https://github.com/gavoja)**. See [Puppeteer issue](https://github.com/GoogleChrome/puppeteer/issues/1183) +- **[Puppeteer]** Fixed setting viewport size by **[gavoja](https://github.com/gavoja)**. See [Puppeteer issue](https://github.com/puppeteer/puppeteer/issues/1183) ## 1.1.7 diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md index 5f5dbc585..7c054a153 100644 --- a/docs/custom-helpers.md +++ b/docs/custom-helpers.md @@ -5,7 +5,7 @@ title: Custom Helpers # Extending CodeceptJS With Custom Helpers -Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them. When `I` object is used in tests it delegates execution of its functions to currently enabled helper classes. +Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them. When `I` object is used in tests it delegates execution of its functions to currently enabled helper classes. Use Helpers to introduce low-level API to your tests without polluting test scenarios. Helpers can also be used to share functionality across different project and installed as npm packages. @@ -34,10 +34,9 @@ Helpers are classes inherited from [corresponding abstract class](https://github Created helper file should look like this: ```js -const Helper = require('@codeceptjs/helper'); +const Helper = require('@codeceptjs/helper') class MyHelper extends Helper { - // before/after hooks _before() { // remove if not used @@ -50,48 +49,43 @@ class MyHelper extends Helper { // add custom methods here // If you need to access other helpers // use: this.helpers['helperName'] - } -module.exports = MyHelper; +module.exports = MyHelper ``` When the helper is enabled in config all methods of a helper class are available in `I` object. For instance, if we add a new method to helper class: ```js -const Helper = require('@codeceptjs/helper'); +const Helper = require('@codeceptjs/helper') class MyHelper extends Helper { - doAwesomeThings() { - console.log('Hello from MyHelpr'); + console.log('Hello from MyHelpr') } - } ``` We can call a new method from within `I`: ```js -I.doAwesomeThings(); +I.doAwesomeThings() ``` > Methods starting with `_` are considered special and won't available in `I` object. - -Please note, `I` object can't be used helper class. As `I` object delegates its calls to helper classes, you can't make a circular dependency on it. Instead of calling `I` inside a helper, you can get access to other helpers by using `helpers` property of a helper. This allows you to access any other enabled helper by its name. +Please note, `I` object can't be used helper class. As `I` object delegates its calls to helper classes, you can't make a circular dependency on it. Instead of calling `I` inside a helper, you can get access to other helpers by using `helpers` property of a helper. This allows you to access any other enabled helper by its name. For instance, to perform a click with Playwright helper, do it like this: ```js doAwesomeThingsWithPlaywright() { const { Playwright } = this.helpers; - Playwright.click('Awesome'); + Playwright.click('Awesome'); } ``` - After a custom helper is finished you can update CodeceptJS Type Definitions by running: ```sh @@ -185,16 +179,16 @@ constructor(config) { Helpers may contain several hooks you can use to handle events of a test. Implement corresponding methods to them. -* `_init` - before all tests -* `_finishTest` - after all tests -* `_before` - before a test -* `_after` - after a test -* `_beforeStep` - before each step -* `_afterStep` - after each step -* `_beforeSuite` - before each suite -* `_afterSuite` - after each suite -* `_passed` - after a test passed -* `_failed` - after a test failed +- `_init` - before all tests +- `_finishTest` - after all tests +- `_before` - before a test +- `_after` - after a test +- `_beforeStep` - before each step +- `_afterStep` - after each step +- `_beforeSuite` - before each suite +- `_afterSuite` - after each suite +- `_passed` - after a test passed +- `_failed` - after a test failed Each implemented method should return a value as they will be added to global promise chain as well. @@ -225,7 +219,6 @@ Retry rules are available in array `recorder.retries`. The last retry rule can b With Typescript, just simply replacing `module.exports` with `export` for autocompletion. - ## Helper Examples ### Playwright Example @@ -233,14 +226,13 @@ With Typescript, just simply replacing `module.exports` with `export` for autoco In this example we take the power of Playwright to change geolocation in our tests: ```js -const Helper = require('@codeceptjs/helper'); +const Helper = require('@codeceptjs/helper') class MyHelper extends Helper { - async setGeoLocation(longitude, latitude) { - const { browserContext } = this.helpers.Playwright; - await browserContext.setGeolocation({ longitude, latitude }); - await Playwright.refreshPage(); + const { browserContext } = this.helpers.Playwright + await browserContext.setGeolocation({ longitude, latitude }) + await Playwright.refreshPage() } } ``` @@ -250,10 +242,10 @@ class MyHelper extends Helper { Next example demonstrates how to use WebDriver library to create your own test action. Method `seeAuthentication` will use `browser` instance of WebDriver to get access to cookies. Standard NodeJS assertion library will be used (you can use any). ```js -const Helper = require('@codeceptjs/helper'); +const Helper = require('@codeceptjs/helper') // use any assertion library you like -const assert = require('assert'); +const assert = require('assert') class MyHelper extends Helper { /** @@ -262,45 +254,43 @@ class MyHelper extends Helper { async seeAuthentication() { // access current browser of WebDriver helper const { WebDriver } = this.helpers - const { browser } = WebDriver; + const { browser } = WebDriver // get all cookies according to https://webdriver.io/api/protocol/cookie.html // any helper method should return a value in order to be added to promise chain - const res = await browser.cookie(); + const res = await browser.cookie() // get values - let cookies = res.value; + let cookies = res.value for (let k in cookies) { // check for a cookie - if (cookies[k].name != 'logged_in') continue; - assert.equal(cookies[k].value, 'yes'); - return; + if (cookies[k].name != 'logged_in') continue + assert.equal(cookies[k].value, 'yes') + return } - assert.fail(cookies, 'logged_in', "Auth cookie not set"); + assert.fail(cookies, 'logged_in', 'Auth cookie not set') } } -module.exports = MyHelper; +module.exports = MyHelper ``` ### Puppeteer Example -Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper. +Puppeteer has [nice and elegant API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/index.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper. -Let's see how we can use [emulate](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulateoptions) function to emulate iPhone browser in a test. +Let's see how we can use [emulate](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.page.emulate.md) function to emulate iPhone browser in a test. ```js -const Helper = require('@codeceptjs/helper'); -const puppeteer = require('puppeteer'); -const iPhone = puppeteer.devices['iPhone 6']; +const Helper = require('@codeceptjs/helper') +const puppeteer = require('puppeteer') +const iPhone = puppeteer.devices['iPhone 6'] class MyHelper extends Helper { - async emulateIPhone() { - const { page } = this.helpers.Puppeteer; - await page.emulate(iPhone); + const { page } = this.helpers.Puppeteer + await page.emulate(iPhone) } - } -module.exports = MyHelper; +module.exports = MyHelper ``` diff --git a/docs/helpers/Playwright.md b/docs/helpers/Playwright.md index 2df11ee95..e26a363b0 100644 --- a/docs/helpers/Playwright.md +++ b/docs/helpers/Playwright.md @@ -13,9 +13,9 @@ title: Playwright Uses [Playwright][1] library to run tests inside: -* Chromium -* Firefox -* Webkit (Safari) +- Chromium +- Firefox +- Webkit (Safari) This helper works with a browser out of the box with no additional tools required to install. @@ -33,8 +33,6 @@ Run `npx playwright install` to download browsers after `npm install`. Using playwright-core package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one. - - ## Configuration This helper should be configured in codecept.conf.(js|ts) @@ -43,53 +41,51 @@ Type: [object][6] ### Properties -* `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][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][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][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][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]. -* `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][49]. -* `customLocatorStrategies` **[object][6]?** custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(`[role="${selector}"]`) } }` -* `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or object) - passed directly to `browser.newContext`. - If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`), - those cookies are used instead and the configured `storageState` is ignored (no merge). - May include session cookies, auth tokens, localStorage and (if captured with - `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit. - - +- `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][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][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][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][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]. +- `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][49]. +- `customLocatorStrategies` **[object][6]?** custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(`[role="${selector}"]`) } }` +- `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or object) + passed directly to `browser.newContext`. + If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`), + those cookies are used instead and the configured `storageState` is ignored (no merge). + May include session cookies, auth tokens, localStorage and (if captured with + `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit. #### Video Recording Customization @@ -97,16 +93,16 @@ By default, video is saved to `output/video` dir. You can customize this path by `video`: enables video recording for failed tests; videos are saved into `output/videos` folder -* `keepVideoForPassedTests`: - save videos for passed tests -* `recordVideo`: [additional options for videos customization][2] +- `keepVideoForPassedTests`: - save videos for passed tests +- `recordVideo`: [additional options for videos customization][2] #### Trace Recording Customization Trace recording provides complete information on test execution and includes DOM snapshots, screenshots, and network requests logged during run. 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 +- `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder +- `keepTraceForPassedTests`: - save trace for passed tests #### HAR Recording Customization @@ -231,7 +227,7 @@ const { devices } = require('playwright'); } ``` -* #### Example #8: Launch test with a specific color scheme +- #### Example #8: Launch test with a specific color scheme ```js { @@ -244,7 +240,7 @@ const { devices } = require('playwright'); } ``` -* #### Example #9: Launch electron test +- #### Example #9: Launch electron test ```js { @@ -267,64 +263,64 @@ Note: When connecting to remote browser `show` and specific `chrome` options (e. Receive Playwright client from a custom helper by accessing `browser` for the Browser object or `page` for the current Page object: ```js -const { browser } = this.helpers.Playwright; -await browser.pages(); // List of pages in the browser +const { browser } = this.helpers.Playwright +await browser.pages() // List of pages in the browser // get current page -const { page } = this.helpers.Playwright; -await page.url(); // Get the url of the current page +const { page } = this.helpers.Playwright +await page.url() // Get the url of the current page -const { browserContext } = this.helpers.Playwright; -await browserContext.cookies(); // get current browser context +const { browserContext } = this.helpers.Playwright +await browserContext.cookies() // get current browser context ``` ### Parameters -* `config` +- `config` -### _addPopupListener +### \_addPopupListener Add the 'dialog' event listener to a page #### Parameters -* `page` +- `page` -### _contextLocator +### \_contextLocator Grab Locator if called within Context #### Parameters -* `locator` **any** +- `locator` **any** -### _createContextPage +### \_createContextPage -Create a new browser context with a page. +Create a new browser context with a page. Usually it should be run from a custom helper after call of `_startBrowser()` #### Parameters -* `contextOptions` **[object][6]?** See [https://playwright.dev/docs/api/class-browser#browser-new-context][7] +- `contextOptions` **[object][6]?** See [https://playwright.dev/docs/api/class-browser#browser-new-context][7] -### _getPageUrl +### \_getPageUrl Gets page URL including hash. -### _locate +### \_locate Get elements by different locator types, including strict locator Should be used in custom helpers: ```js -const elements = await this.helpers['Playwright']._locate({name: 'password'}); +const elements = await this.helpers['Playwright']._locate({ name: 'password' }) ``` #### Parameters -* `locator` +- `locator` -### _locateCheckable +### \_locateCheckable Find a checkbox by providing human-readable text: NOTE: Assumes the checkable element exists @@ -335,10 +331,10 @@ this.helpers['Playwright']._locateCheckable('I agree with terms and conditions') #### Parameters -* `locator` -* `providedContext` +- `locator` +- `providedContext` -### _locateClickable +### \_locateClickable Find a clickable element by providing human-readable text: @@ -348,22 +344,22 @@ this.helpers['Playwright']._locateClickable('Next page').then // ... #### Parameters -* `locator` +- `locator` -### _locateElement +### \_locateElement Get the first element by different locator types, including strict locator Should be used in custom helpers: ```js -const element = await this.helpers['Playwright']._locateElement({name: 'password'}); +const element = await this.helpers['Playwright']._locateElement({ name: 'password' }) ``` #### Parameters -* `locator` +- `locator` -### _locateFields +### \_locateFields Find field elements by providing human-readable text: @@ -373,15 +369,15 @@ this.helpers['Playwright']._locateFields('Your email').then // ... #### Parameters -* `locator` +- `locator` -### _setPage +### \_setPage Set current page #### Parameters -* `page` **[object][6]** page to set +- `page` **[object][6]** page to set ### acceptPopup @@ -395,9 +391,9 @@ Set the automatic popup response to Accept. This must be set before a popup is triggered. ```js -I.amAcceptingPopups(); -I.click('#triggerPopup'); -I.acceptPopup(); +I.amAcceptingPopups() +I.click('#triggerPopup') +I.acceptPopup() ``` ### amCancellingPopups @@ -406,9 +402,9 @@ Set the automatic popup response to Cancel/Dismiss. This must be set before a popup is triggered. ```js -I.amCancellingPopups(); -I.click('#triggerPopup'); -I.cancelPopup(); +I.amCancellingPopups() +I.click('#triggerPopup') +I.cancelPopup() ``` ### amOnPage @@ -417,14 +413,14 @@ Opens a web page in a browser. Requires relative or absolute url. If url starts with `/`, opens a web page of a site defined in `url` config parameter. ```js -I.amOnPage('/'); // opens main page of website -I.amOnPage('https://github.com'); // opens github -I.amOnPage('/login'); // opens a login page +I.amOnPage('/') // opens main page of website +I.amOnPage('https://github.com') // opens github +I.amOnPage('/login') // opens a login page ``` #### Parameters -* `url` **[string][9]** url path or global url. +- `url` **[string][9]** url path or global url. Returns **void** automatically synchronized promise through #recorder @@ -434,15 +430,15 @@ Appends text to a input field or textarea. Field is located by name, label, CSS or XPath ```js -I.appendField('#myTextField', 'appended'); +I.appendField('#myTextField', 'appended') // typing secret -I.appendField('password', secret('123456')); +I.appendField('password', secret('123456')) ``` #### Parameters -* `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator -* `value` **[string][9]** 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 @@ -453,14 +449,14 @@ Path to file is relative current codecept directory (where codecept.conf.ts or c File will be uploaded to remote system (if tests are running remotely). ```js -I.attachFile('Avatar', 'data/avatar.jpg'); -I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); +I.attachFile('Avatar', 'data/avatar.jpg') +I.attachFile('form input[name=avatar]', 'data/avatar.jpg') ``` #### Parameters -* `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. +- `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 @@ -471,19 +467,19 @@ Blocks traffic of a given URL or a list of URLs. Examples: ```js -I.blockTraffic('http://example.com/css/style.css'); -I.blockTraffic('http://example.com/css/*.css'); -I.blockTraffic('http://example.com/**'); -I.blockTraffic(/.css$/); +I.blockTraffic('http://example.com/css/style.css') +I.blockTraffic('http://example.com/css/*.css') +I.blockTraffic('http://example.com/**') +I.blockTraffic(/.css$/) ``` ```js -I.blockTraffic(['http://example.com/css/style.css', 'http://example.com/css/*.css']); +I.blockTraffic(['http://example.com/css/style.css', 'http://example.com/css/*.css']) ``` #### Parameters -* `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. +- `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 @@ -498,15 +494,15 @@ I.blur('.text-area') ```js //element `#product-tile` is focused -I.see('#add-to-cart-btn'); +I.see('#add-to-cart-btn') I.blur('#product-tile') -I.dontSee('#add-to-cart-btn'); +I.dontSee('#add-to-cart-btn') ``` #### Parameters -* `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. +- `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 @@ -533,16 +529,16 @@ 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.checkOption('#agree'); -I.checkOption('I Agree to Terms and Conditions'); -I.checkOption('agree', '//form'); +I.checkOption('#agree') +I.checkOption('I Agree to Terms and Conditions') +I.checkOption('agree', '//form') ``` #### Parameters -* `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` +- `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 @@ -552,14 +548,14 @@ Clears a cookie by name, if none provided clears all cookies. ```js -I.clearCookie(); -I.clearCookie('test'); +I.clearCookie() +I.clearCookie('test') ``` #### Parameters -* `cookieName` -* `cookie` **[string][9]?** (optional, `null` by default) cookie name +- `cookieName` +- `cookie` **[string][9]?** (optional, `null` by default) cookie name ### clearField @@ -578,8 +574,8 @@ Use `force` to bypass the [actionability][16] checks. #### Parameters -* `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. +- `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 @@ -592,29 +588,29 @@ The second parameter is a context (CSS or XPath locator) to narrow the search. ```js // simple link -I.click('Logout'); +I.click('Logout') // button of form -I.click('Submit'); +I.click('Submit') // CSS button -I.click('#form input[type=submit]'); +I.click('#form input[type=submit]') // XPath -I.click('//form/*[@type=submit]'); +I.click('//form/*[@type=submit]') // link in context -I.click('Logout', '#nav'); +I.click('Logout', '#nav') // using strict locator -I.click({css: 'nav a.login'}); +I.click({ css: 'nav a.login' }) ``` #### Parameters -* `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. +- `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 ````javascript -```js +;```js // click on element at position I.click('canvas', '.model', { position: { x: 20, y: 40 } }) @@ -631,15 +627,15 @@ Clicks link and waits for navigation (deprecated) #### Parameters -* `locator` -* `context` +- `locator` +- `context` ### closeCurrentTab Close current tab and switches to previous. ```js -I.closeCurrentTab(); +I.closeCurrentTab() ``` ### closeOtherTabs @@ -647,7 +643,7 @@ I.closeCurrentTab(); Close all tabs except for the current one. ```js -I.closeOtherTabs(); +I.closeOtherTabs() ``` ### dontSee @@ -656,14 +652,14 @@ Opposite to `see`. Checks that a text is not present on a page. Use context parameter to narrow down the search. ```js -I.dontSee('Login'); // assume we are already logged in. -I.dontSee('Login', '.nav'); // no login inside .nav element +I.dontSee('Login') // assume we are already logged in. +I.dontSee('Login', '.nav') // no login inside .nav element ``` #### Parameters -* `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. +- `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 @@ -672,14 +668,14 @@ Returns **void** automatically synchronized promise through #recorder Verifies that the specified checkbox is not checked. ```js -I.dontSeeCheckboxIsChecked('#agree'); // located by ID -I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label -I.dontSeeCheckboxIsChecked('agree'); // located by name +I.dontSeeCheckboxIsChecked('#agree') // located by ID +I.dontSeeCheckboxIsChecked('I agree to terms') // located by label +I.dontSeeCheckboxIsChecked('agree') // located by name ``` #### Parameters -* `field` **([string][9] | [object][6])** 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 @@ -688,12 +684,12 @@ Returns **void** automatically synchronized promise through #recorder Checks that cookie with given name does not exist. ```js -I.dontSeeCookie('auth'); // no auth cookie +I.dontSeeCookie('auth') // no auth cookie ``` #### Parameters -* `name` **[string][9]** cookie name. +- `name` **[string][9]** cookie name. Returns **void** automatically synchronized promise through #recorder @@ -703,13 +699,13 @@ Checks that current url is not equal to provided one. If a relative url provided, a configured url will be prepended to it. ```js -I.dontSeeCurrentUrlEquals('/login'); // relative url are ok -I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok +I.dontSeeCurrentUrlEquals('/login') // relative url are ok +I.dontSeeCurrentUrlEquals('http://mysite.com/login') // absolute urls are also ok ``` #### Parameters -* `url` **[string][9]** value to check. +- `url` **[string][9]** value to check. Returns **void** automatically synchronized promise through #recorder @@ -718,12 +714,12 @@ Returns **void** automatically synchronized promise through #recorder Opposite to `seeElement`. Checks that element is not visible (or in DOM) ```js -I.dontSeeElement('.modal'); // modal is not shown +I.dontSeeElement('.modal') // modal is not shown ``` #### Parameters -* `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. +- `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. Returns **void** automatically synchronized promise through #recorder @@ -732,12 +728,12 @@ Returns **void** automatically synchronized promise through #recorder Opposite to `seeElementInDOM`. Checks that element is not on page. ```js -I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not +I.dontSeeElementInDOM('.nav') // checks that element is not on page visible or not ``` #### Parameters -* `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. +- `locator` **([string][9] | [object][6])** located by CSS|XPath|Strict locator. Returns **void** automatically synchronized promise through #recorder @@ -747,7 +743,7 @@ Checks that current url does not contain a provided fragment. #### Parameters -* `url` **[string][9]** value to check. +- `url` **[string][9]** value to check. Returns **void** automatically synchronized promise through #recorder @@ -757,14 +753,14 @@ Checks that value of input field or textarea doesn't equal to given value Opposite to `seeInField`. ```js -I.dontSeeInField('email', 'user@user.com'); // field by name -I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS +I.dontSeeInField('email', 'user@user.com') // field by name +I.dontSeeInField({ css: 'form input.email' }, 'user@user.com') // field by CSS ``` #### Parameters -* `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator. -* `value` **([string][9] | [object][6])** 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 @@ -773,13 +769,13 @@ Returns **void** automatically synchronized promise through #recorder Checks that the current page does not contains the given string in its raw source code. ```js -I.dontSeeInSource('