codeceptjs 4.0.0-rc.22 → 4.0.0-rc.24

package/docs/helpers/Playwright.md

@@ -45,39 +45,39 @@ Type: [object][6]
 
 *   `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.
+*   `show` **[boolean][27]?** show browser window.
+*   `restart` **([string][9] | [boolean][27])?** 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.
     *   '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][17]?** *   [timeout][45] in ms of all Playwright actions .
-*   `disableScreenshots` **[boolean][26]?** don't save screenshot on failure.
+*   `timeout` **[number][18]?** *   [timeout][45] in ms of all Playwright actions .
+*   `disableScreenshots` **[boolean][27]?** 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][17]?** 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][17]?** Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
-*   `getPageTimeout` **[number][17]?** config option to set maximum navigation time in milliseconds.
-*   `waitForTimeout` **[number][17]?** default wait* timeout in ms. Default: 1000.
+*   `video` **[boolean][27]?** enables video recording for failed tests; videos are saved into `output/videos` folder
+*   `keepVideoForPassedTests` **[boolean][27]?** save videos for passed tests; videos are saved into `output/videos` folder
+*   `trace` **[boolean][27]?** record [tracing information][46] with screenshots and snapshots.
+*   `keepTraceForPassedTests` **[boolean][27]?** save trace for passed tests.
+*   `fullPageScreenshots` **[boolean][27]?** make full page screenshots on failure.
+*   `uniqueScreenshotNames` **[boolean][27]?** option to prevent screenshot override if you have scenarios with the same name in different suites.
+*   `keepBrowserState` **[boolean][27]?** keep browser state between tests when `restart` is set to 'session'.
+*   `keepCookies` **[boolean][27]?** keep cookies between tests when `restart` is set to 'session'.
+*   `waitForAction` **[number][18]?** 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][43].
+*   `pressKeyDelay` **[number][18]?** Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
+*   `getPageTimeout` **[number][18]?** config option to set maximum navigation time in milliseconds.
+*   `waitForTimeout` **[number][18]?** 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()`.
+*   `manualStart` **[boolean][27]?** 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).
+*   `ignoreHTTPSErrors` **[boolean][27]?** Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
+*   `bypassCSP` **[boolean][27]?** bypass Content Security Policy or CSP
+*   `highlightElement` **[boolean][27]?** 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].
 *   `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or object)
@@ -635,13 +635,17 @@ I.click('//form/*[@type=submit]');
 I.click('Logout', '#nav');
 // using strict locator
 I.click({css: 'nav a.login'});
+// using ARIA role locator
+I.click({role: 'button', name: 'Submit'});
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][16].
+
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** (optional, `'//body'` by default) 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][16] for click available as 3rd argument. 
+*   `options` **any?** [Additional options][17] for click available as 3rd argument. 
 
 #### Examples
 
@@ -657,15 +661,6 @@ I.click('.edit', null, { modifiers: ['Ctrl'] } )
 
 Returns **void** automatically synchronized promise through #recorder
 
-### clickLink
-
-Clicks link and waits for navigation (deprecated)
-
-#### Parameters
-
-*   `locator` &#x20;
-*   `context`   
-
 ### clickXY
 
 Performs click at specific coordinates.
@@ -682,11 +677,11 @@ I.clickXY('#someElement', 50, 30);
 
 #### Parameters
 
-*   `locator` **([string][9] | [object][6] | [number][17])** Element to click on or X coordinate if no element.
-*   `x` **[number][17]?** X coordinate relative to element, or Y coordinate if locator is a number.
-*   `y` **[number][17]?** Y coordinate relative to element.
+*   `locator` **([string][9] | [object][6] | [number][18])** Element to click on or X coordinate if no element.
+*   `x` **[number][18]?** X coordinate relative to element, or Y coordinate if locator is a number.
+*   `y` **[number][18]?** Y coordinate relative to element.
 
-Returns **[Promise][18]<void>**&#x20;
+Returns **[Promise][19]<void>**&#x20;
 
 ### closeCurrentTab
 
@@ -934,7 +929,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.
+*   `options` **any?** [Additional options][20] can be passed as 3rd argument.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -951,7 +946,7 @@ I.dragSlider('#slider', -70);
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator.
-*   `offsetX` **[number][17]** position to drag. 
+*   `offsetX` **[number][18]** position to drag. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -980,10 +975,10 @@ If a function returns a Promise it will wait for its resolution.
 
 #### Parameters
 
-*   `fn` **([string][9] | [function][20])** function to be executed in browser context.
+*   `fn` **([string][9] | [function][21])** function to be executed in browser context.
 *   `arg` **any?** optional argument to pass to the function
 
-Returns **[Promise][18]<any>**&#x20;
+Returns **[Promise][19]<any>**&#x20;
 
 ### fillField
 
@@ -1001,10 +996,14 @@ I.fillField('password', secret('123456'));
 I.fillField('form#login input[name=username]', 'John');
 // or by strict locator
 I.fillField({css: 'form#login input[name=username]'}, 'John');
+// by ARIA role locator
+I.fillField({role: 'textbox', name: 'Email'}, 'hello@world.com');
 // within a context
 I.fillField('Name', 'John', '#section2');
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match fields by their accessible name and survive markup refactors. See [Locators][16].
+
 #### Parameters
 
 *   `field` **([string][9] | [object][6])** located by label|name|CSS|XPath|strict locator.
@@ -1040,7 +1039,7 @@ I.see('#add-to-cart-bnt');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator.
-*   `options` **any?** Playwright only: [Additional options][21] for available options object as 2nd argument. 
+*   `options` **any?** Playwright only: [Additional options][22] for available options object as 2nd argument. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -1080,7 +1079,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 ### grabAriaSnapshot
 
-Retrieves the ARIA snapshot for an element using Playwright's [`locator.ariaSnapshot`][22].
+Retrieves the ARIA snapshot for an element using Playwright's [`locator.ariaSnapshot`][23].
 This method returns a YAML representation of the accessibility tree that can be used for assertions.
 If no locator is provided, it captures the snapshot of the entire page body.
 
@@ -1092,13 +1091,13 @@ const formSnapshot = await I.grabAriaSnapshot('#login-form');
 expect(formSnapshot).toContain('textbox "Email"');
 ```
 
-[Learn more about ARIA snapshots][23]
+[Learn more about ARIA snapshots][24]
 
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator. Defaults to body element. 
 
-Returns **[Promise][18]<[string][9]>** YAML representation of the accessibility tree
+Returns **[Promise][19]<[string][9]>** YAML representation of the accessibility tree
 
 ### grabAttributeFrom
 
@@ -1115,7 +1114,7 @@ let hint = await I.grabAttributeFrom('#tooltip', 'title');
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 *   `attr` **[string][9]** attribute name.
 
-Returns **[Promise][18]<[string][9]>** attribute value
+Returns **[Promise][19]<[string][9]>** attribute value
 
 ### grabAttributeFromAll
 
@@ -1131,7 +1130,7 @@ let hints = await I.grabAttributeFromAll('.tooltip', 'title');
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 *   `attr` **[string][9]** attribute name.
 
-Returns **[Promise][18]<[Array][10]<[string][9]>>** attribute value
+Returns **[Promise][19]<[Array][10]<[string][9]>>** attribute value
 
 ### grabBrowserLogs
 
@@ -1143,9 +1142,9 @@ const errors = logs.map(l => ({ type: l.type(), text: l.text() })).filter(l => l
 console.log(JSON.stringify(errors));
 ```
 
-[Learn more about console messages][24]
+[Learn more about console messages][25]
 
-Returns **[Promise][18]<[Array][10]<any>>**&#x20;
+Returns **[Promise][19]<[Array][10]<any>>**&#x20;
 
 ### grabCheckedElementStatus
 
@@ -1154,9 +1153,9 @@ Return the checked status of given element.
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `options` **[object][6]?** See [https://playwright.dev/docs/api/class-locator#locator-is-checked][25] 
+*   `options` **[object][6]?** See [https://playwright.dev/docs/api/class-locator#locator-is-checked][26] 
 
-Returns **[Promise][18]<[boolean][26]>**&#x20;
+Returns **[Promise][19]<[boolean][27]>**&#x20;
 
 ### grabCookie
 
@@ -1192,7 +1191,7 @@ const value = await I.grabCssPropertyFrom('h3', 'font-weight');
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 *   `cssProperty` **[string][9]** CSS property name.
 
-Returns **[Promise][18]<[string][9]>** CSS value
+Returns **[Promise][19]<[string][9]>** CSS value
 
 ### grabCssPropertyFromAll
 
@@ -1208,7 +1207,7 @@ const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 *   `cssProperty` **[string][9]** CSS property name.
 
-Returns **[Promise][18]<[Array][10]<[string][9]>>** CSS value
+Returns **[Promise][19]<[Array][10]<[string][9]>>** CSS value
 
 ### grabCurrentUrl
 
@@ -1220,7 +1219,7 @@ let url = await I.grabCurrentUrl();
 console.log(`Current URL is [${url}]`);
 ```
 
-Returns **[Promise][18]<[string][9]>** current URL
+Returns **[Promise][19]<[string][9]>** current URL
 
 ### grabDataFromPerformanceTiming
 
@@ -1254,9 +1253,9 @@ Return the disabled status of given element.
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `options` **[object][6]?** See [https://playwright.dev/docs/api/class-locator#locator-is-disabled][27] 
+*   `options` **[object][6]?** See [https://playwright.dev/docs/api/class-locator#locator-is-disabled][28] 
 
-Returns **[Promise][18]<[boolean][26]>**&#x20;
+Returns **[Promise][19]<[boolean][27]>**&#x20;
 
 ### grabElementBoundingRect
 
@@ -1284,7 +1283,7 @@ const width = await I.grabElementBoundingRect('h3', 'width');
 *   `prop` &#x20;
 *   `elementSize` **[string][9]?** x, y, width or height of the given element.
 
-Returns **([Promise][18]<DOMRect> | [Promise][18]<[number][17]>)** Element bounding rectangle
+Returns **([Promise][19]<DOMRect> | [Promise][19]<[number][18]>)** Element bounding rectangle
 
 ### grabHTMLFrom
 
@@ -1301,7 +1300,7 @@ let postHTML = await I.grabHTMLFrom('#post');
 *   `locator` &#x20;
 *   `element` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[string][9]>** HTML code for an element
+Returns **[Promise][19]<[string][9]>** HTML code for an element
 
 ### grabHTMLFromAll
 
@@ -1317,7 +1316,7 @@ let postHTMLs = await I.grabHTMLFromAll('.post');
 *   `locator` &#x20;
 *   `element` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[Array][10]<[string][9]>>** HTML code for an element
+Returns **[Promise][19]<[Array][10]<[string][9]>>** HTML code for an element
 
 ### grabMetrics
 
@@ -1372,7 +1371,7 @@ const metrics = await I.grabMetrics();
 
 ```
 
-Returns **[Promise][18]<[Array][10]<[Object][6]>>**&#x20;
+Returns **[Promise][19]<[Array][10]<[Object][6]>>**&#x20;
 
 ### grabNumberOfOpenTabs
 
@@ -1383,7 +1382,7 @@ Resumes test execution, so **should be used inside async function with `await`**
 let tabs = await I.grabNumberOfOpenTabs();
 ```
 
-Returns **[Promise][18]<[number][17]>** number of open tabs
+Returns **[Promise][19]<[number][18]>** number of open tabs
 
 ### grabNumberOfVisibleElements
 
@@ -1398,7 +1397,7 @@ let numOfElements = await I.grabNumberOfVisibleElements('p');
 
 *   `locator` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[number][17]>** number of visible elements
+Returns **[Promise][19]<[number][18]>** number of visible elements
 
 ### grabPageScrollPosition
 
@@ -1409,7 +1408,7 @@ Resumes test execution, so **should be used inside an async function with `await
 let { x, y } = await I.grabPageScrollPosition();
 ```
 
-Returns **[Promise][18]<PageScrollPosition>** scroll position
+Returns **[Promise][19]<PageScrollPosition>** scroll position
 
 ### grabPopupText
 
@@ -1419,7 +1418,7 @@ Grab the text within the popup. If no popup is visible then it will return null
 await I.grabPopupText();
 ```
 
-Returns **[Promise][18]<([string][9] | null)>**&#x20;
+Returns **[Promise][19]<([string][9] | null)>**&#x20;
 
 ### grabRecordedNetworkTraffics
 
@@ -1443,7 +1442,7 @@ Resumes test execution, so **should be used inside async function with `await`**
 let pageSource = await I.grabSource();
 ```
 
-Returns **[Promise][18]<[string][9]>** source code
+Returns **[Promise][19]<[string][9]>** source code
 
 ### grabStorageState
 
@@ -1458,7 +1457,7 @@ Avoid committing it to source control and prefer storing it in a protected secre
 
 *   `options` **[object][6]?**  
 
-    *   `options.indexedDB` **[boolean][26]?** set to true to include IndexedDB in snapshot (Playwright >=1.51)```js
+    *   `options.indexedDB` **[boolean][27]?** set to true to include IndexedDB in snapshot (Playwright >=1.51)```js
         // basic usage
         const state = await I.grabStorageState();
         require('fs').writeFileSync('authState.json', JSON.stringify(state));
@@ -1482,7 +1481,7 @@ If multiple elements found returns first element.
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[string][9]>** attribute value
+Returns **[Promise][19]<[string][9]>** attribute value
 
 ### grabTextFromAll
 
@@ -1497,7 +1496,7 @@ let pins = await I.grabTextFromAll('#pin li');
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[Array][10]<[string][9]>>** attribute value
+Returns **[Promise][19]<[Array][10]<[string][9]>>** attribute value
 
 ### grabTitle
 
@@ -1508,7 +1507,7 @@ Resumes test execution, so **should be used inside async with `await`** operator
 let title = await I.grabTitle();
 ```
 
-Returns **[Promise][18]<[string][9]>** title
+Returns **[Promise][19]<[string][9]>** title
 
 ### grabTrafficUrl
 
@@ -1525,7 +1524,7 @@ I.grabTrafficUrl(/session.*start/);
 
 *   `urlMatch` **([string][9] | [RegExp][11])** Expected URL of request in network traffic. Can be a string or a regular expression.
 
-Returns **[Promise][18]<any>**&#x20;
+Returns **[Promise][19]<any>**&#x20;
 
 ### grabValueFrom
 
@@ -1541,7 +1540,7 @@ let email = await I.grabValueFrom('input[name=email]');
 
 *   `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[string][9]>** attribute value
+Returns **[Promise][19]<[string][9]>** attribute value
 
 ### grabValueFromAll
 
@@ -1556,7 +1555,7 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 *   `locator` **([string][9] | [object][6])** field located by label|name|CSS|XPath|strict locator.
 
-Returns **[Promise][18]<[Array][10]<[string][9]>>** attribute value
+Returns **[Promise][19]<[Array][10]<[string][9]>>** attribute value
 
 ### grabWebElement
 
@@ -1571,7 +1570,7 @@ const webElement = await I.grabWebElement('#button');
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<any>** WebElement of being used Web helper
+Returns **[Promise][19]<any>** WebElement of being used Web helper
 
 ### grabWebElements
 
@@ -1586,7 +1585,7 @@ const webElements = await I.grabWebElements('#button');
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 
-Returns **[Promise][18]<any>** WebElement of being used Web helper
+Returns **[Promise][19]<any>** WebElement of being used Web helper
 
 ### grabWebSocketMessages
 
@@ -1599,7 +1598,7 @@ Returns **[Array][10]<any>**&#x20;
 Handles a file download. A file name is required to save the file on disk.
 Files are saved to "output" directory.
 
-Should be used with [FileSystem helper][28] to check that file were downloaded correctly.
+Should be used with [FileSystem helper][29] to check that file were downloaded correctly.
 
 ```js
 I.handleDownloads('downloads/avatar.jpg');
@@ -1613,11 +1612,11 @@ I.waitForFile('avatar.jpg', 5);
 
 *   `fileName` **[string][9]** set filename for downloaded file
 
-Returns **[Promise][18]<void>**&#x20;
+Returns **[Promise][19]<void>**&#x20;
 
 ### makeApiRequest
 
-Performs [api request][29] using
+Performs [api request][30] using
 the cookies from the current browser session.
 
 ```js
@@ -1634,22 +1633,22 @@ I.makeApiRequest('PATCH', )
 *   `url` **[string][9]** endpoint
 *   `options` **[object][6]** request options depending on method used
 
-Returns **[Promise][18]<[object][6]>** response
+Returns **[Promise][19]<[object][6]>** response
 
 ### mockRoute
 
-Mocks network request using [`browserContext.route`][30] of Playwright
+Mocks network request using [`browserContext.route`][31] of Playwright
 
 ```js
 I.mockRoute(/(.png$)|(.jpg$)/, route => route.abort());
 ```
 
-This method allows intercepting and mocking requests & responses. [Learn more about it][31]
+This method allows intercepting and mocking requests & responses. [Learn more about it][32]
 
 #### Parameters
 
 *   `url` **([string][9] | [RegExp][11])?** URL, regex or pattern for to match URL
-*   `handler` **[function][20]?** a function to process request
+*   `handler` **[function][21]?** a function to process request
 
 ### mockTraffic
 
@@ -1687,8 +1686,8 @@ I.moveCursorTo('#submit', '.container');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
-*   `offsetX` **([number][17] | [string][9] | [object][6])** (optional, `0` by default) X-axis offset or context locator. 
-*   `offsetY` **[number][17]** (optional, `0` by default) Y-axis offset. 
+*   `offsetX` **([number][18] | [string][9] | [object][6])** (optional, `0` by default) X-axis offset or context locator. 
+*   `offsetY` **[number][18]** (optional, `0` by default) Y-axis offset. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -1700,7 +1699,7 @@ Open new tab and automatically switched to new tab
 I.openNewTab();
 ```
 
-You can pass in [page options][32] to emulate device on this page
+You can pass in [page options][33] to emulate device on this page
 
 ```js
 // enable mobile
@@ -1713,11 +1712,11 @@ I.openNewTab({ isMobile: true });
 
 ### pressKey
 
-*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313][33]).
+*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313][34]).
 
 Presses a key in the browser (on a focused element).
 
-*Hint:* For populating text field or textarea, it is recommended to use [`fillField`][34].
+*Hint:* For populating text field or textarea, it is recommended to use [`fillField`][35].
 
 ```js
 I.pressKey('Backspace');
@@ -1784,7 +1783,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 Presses a key in the browser and leaves it in a down state.
 
-To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][35]).
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][36]).
 
 ```js
 I.pressKeyDown('Control');
@@ -1802,7 +1801,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 Releases a key in the browser which was previously set to a down state.
 
-To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][35]).
+To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][36]).
 
 ```js
 I.pressKeyDown('Control');
@@ -1842,7 +1841,7 @@ Replaying from HAR
 #### Parameters
 
 *   `harFilePath` **[string][9]** Path to recorded HAR file
-*   `opts` **[object][6]?** [Options for replaying from HAR][36]
+*   `opts` **[object][6]?** [Options for replaying from HAR][37]
 
 Returns **any** Promise<void>
 
@@ -1865,8 +1864,8 @@ First parameter can be set to `maximize`.
 
 #### Parameters
 
-*   `width` **[number][17]** width in pixels or `maximize`.
-*   `height` **[number][17]** height in pixels.
+*   `width` **[number][18]** width in pixels or `maximize`.
+*   `height` **[number][18]** height in pixels.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -1920,7 +1919,7 @@ I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scro
 #### Parameters
 
 *   `fileName` **[string][9]** file name to save.
-*   `fullPage` **[boolean][26]** (optional, `false` by default) flag to enable fullscreen screenshot mode. 
+*   `fullPage` **[boolean][27]** (optional, `false` by default) flag to enable fullscreen screenshot mode. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -1957,8 +1956,8 @@ I.scrollTo('#submit', 5, 5);
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
-*   `offsetX` **[number][17]** (optional, `0` by default) X-axis offset. 
-*   `offsetY` **[number][17]** (optional, `0` by default) Y-axis offset. 
+*   `offsetX` **[number][18]** (optional, `0` by default) X-axis offset. 
+*   `offsetY` **[number][18]** (optional, `0` by default) Y-axis offset. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2083,8 +2082,12 @@ The second parameter is a context (CSS or XPath locator) to narrow the search.
 ```js
 I.seeElement('#modal');
 I.seeElement('#modal', '#container');
+// using ARIA role locator
+I.seeElement({role: 'dialog'});
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][16].
+
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** located by CSS|XPath|strict locator.
@@ -2200,7 +2203,7 @@ I.seeNumberOfElements('#submitBtn', 1);
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `num` **[number][17]** number of elements.
+*   `num` **[number][18]** number of elements.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2216,7 +2219,7 @@ I.seeNumberOfVisibleElements('.buttons', 3);
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `num` **[number][17]** number of elements.
+*   `num` **[number][18]** number of elements.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2288,7 +2291,7 @@ await I.seeTraffic({
     *   `opts.url` **[string][9]** Expected URL of request in network traffic
     *   `opts.parameters` **[Object][6]?** Expected parameters of that request in network traffic
     *   `opts.requestPostData` **[Object][6]?** Expected that request contains post data in network traffic
-    *   `opts.timeout` **[number][17]?** Timeout to wait for request in seconds. Default is 10 seconds. 
+    *   `opts.timeout` **[number][18]?** Timeout to wait for request in seconds. Default is 10 seconds. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2397,7 +2400,7 @@ If no handler is passed, all mock requests for the rote are disabled.
 #### Parameters
 
 *   `url` **([string][9] | [RegExp][11])?** URL, regex or pattern for to match URL
-*   `handler` **[function][20]?** a function to process request
+*   `handler` **[function][21]?** a function to process request
 
 ### stopRecordingTraffic
 
@@ -2443,7 +2446,7 @@ I.switchToNextTab(2);
 
 #### Parameters
 
-*   `num` **[number][17]**  
+*   `num` **[number][18]**  
 
 ### switchToPreviousTab
 
@@ -2456,13 +2459,13 @@ I.switchToPreviousTab(2);
 
 #### Parameters
 
-*   `num` **[number][17]**  
+*   `num` **[number][18]**  
 
 ### type
 
 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`][34] is not an option.
+*Note:* Should be used when [`fillField`][35] is not an option.
 
 ```js
 // passing in a string
@@ -2481,14 +2484,14 @@ I.type(secret('123456'));
 #### Parameters
 
 *   `keys` &#x20;
-*   `delay` **[number][17]?** (optional) delay in ms between key presses 
+*   `delay` **[number][18]?** (optional) delay in ms between key presses 
 *   `key` **([string][9] | [Array][10]<[string][9]>)** or array of keys to type.
 
 Returns **void** automatically synchronized promise through #recorder
 
 ### uncheckOption
 
-[Additional options][37] for uncheck available as 3rd argument.
+[Additional options][38] for uncheck available as 3rd argument.
 
 Examples:
 
@@ -2525,7 +2528,7 @@ Use Playwright API inside a test.
 First argument is a description of an action.
 Second argument is async function that gets this helper as parameter.
 
-{ [`page`][38], [`browserContext`][39] [`browser`][40] } objects from Playwright API are available.
+{ [`page`][39], [`browserContext`][40] [`browser`][41] } objects from Playwright API are available.
 
 ```js
 I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => {
@@ -2536,7 +2539,7 @@ I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => {
 #### Parameters
 
 *   `description` **[string][9]** used to show in logs.
-*   `fn` **[function][20]** async function that executed with Playwright helper as arguments
+*   `fn` **[function][21]** async function that executed with Playwright helper as arguments
 
 ### wait
 
@@ -2548,7 +2551,7 @@ I.wait(2); // wait 2 secs
 
 #### Parameters
 
-*   `sec` **[number][17]** number of second to wait.
+*   `sec` **[number][18]** number of second to wait.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2575,7 +2578,7 @@ I.waitForClickable('.btn.continue', 5); // wait for 5 secs
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
 *   `waitTimeout` &#x20;
-*   `sec` **[number][17]?** (optional, `1` by default) time in seconds to wait
+*   `sec` **[number][18]?** (optional, `1` by default) time in seconds to wait
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2590,7 +2593,7 @@ I.waitForCookie("token");
 #### Parameters
 
 *   `name` **[string][9]** expected cookie name.
-*   `sec` **[number][17]** (optional, `3` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `3` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2606,7 +2609,7 @@ I.waitForDetached('#popup');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2618,7 +2621,7 @@ Element can be located by CSS or XPath.
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional) time in seconds to wait, 1 by default. 
+*   `sec` **[number][18]** (optional) time in seconds to wait, 1 by default. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2635,7 +2638,7 @@ I.waitForElement('.btn.continue', 5); // wait for 5 secs
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]?** (optional, `1` by default) time in seconds to wait
+*   `sec` **[number][18]?** (optional, `1` by default) time in seconds to wait
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2647,7 +2650,7 @@ Element can be located by CSS or XPath.
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional) time in seconds to wait, 1 by default. 
+*   `sec` **[number][18]** (optional) time in seconds to wait, 1 by default. 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2668,9 +2671,9 @@ I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and
 
 #### Parameters
 
-*   `fn` **([string][9] | [function][20])** to be executed in browser context.
-*   `argsOrSec` **([Array][10]<any> | [number][17])?** (optional, `1` by default) arguments for function or seconds. 
-*   `sec` **[number][17]?** (optional, `1` by default) time in seconds to wait 
+*   `fn` **([string][9] | [function][21])** to be executed in browser context.
+*   `argsOrSec` **([Array][10]<any> | [number][18])?** (optional, `1` by default) arguments for function or seconds. 
+*   `sec` **[number][18]?** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2686,7 +2689,7 @@ I.waitForInvisible('#popup');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2694,7 +2697,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 Waits for navigation to finish. By default, it takes configured `waitForNavigation` option.
 
-See [Playwright's reference][41]
+See [Playwright's reference][42]
 
 #### Parameters
 
@@ -2710,8 +2713,8 @@ I.waitForNumberOfTabs(2);
 
 #### Parameters
 
-*   `expectedTabs` **[number][17]** expecting the number of tabs.
-*   `sec` **[number][17]** number of secs to wait.
+*   `expectedTabs` **[number][18]** expecting the number of tabs.
+*   `sec` **[number][18]** number of secs to wait.
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2726,8 +2729,8 @@ I.waitForRequest(request => request.url() === 'http://example.com' && request.me
 
 #### Parameters
 
-*   `urlOrPredicate` **([string][9] | [function][20])**&#x20;
-*   `sec` **[number][17]?** seconds to wait 
+*   `urlOrPredicate` **([string][9] | [function][21])**&#x20;
+*   `sec` **[number][18]?** seconds to wait 
 
 ### waitForResponse
 
@@ -2740,8 +2743,8 @@ I.waitForResponse(response => response.url() === 'https://example.com' && respon
 
 #### Parameters
 
-*   `urlOrPredicate` **([string][9] | [function][20])**&#x20;
-*   `sec` **[number][17]?** number of seconds to wait 
+*   `urlOrPredicate` **([string][9] | [function][21])**&#x20;
+*   `sec` **[number][18]?** number of seconds to wait 
 
 ### waitForText
 
@@ -2757,7 +2760,7 @@ I.waitForText('Thank you, form has been submitted', 5, '#modal');
 #### Parameters
 
 *   `text` **[string][9]** to wait for.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 *   `context` **([string][9] | [object][6])?** (optional) element located by CSS|XPath|strict locator. 
 
 Returns **void** automatically synchronized promise through #recorder
@@ -2766,7 +2769,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 Waits for page navigates to a new URL or reloads. By default, it takes configured `waitForNavigation` option.
 
-See [Playwright's reference][42]
+See [Playwright's reference][43]
 
 #### Parameters
 
@@ -2785,14 +2788,12 @@ I.waitForValue('//input', "GoodValue");
 
 *   `field` **([string][9] | [object][6])** input field.
 *   `value` **[string][9]** expected value.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 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.
 
@@ -2803,7 +2804,7 @@ I.waitForVisible('#popup');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2818,7 +2819,7 @@ I.waitInUrl('/info', 2);
 #### Parameters
 
 *   `urlPart` **[string][9]** value to check.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2833,8 +2834,8 @@ I.waitNumberOfVisibleElements('a', 3);
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `num` **[number][17]** number of elements.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `num` **[number][18]** number of elements.
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2850,7 +2851,7 @@ I.waitToHide('#popup');
 #### Parameters
 
 *   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2866,7 +2867,7 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 #### Parameters
 
 *   `urlPart` **[string][9]** value to check.
-*   `sec` **[number][17]** (optional, `1` by default) time in seconds to wait 
+*   `sec` **[number][18]** (optional, `1` by default) time in seconds to wait 
 
 Returns **void** automatically synchronized promise through #recorder
 
@@ -2900,61 +2901,61 @@ Returns **void** automatically synchronized promise through #recorder
 
 [15]: https://playwright.dev/docs/api/class-elementhandle#element-handle-check
 
-[16]: https://playwright.dev/docs/api/class-page#page-click
+[16]: /locators#aria-locators
 
-[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[17]: https://playwright.dev/docs/api/class-page#page-click
 
-[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[19]: https://playwright.dev/docs/api/class-page#page-drag-and-drop
+[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[20]: https://playwright.dev/docs/api/class-page#page-drag-and-drop
 
-[21]: https://playwright.dev/docs/api/class-locator#locator-focus
+[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[22]: https://playwright.dev/docs/api/class-locator#locator-aria-snapshot
+[22]: https://playwright.dev/docs/api/class-locator#locator-focus
 
-[23]: https://playwright.dev/docs/aria-snapshots
+[23]: https://playwright.dev/docs/api/class-locator#locator-aria-snapshot
 
-[24]: https://playwright.dev/docs/api/class-consolemessage
+[24]: https://playwright.dev/docs/aria-snapshots
 
-[25]: https://playwright.dev/docs/api/class-locator#locator-is-checked
+[25]: https://playwright.dev/docs/api/class-consolemessage
 
-[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[26]: https://playwright.dev/docs/api/class-locator#locator-is-checked
 
-[27]: https://playwright.dev/docs/api/class-locator#locator-is-disabled
+[27]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[28]: https://codecept.io/helpers/FileSystem
+[28]: https://playwright.dev/docs/api/class-locator#locator-is-disabled
 
-[29]: https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get
+[29]: https://codecept.io/helpers/FileSystem
 
-[30]: https://playwright.dev/docs/api/class-browsercontext#browser-context-route
+[30]: https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get
 
-[31]: https://playwright.dev/docs/network#handle-requests
+[31]: https://playwright.dev/docs/api/class-browsercontext#browser-context-route
 
-[32]: https://github.com/microsoft/playwright/blob/main/docs/api.md#browsernewpageoptions
+[32]: https://playwright.dev/docs/network#handle-requests
 
-[33]: https://github.com/puppeteer/puppeteer/issues/1313
+[33]: https://github.com/microsoft/playwright/blob/main/docs/api.md#browsernewpageoptions
 
-[34]: #fillfield
+[34]: https://github.com/puppeteer/puppeteer/issues/1313
 
-[35]: #click
+[35]: #fillfield
 
-[36]: https://playwright.dev/docs/api/class-page#page-route-from-har
+[36]: #click
 
-[37]: https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck
+[37]: https://playwright.dev/docs/api/class-page#page-route-from-har
 
-[38]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md
+[38]: https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck
 
-[39]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md
+[39]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md
 
-[40]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md
+[40]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md
 
-[41]: https://playwright.dev/docs/api/class-page#page-wait-for-navigation
+[41]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md
 
-[42]: https://playwright.dev/docs/api/class-page#page-wait-for-url
+[42]: https://playwright.dev/docs/api/class-page#page-wait-for-navigation
 
-[43]: https://codecept.io/react
+[43]: https://playwright.dev/docs/api/class-page#page-wait-for-url
 
 [44]: https://playwright.dev/docs/api/class-browsercontext