diff --git a/docs/helpers/WebDriver.md b/docs/helpers/WebDriver.md index 596d5b6d0..3dc5d60f3 100644 --- a/docs/helpers/WebDriver.md +++ b/docs/helpers/WebDriver.md @@ -23,8 +23,6 @@ One of the significant advantages of this update is that you can now get rid of For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration. If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebDriver Helper will only start a driver when there are no other connection information settings like hostname or port specified. - - ## Configuration This helper should be configured in codecept.conf.js @@ -33,29 +31,28 @@ Type: [object][17] ### Properties -* `url` **[string][18]** base url of website to be tested. -* `browser` **[string][18]** Browser in which to perform testing. -* `basicAuth` **[string][18]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} -* `host` **[string][18]?** WebDriver host to connect. -* `port` **[number][23]?** WebDriver port to connect. -* `protocol` **[string][18]?** protocol for WebDriver server. -* `path` **[string][18]?** path to WebDriver server. -* `restart` **[boolean][33]?** restart browser between tests. -* `smartWait` **([boolean][33] | [number][23])?** **enables [SmartWait][37]**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000. -* `disableScreenshots` **[boolean][33]?** don't save screenshots on failure. -* `fullPageScreenshots` **[boolean][33]?** (optional - make full page screenshots on failure. -* `uniqueScreenshotNames` **[boolean][33]?** option to prevent screenshot override if you have scenarios with the same name in different suites. -* `keepBrowserState` **[boolean][33]?** keep browser state between tests when `restart` is set to false. -* `keepCookies` **[boolean][33]?** keep cookies between tests when `restart` set to false. -* `windowSize` **[string][18]?** default window size. Set to `maximize` or a dimension in the format `640x480`. -* `waitForTimeout` **[number][23]?** sets default wait time in *ms* for all `wait*` functions. -* `desiredCapabilities` **[object][17]?** Selenium's [desired capabilities][7]. -* `manualStart` **[boolean][33]?** do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`. -* `timeouts` **[object][17]?** [WebDriver timeouts][38] defined as hash. -* `highlightElement` **[boolean][33]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). -* `logLevel` **[string][18]?** level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: [https://webdriver.io/docs/configuration/#loglevel][39] - - +- `url` **[string][18]** base url of website to be tested. +- `browser` **[string][18]** Browser in which to perform testing. +- `bidiProtocol` **[boolean][33]?** WebDriver Bidi Protocol. Default: false. More info: [https://webdriver.io/docs/api/webdriverBidi/][37] +- `basicAuth` **[string][18]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} +- `host` **[string][18]?** WebDriver host to connect. +- `port` **[number][23]?** WebDriver port to connect. +- `protocol` **[string][18]?** protocol for WebDriver server. +- `path` **[string][18]?** path to WebDriver server. +- `restart` **[boolean][33]?** restart browser between tests. +- `smartWait` **([boolean][33] | [number][23])?** **enables [SmartWait][38]**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000. +- `disableScreenshots` **[boolean][33]?** don't save screenshots on failure. +- `fullPageScreenshots` **[boolean][33]?** (optional - make full page screenshots on failure. +- `uniqueScreenshotNames` **[boolean][33]?** option to prevent screenshot override if you have scenarios with the same name in different suites. +- `keepBrowserState` **[boolean][33]?** keep browser state between tests when `restart` is set to false. +- `keepCookies` **[boolean][33]?** keep cookies between tests when `restart` set to false. +- `windowSize` **[string][18]?** default window size. Set to `maximize` or a dimension in the format `640x480`. +- `waitForTimeout` **[number][23]?** sets default wait time in _ms_ for all `wait*` functions. +- `desiredCapabilities` **[object][17]?** Selenium's [desired capabilities][7]. +- `manualStart` **[boolean][33]?** do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`. +- `timeouts` **[object][17]?** [WebDriver timeouts][39] defined as hash. +- `highlightElement` **[boolean][33]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). +- `logLevel` **[string][18]?** level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: [https://webdriver.io/docs/configuration/#loglevel][40] Example: @@ -396,7 +393,7 @@ Here is the [webdriverio docs][16] on the subject Receive a WebDriver client from a custom helper by accessing `browser` property: ```js -const { WebDriver } = this.helpers; +const { WebDriver } = this.helpers const browser = WebDriver.browser ``` @@ -404,31 +401,31 @@ const browser = WebDriver.browser ### Parameters -* `config` +- `config` -### _isShadowLocator +### \_isShadowLocator Check if locator is type of "Shadow" #### Parameters -* `locator` **[object][17]** +- `locator` **[object][17]** -### _locate +### \_locate Get elements by different locator types, including strict locator. Should be used in custom helpers: ```js -this.helpers['WebDriver']._locate({name: 'password'}).then //... +this.helpers['WebDriver']._locate({ name: 'password' }).then //... ``` #### Parameters -* `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. -* `smartWait` +- `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. +- `smartWait` -### _locateCheckable +### \_locateCheckable Find a checkbox by providing human-readable text: @@ -438,23 +435,23 @@ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions'). #### Parameters -* `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. +- `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. -### _locateClickable +### \_locateClickable Find a clickable element by providing human-readable text: ```js -const els = await this.helpers.WebDriver._locateClickable('Next page'); -const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages'); +const els = await this.helpers.WebDriver._locateClickable('Next page') +const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages') ``` #### Parameters -* `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. -* `context` +- `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. +- `context` -### _locateFields +### \_locateFields Find field elements by providing human-readable text: @@ -464,23 +461,23 @@ this.helpers['WebDriver']._locateFields('Your email').then // ... #### Parameters -* `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. +- `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator. -### _locateShadow +### \_locateShadow Locate Element within the Shadow Dom #### Parameters -* `locator` **[object][17]** +- `locator` **[object][17]** -### _smartWait +### \_smartWait Smart Wait to locate an element #### Parameters -* `locator` **[object][17]** +- `locator` **[object][17]** ### acceptPopup @@ -494,14 +491,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][18]** url path or global url. +- `url` **[string][18]** url path or global url. Returns **void** automatically synchronized promise through #recorder @@ -511,22 +508,20 @@ 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][18] | [object][17])** located by label|name|CSS|XPath|strict locator -* `value` **[string][18]** text value to append. +- `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator +- `value` **[string][18]** text value to append. Returns **void** automatically synchronized promise through #recorder - This action supports [React locators](https://codecept.io/react#locators) - ### attachFile Appium: not tested @@ -536,14 +531,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][18] | [object][17])** field located by label|name|CSS|XPath|strict locator. -* `pathToFile` **[string][18]** local file path relative to codecept.conf.ts or codecept.conf.js config file. +- `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator. +- `pathToFile` **[string][18]** local file path relative to codecept.conf.ts or codecept.conf.js config file. Returns **void** automatically synchronized promise through #recorder @@ -560,15 +555,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][18] | [object][17])** field located by label|name|CSS|XPath|strict locator. -* `options` **any?** Playwright only: [Additional options][21] for available options object as 2nd argument. +- `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator. +- `options` **any?** Playwright only: [Additional options][21] for available options object as 2nd argument. Returns **void** automatically synchronized promise through #recorder @@ -585,15 +580,15 @@ 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][18] | [object][17])** checkbox located by label | name | CSS | XPath | strict locator. -* `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator. +- `field` **([string][18] | [object][17])** checkbox located by label | name | CSS | XPath | strict locator. +- `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator. Returns **void** automatically synchronized promise through #recorder @@ -603,28 +598,28 @@ Clears a cookie by name, if none provided clears all cookies. ```js -I.clearCookie(); -I.clearCookie('test'); +I.clearCookie() +I.clearCookie('test') ``` #### Parameters -* `cookie` **[string][18]?** (optional, `null` by default) cookie name +- `cookie` **[string][18]?** (optional, `null` by default) cookie name ### clearField Clears a `