codeceptjs 4.0.2-beta.9 → 4.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (326) hide show
  1. package/README.md +39 -28
  2. package/bin/codecept.js +15 -2
  3. package/bin/codeceptq.js +49 -0
  4. package/bin/mcp-server.js +1189 -0
  5. package/docs/advanced.md +201 -0
  6. package/docs/agents.md +181 -0
  7. package/docs/ai.md +489 -0
  8. package/docs/aitrace.md +266 -0
  9. package/docs/api.md +332 -0
  10. package/docs/architecture.md +235 -0
  11. package/docs/assertions.md +415 -0
  12. package/docs/auth.md +318 -0
  13. package/docs/basics.md +424 -0
  14. package/docs/bdd.md +539 -0
  15. package/docs/best.md +240 -0
  16. package/docs/bootstrap.md +132 -0
  17. package/docs/commands.md +352 -0
  18. package/docs/community-helpers.md +63 -0
  19. package/docs/configuration.md +185 -0
  20. package/docs/continuous-integration.md +431 -0
  21. package/docs/custom-helpers.md +297 -0
  22. package/docs/data.md +448 -0
  23. package/docs/debugging.md +332 -0
  24. package/docs/detox.md +235 -0
  25. package/docs/docker.md +107 -0
  26. package/docs/effects.md +179 -0
  27. package/docs/element-based-testing.md +295 -0
  28. package/docs/element-selection.md +125 -0
  29. package/docs/els.md +328 -0
  30. package/docs/environment-variables.md +131 -0
  31. package/docs/examples.md +160 -0
  32. package/docs/heal.md +213 -0
  33. package/docs/helpers/ApiDataFactory.md +267 -0
  34. package/docs/helpers/Appium.md +1419 -0
  35. package/docs/helpers/Detox.md +665 -0
  36. package/docs/helpers/ExpectHelper.md +275 -0
  37. package/docs/helpers/FileSystem.md +152 -0
  38. package/docs/helpers/GraphQL.md +152 -0
  39. package/docs/helpers/GraphQLDataFactory.md +226 -0
  40. package/docs/helpers/JSONResponse.md +255 -0
  41. package/docs/helpers/MockRequest.md +377 -0
  42. package/docs/helpers/Playwright.md +2970 -0
  43. package/docs/helpers/Puppeteer-firefox.md +86 -0
  44. package/docs/helpers/Puppeteer.md +2583 -0
  45. package/docs/helpers/REST.md +289 -0
  46. package/docs/helpers/WebDriver.md +2639 -0
  47. package/docs/hooks.md +148 -0
  48. package/docs/index.md +111 -0
  49. package/docs/installation.md +121 -0
  50. package/docs/internal-test-server.md +89 -0
  51. package/docs/locators.md +355 -0
  52. package/docs/mcp.md +485 -0
  53. package/docs/migrate-from-cypress.md +98 -0
  54. package/docs/migrate-from-java.md +108 -0
  55. package/docs/migrate-from-protractor.md +101 -0
  56. package/docs/migrate-from-testcafe.md +99 -0
  57. package/docs/migration-4.md +745 -0
  58. package/docs/mobile.md +338 -0
  59. package/docs/pageobjects.md +399 -0
  60. package/docs/parallel.md +187 -0
  61. package/docs/playwright.md +714 -0
  62. package/docs/plugins/aiTrace.md +49 -0
  63. package/docs/plugins/analyze.md +66 -0
  64. package/docs/plugins/auth.md +241 -0
  65. package/docs/plugins/autoDelay.md +48 -0
  66. package/docs/plugins/browser.md +41 -0
  67. package/docs/plugins/coverage.md +39 -0
  68. package/docs/plugins/customLocator.md +119 -0
  69. package/docs/plugins/customReporter.md +16 -0
  70. package/docs/plugins/expose.md +75 -0
  71. package/docs/plugins/heal.md +44 -0
  72. package/docs/plugins/junitReporter.md +51 -0
  73. package/docs/plugins/pageInfo.md +34 -0
  74. package/docs/plugins/pause.md +43 -0
  75. package/docs/plugins/pauseOnFail.md +18 -0
  76. package/docs/plugins/retryFailedStep.md +75 -0
  77. package/docs/plugins/screencast.md +55 -0
  78. package/docs/plugins/screenshot.md +58 -0
  79. package/docs/plugins/screenshotOnFail.md +18 -0
  80. package/docs/plugins/stepTimeout.md +65 -0
  81. package/docs/plugins.md +87 -0
  82. package/docs/puppeteer.md +314 -0
  83. package/docs/quickstart.md +120 -0
  84. package/docs/reports.md +195 -0
  85. package/docs/retry.md +311 -0
  86. package/docs/secrets.md +150 -0
  87. package/docs/sessions.md +80 -0
  88. package/docs/shadow.md +68 -0
  89. package/docs/store.md +94 -0
  90. package/docs/test-structure.md +275 -0
  91. package/docs/timeouts.md +183 -0
  92. package/docs/translation.md +247 -0
  93. package/docs/tutorial.md +323 -0
  94. package/docs/typescript.md +159 -0
  95. package/docs/web-element.md +251 -0
  96. package/docs/webdriver.md +641 -0
  97. package/docs/within.md +55 -0
  98. package/lib/actor.js +1 -36
  99. package/lib/ai.js +3 -2
  100. package/lib/aria.js +260 -0
  101. package/lib/assertions.js +18 -0
  102. package/lib/codecept.js +34 -25
  103. package/lib/command/check.js +2 -1
  104. package/lib/command/definitions.js +6 -7
  105. package/lib/command/dryRun.js +24 -5
  106. package/lib/command/generate.js +3 -1
  107. package/lib/command/gherkin/snippets.js +5 -4
  108. package/lib/command/init.js +249 -270
  109. package/lib/command/list.js +150 -10
  110. package/lib/command/query.js +218 -0
  111. package/lib/command/run-multiple.js +3 -1
  112. package/lib/command/run-workers.js +2 -14
  113. package/lib/command/run.js +3 -17
  114. package/lib/command/utils.js +14 -0
  115. package/lib/command/workers/runTests.js +84 -41
  116. package/lib/config.js +96 -18
  117. package/lib/container.js +115 -17
  118. package/lib/effects.js +17 -0
  119. package/lib/element/WebElement.js +246 -2
  120. package/lib/els.js +12 -6
  121. package/lib/globals.js +32 -19
  122. package/lib/heal.js +7 -4
  123. package/lib/helper/ApiDataFactory.js +2 -1
  124. package/lib/helper/Appium.js +8 -8
  125. package/lib/helper/FileSystem.js +3 -2
  126. package/lib/helper/GraphQLDataFactory.js +2 -1
  127. package/lib/helper/Playwright.js +358 -467
  128. package/lib/helper/Puppeteer.js +335 -192
  129. package/lib/helper/WebDriver.js +324 -111
  130. package/lib/helper/errors/ElementNotFound.js +5 -2
  131. package/lib/helper/errors/MultipleElementsFound.js +52 -0
  132. package/lib/helper/errors/NonFocusedType.js +8 -0
  133. package/lib/helper/extras/Download.js +45 -0
  134. package/lib/helper/extras/PlaywrightLocator.js +7 -107
  135. package/lib/helper/extras/elementSelection.js +58 -0
  136. package/lib/helper/extras/focusCheck.js +43 -0
  137. package/lib/helper/extras/richTextEditor.js +178 -0
  138. package/lib/helper/scripts/dropFile.js +11 -0
  139. package/lib/history.js +3 -2
  140. package/lib/html.js +103 -16
  141. package/lib/index.js +9 -1
  142. package/lib/listener/config.js +6 -4
  143. package/lib/listener/emptyRun.js +2 -1
  144. package/lib/listener/globalRetry.js +32 -6
  145. package/lib/listener/helpers.js +4 -1
  146. package/lib/listener/mocha.js +2 -1
  147. package/lib/listener/pageobjects.js +43 -0
  148. package/lib/listener/result.js +3 -2
  149. package/lib/locator.js +158 -16
  150. package/lib/mocha/cli.js +19 -1
  151. package/lib/mocha/factory.js +11 -1
  152. package/lib/mocha/inject.js +1 -1
  153. package/lib/mocha/scenarioConfig.js +2 -1
  154. package/lib/mocha/ui.js +5 -6
  155. package/lib/parser.js +2 -2
  156. package/lib/pause.js +38 -4
  157. package/lib/plugin/aiTrace.js +457 -0
  158. package/lib/plugin/analyze.js +9 -9
  159. package/lib/plugin/auth.js +5 -4
  160. package/lib/plugin/browser.js +77 -0
  161. package/lib/plugin/expose.js +159 -0
  162. package/lib/plugin/heal.js +47 -3
  163. package/lib/plugin/junitReporter.js +303 -0
  164. package/lib/plugin/pageInfo.js +54 -52
  165. package/lib/plugin/pause.js +131 -0
  166. package/lib/plugin/pauseOnFail.js +11 -33
  167. package/lib/plugin/retryFailedStep.js +43 -32
  168. package/lib/plugin/screencast.js +289 -0
  169. package/lib/plugin/screenshot.js +558 -0
  170. package/lib/plugin/screenshotOnFail.js +9 -170
  171. package/lib/plugin/stepTimeout.js +3 -2
  172. package/lib/recorder.js +1 -1
  173. package/lib/rerun.js +2 -1
  174. package/lib/result.js +2 -1
  175. package/lib/step/base.js +10 -9
  176. package/lib/step/comment.js +2 -2
  177. package/lib/step/config.js +15 -2
  178. package/lib/step/helper.js +4 -4
  179. package/lib/step/meta.js +3 -3
  180. package/lib/step/record.js +5 -5
  181. package/lib/store.js +72 -3
  182. package/lib/translation.js +2 -1
  183. package/lib/utils/loaderCheck.js +28 -0
  184. package/lib/utils/mask_data.js +2 -1
  185. package/lib/utils/pluginParser.js +151 -0
  186. package/lib/utils/trace.js +297 -0
  187. package/lib/utils/typescript.js +188 -23
  188. package/lib/utils.js +77 -3
  189. package/lib/workers.js +65 -40
  190. package/package.json +35 -30
  191. package/typings/index.d.ts +119 -8
  192. package/typings/promiseBasedTypes.d.ts +3158 -6065
  193. package/typings/types.d.ts +3453 -6494
  194. package/docs/webapi/amOnPage.mustache +0 -11
  195. package/docs/webapi/appendField.mustache +0 -11
  196. package/docs/webapi/attachFile.mustache +0 -12
  197. package/docs/webapi/blur.mustache +0 -18
  198. package/docs/webapi/checkOption.mustache +0 -13
  199. package/docs/webapi/clearCookie.mustache +0 -9
  200. package/docs/webapi/clearField.mustache +0 -9
  201. package/docs/webapi/click.mustache +0 -29
  202. package/docs/webapi/clickLink.mustache +0 -8
  203. package/docs/webapi/closeCurrentTab.mustache +0 -7
  204. package/docs/webapi/closeOtherTabs.mustache +0 -8
  205. package/docs/webapi/dontSee.mustache +0 -11
  206. package/docs/webapi/dontSeeCheckboxIsChecked.mustache +0 -10
  207. package/docs/webapi/dontSeeCookie.mustache +0 -8
  208. package/docs/webapi/dontSeeCurrentUrlEquals.mustache +0 -10
  209. package/docs/webapi/dontSeeElement.mustache +0 -8
  210. package/docs/webapi/dontSeeElementInDOM.mustache +0 -8
  211. package/docs/webapi/dontSeeInCurrentUrl.mustache +0 -4
  212. package/docs/webapi/dontSeeInField.mustache +0 -11
  213. package/docs/webapi/dontSeeInSource.mustache +0 -8
  214. package/docs/webapi/dontSeeInTitle.mustache +0 -8
  215. package/docs/webapi/dontSeeTraffic.mustache +0 -13
  216. package/docs/webapi/doubleClick.mustache +0 -13
  217. package/docs/webapi/downloadFile.mustache +0 -12
  218. package/docs/webapi/dragAndDrop.mustache +0 -9
  219. package/docs/webapi/dragSlider.mustache +0 -11
  220. package/docs/webapi/executeAsyncScript.mustache +0 -24
  221. package/docs/webapi/executeScript.mustache +0 -26
  222. package/docs/webapi/fillField.mustache +0 -16
  223. package/docs/webapi/flushNetworkTraffics.mustache +0 -5
  224. package/docs/webapi/focus.mustache +0 -13
  225. package/docs/webapi/forceClick.mustache +0 -28
  226. package/docs/webapi/forceRightClick.mustache +0 -18
  227. package/docs/webapi/grabAllWindowHandles.mustache +0 -7
  228. package/docs/webapi/grabAttributeFrom.mustache +0 -10
  229. package/docs/webapi/grabAttributeFromAll.mustache +0 -9
  230. package/docs/webapi/grabBrowserLogs.mustache +0 -9
  231. package/docs/webapi/grabCookie.mustache +0 -11
  232. package/docs/webapi/grabCssPropertyFrom.mustache +0 -11
  233. package/docs/webapi/grabCssPropertyFromAll.mustache +0 -10
  234. package/docs/webapi/grabCurrentUrl.mustache +0 -9
  235. package/docs/webapi/grabCurrentWindowHandle.mustache +0 -6
  236. package/docs/webapi/grabDataFromPerformanceTiming.mustache +0 -20
  237. package/docs/webapi/grabElementBoundingRect.mustache +0 -20
  238. package/docs/webapi/grabGeoLocation.mustache +0 -8
  239. package/docs/webapi/grabHTMLFrom.mustache +0 -10
  240. package/docs/webapi/grabHTMLFromAll.mustache +0 -9
  241. package/docs/webapi/grabNumberOfOpenTabs.mustache +0 -8
  242. package/docs/webapi/grabNumberOfVisibleElements.mustache +0 -9
  243. package/docs/webapi/grabPageScrollPosition.mustache +0 -8
  244. package/docs/webapi/grabPopupText.mustache +0 -5
  245. package/docs/webapi/grabRecordedNetworkTraffics.mustache +0 -10
  246. package/docs/webapi/grabSource.mustache +0 -8
  247. package/docs/webapi/grabTextFrom.mustache +0 -10
  248. package/docs/webapi/grabTextFromAll.mustache +0 -9
  249. package/docs/webapi/grabTitle.mustache +0 -8
  250. package/docs/webapi/grabValueFrom.mustache +0 -9
  251. package/docs/webapi/grabValueFromAll.mustache +0 -8
  252. package/docs/webapi/grabWebElement.mustache +0 -9
  253. package/docs/webapi/grabWebElements.mustache +0 -9
  254. package/docs/webapi/moveCursorTo.mustache +0 -12
  255. package/docs/webapi/openNewTab.mustache +0 -7
  256. package/docs/webapi/pressKey.mustache +0 -12
  257. package/docs/webapi/pressKeyDown.mustache +0 -12
  258. package/docs/webapi/pressKeyUp.mustache +0 -12
  259. package/docs/webapi/pressKeyWithKeyNormalization.mustache +0 -60
  260. package/docs/webapi/refreshPage.mustache +0 -6
  261. package/docs/webapi/resizeWindow.mustache +0 -6
  262. package/docs/webapi/rightClick.mustache +0 -14
  263. package/docs/webapi/saveElementScreenshot.mustache +0 -10
  264. package/docs/webapi/saveScreenshot.mustache +0 -12
  265. package/docs/webapi/say.mustache +0 -10
  266. package/docs/webapi/scrollIntoView.mustache +0 -11
  267. package/docs/webapi/scrollPageToBottom.mustache +0 -6
  268. package/docs/webapi/scrollPageToTop.mustache +0 -6
  269. package/docs/webapi/scrollTo.mustache +0 -12
  270. package/docs/webapi/see.mustache +0 -11
  271. package/docs/webapi/seeAttributesOnElements.mustache +0 -9
  272. package/docs/webapi/seeCheckboxIsChecked.mustache +0 -10
  273. package/docs/webapi/seeCookie.mustache +0 -8
  274. package/docs/webapi/seeCssPropertiesOnElements.mustache +0 -9
  275. package/docs/webapi/seeCurrentUrlEquals.mustache +0 -11
  276. package/docs/webapi/seeElement.mustache +0 -8
  277. package/docs/webapi/seeElementInDOM.mustache +0 -8
  278. package/docs/webapi/seeInCurrentUrl.mustache +0 -8
  279. package/docs/webapi/seeInField.mustache +0 -12
  280. package/docs/webapi/seeInPopup.mustache +0 -8
  281. package/docs/webapi/seeInSource.mustache +0 -7
  282. package/docs/webapi/seeInTitle.mustache +0 -8
  283. package/docs/webapi/seeNumberOfElements.mustache +0 -11
  284. package/docs/webapi/seeNumberOfVisibleElements.mustache +0 -10
  285. package/docs/webapi/seeTextEquals.mustache +0 -9
  286. package/docs/webapi/seeTitleEquals.mustache +0 -8
  287. package/docs/webapi/seeTraffic.mustache +0 -36
  288. package/docs/webapi/selectOption.mustache +0 -21
  289. package/docs/webapi/setCookie.mustache +0 -16
  290. package/docs/webapi/setGeoLocation.mustache +0 -12
  291. package/docs/webapi/startRecordingTraffic.mustache +0 -8
  292. package/docs/webapi/startRecordingWebSocketMessages.mustache +0 -8
  293. package/docs/webapi/stopRecordingTraffic.mustache +0 -5
  294. package/docs/webapi/stopRecordingWebSocketMessages.mustache +0 -7
  295. package/docs/webapi/switchTo.mustache +0 -9
  296. package/docs/webapi/switchToNextTab.mustache +0 -10
  297. package/docs/webapi/switchToPreviousTab.mustache +0 -10
  298. package/docs/webapi/type.mustache +0 -21
  299. package/docs/webapi/uncheckOption.mustache +0 -13
  300. package/docs/webapi/wait.mustache +0 -8
  301. package/docs/webapi/waitForClickable.mustache +0 -11
  302. package/docs/webapi/waitForCookie.mustache +0 -9
  303. package/docs/webapi/waitForDetached.mustache +0 -10
  304. package/docs/webapi/waitForDisabled.mustache +0 -6
  305. package/docs/webapi/waitForElement.mustache +0 -11
  306. package/docs/webapi/waitForEnabled.mustache +0 -6
  307. package/docs/webapi/waitForFunction.mustache +0 -17
  308. package/docs/webapi/waitForInvisible.mustache +0 -10
  309. package/docs/webapi/waitForNumberOfTabs.mustache +0 -9
  310. package/docs/webapi/waitForText.mustache +0 -13
  311. package/docs/webapi/waitForValue.mustache +0 -10
  312. package/docs/webapi/waitForVisible.mustache +0 -10
  313. package/docs/webapi/waitInUrl.mustache +0 -9
  314. package/docs/webapi/waitNumberOfVisibleElements.mustache +0 -10
  315. package/docs/webapi/waitToHide.mustache +0 -10
  316. package/docs/webapi/waitUrlEquals.mustache +0 -10
  317. package/lib/helper/AI.js +0 -214
  318. package/lib/helper/Mochawesome.js +0 -96
  319. package/lib/helper/extras/PlaywrightReactVueLocator.js +0 -52
  320. package/lib/helper/extras/React.js +0 -65
  321. package/lib/listener/enhancedGlobalRetry.js +0 -110
  322. package/lib/plugin/enhancedRetryFailedStep.js +0 -99
  323. package/lib/plugin/htmlReporter.js +0 -3648
  324. package/lib/plugin/stepByStepReport.js +0 -427
  325. package/lib/plugin/subtitles.js +0 -89
  326. package/lib/retryCoordinator.js +0 -207
@@ -0,0 +1,2639 @@
1
+ ---
2
+ permalink: /helpers/WebDriver
3
+ editLink: false
4
+ sidebar: auto
5
+ title: WebDriver
6
+ ---
7
+
8
+ <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
9
+
10
+ ## WebDriver
11
+
12
+ **Extends Helper**
13
+
14
+ WebDriver helper which wraps [webdriverio][1] library to
15
+ manipulate browser using Selenium WebDriver or PhantomJS.
16
+
17
+ No Selenium Server, ChromeDriver, or GeckoDriver to install or start. Since WebdriverIO 9, driver management is fully automatic — WebdriverIO downloads and starts the matching driver for you. Read more [here][2]. Please check [Testing with WebDriver][3] for more details.
18
+
19
+ For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration.
20
+ 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.
21
+
22
+
23
+
24
+ ## Configuration
25
+
26
+ This helper should be configured in codecept.conf.js
27
+
28
+ Type: [object][17]
29
+
30
+ ### Properties
31
+
32
+ * `url` **[string][18]** base url of website to be tested.
33
+ * `browser` **[string][18]** Browser in which to perform testing.
34
+ * `bidiProtocol` **[boolean][34]?** WebDriver Bidi Protocol. Default: false. More info: [https://webdriver.io/docs/api/webdriverBidi/][38]
35
+ * `basicAuth` **[string][18]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
36
+ * `host` **[string][18]?** WebDriver host to connect.
37
+ * `port` **[number][23]?** WebDriver port to connect.
38
+ * `protocol` **[string][18]?** protocol for WebDriver server.
39
+ * `path` **[string][18]?** path to WebDriver server.
40
+ * `restart` **[boolean][34]?** restart browser between tests.
41
+ * `smartWait` **([boolean][34] | [number][23])?** **enables [SmartWait][39]**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000.
42
+ * `disableScreenshots` **[boolean][34]?** don't save screenshots on failure.
43
+ * `fullPageScreenshots` **[boolean][34]?** (optional - make full page screenshots on failure.
44
+ * `uniqueScreenshotNames` **[boolean][34]?** option to prevent screenshot override if you have scenarios with the same name in different suites.
45
+ * `keepBrowserState` **[boolean][34]?** keep browser state between tests when `restart` is set to false.
46
+ * `keepCookies` **[boolean][34]?** keep cookies between tests when `restart` set to false.
47
+ * `windowSize` **[string][18]?** default window size. Set to `maximize` or a dimension in the format `640x480`.
48
+ * `waitForTimeout` **[number][23]?** sets default wait time in *ms* for all `wait*` functions.
49
+ * `desiredCapabilities` **[object][17]?** Selenium's [desired capabilities][7].
50
+ * `manualStart` **[boolean][34]?** do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
51
+ * `timeouts` **[object][17]?** [WebDriver timeouts][40] defined as hash.
52
+ * `highlightElement` **[boolean][34]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
53
+ * `logLevel` **[string][18]?** level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: [https://webdriver.io/docs/configuration/#loglevel][41]
54
+
55
+ ## wrapError
56
+
57
+ Wraps error objects that don't have a proper message property
58
+ This is needed for ESM compatibility with WebdriverIO error handling
59
+
60
+ ### Parameters
61
+
62
+ * `e` &#x20;
63
+
64
+
65
+
66
+ Example:
67
+
68
+ ```js
69
+ {
70
+ helpers: {
71
+ WebDriver : {
72
+ smartWait: 5000,
73
+ browser: "chrome",
74
+ restart: false,
75
+ windowSize: "maximize",
76
+ timeouts: {
77
+ "script": 60000,
78
+ "page load": 10000
79
+ }
80
+ }
81
+ }
82
+ }
83
+ ```
84
+
85
+ Testing Chrome locally is now more convenient than ever. You can define a browser channel, and WebDriver Helper will take care of downloading the specified browser version for you.
86
+ For example:
87
+
88
+ ```js
89
+ {
90
+ helpers: {
91
+ WebDriver : {
92
+ smartWait: 5000,
93
+ browser: "chrome",
94
+ browserVersion: '116.0.5793.0', // or 'stable', 'beta', 'dev' or 'canary'
95
+ restart: false,
96
+ windowSize: "maximize",
97
+ timeouts: {
98
+ "script": 60000,
99
+ "page load": 10000
100
+ }
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ Example with basic authentication
107
+
108
+ ```js
109
+ {
110
+ helpers: {
111
+ WebDriver : {
112
+ smartWait: 5000,
113
+ browser: "chrome",
114
+ basicAuth: {username: 'username', password: 'password'},
115
+ restart: false,
116
+ windowSize: "maximize",
117
+ timeouts: {
118
+ "script": 60000,
119
+ "page load": 10000
120
+ }
121
+ }
122
+ }
123
+ }
124
+ ```
125
+
126
+ Additional configuration params can be used from [webdriverio
127
+ website][4].
128
+
129
+ ### Headless Chrome
130
+
131
+ ```js
132
+ {
133
+ helpers: {
134
+ WebDriver : {
135
+ url: "http://localhost",
136
+ browser: "chrome",
137
+ desiredCapabilities: {
138
+ chromeOptions: {
139
+ args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
140
+ }
141
+ }
142
+ }
143
+ }
144
+ }
145
+ ```
146
+
147
+ ### Running with devtools protocol
148
+
149
+ ```js
150
+ {
151
+ helpers: {
152
+ WebDriver : {
153
+ url: "http://localhost",
154
+ browser: "chrome",
155
+ desiredCapabilities: {
156
+ chromeOptions: {
157
+ args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
158
+ }
159
+ }
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ ### Internet Explorer
166
+
167
+ Additional configuration params can be used from [IE options][5]
168
+
169
+ ```js
170
+ {
171
+ helpers: {
172
+ WebDriver : {
173
+ url: "http://localhost",
174
+ browser: "internet explorer",
175
+ desiredCapabilities: {
176
+ ieOptions: {
177
+ "ie.browserCommandLineSwitches": "-private",
178
+ "ie.usePerProcessProxy": true,
179
+ "ie.ensureCleanSession": true,
180
+ }
181
+ }
182
+ }
183
+ }
184
+ }
185
+ ```
186
+
187
+ ### Selenoid Options
188
+
189
+ [Selenoid][6] is a modern way to run Selenium inside Docker containers.
190
+ Selenoid is easy to set up and provides more features than original Selenium Server. Use `selenoidOptions` to set Selenoid capabilities
191
+
192
+ ```js
193
+ {
194
+ helpers: {
195
+ WebDriver : {
196
+ url: "http://localhost",
197
+ browser: "chrome",
198
+ desiredCapabilities: {
199
+ selenoidOptions: {
200
+ enableVNC: true,
201
+ }
202
+ }
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ ### Connect Through proxy
209
+
210
+ CodeceptJS also provides flexible options when you want to execute tests to Selenium servers through proxy. You will
211
+ need to update the `helpers.WebDriver.capabilities.proxy` key.
212
+
213
+ ```js
214
+ {
215
+ helpers: {
216
+ WebDriver: {
217
+ capabilities: {
218
+ proxy: {
219
+ "proxyType": "manual|pac",
220
+ "proxyAutoconfigUrl": "URL TO PAC FILE",
221
+ "httpProxy": "PROXY SERVER",
222
+ "sslProxy": "PROXY SERVER",
223
+ "ftpProxy": "PROXY SERVER",
224
+ "socksProxy": "PROXY SERVER",
225
+ "socksUsername": "USERNAME",
226
+ "socksPassword": "PASSWORD",
227
+ "noProxy": "BYPASS ADDRESSES"
228
+ }
229
+ }
230
+ }
231
+ }
232
+ }
233
+ ```
234
+
235
+ For example,
236
+
237
+ ```js
238
+ {
239
+ helpers: {
240
+ WebDriver: {
241
+ capabilities: {
242
+ proxy: {
243
+ "proxyType": "manual",
244
+ "httpProxy": "http://corporate.proxy:8080",
245
+ "socksUsername": "codeceptjs",
246
+ "socksPassword": "secret",
247
+ "noProxy": "127.0.0.1,localhost"
248
+ }
249
+ }
250
+ }
251
+ }
252
+ }
253
+ ```
254
+
255
+ Please refer to [Selenium - Proxy Object][7] for more
256
+ information.
257
+
258
+ ### Cloud Providers
259
+
260
+ WebDriver makes it possible to execute tests against services like `Sauce Labs` `BrowserStack` `TestingBot`
261
+ Check out their documentation on [available parameters][8]
262
+
263
+ Connecting to `BrowserStack` and `Sauce Labs` is simple. All you need to do
264
+ is set the `user` and `key` parameters. WebDriver automatically know which
265
+ service provider to connect to.
266
+
267
+ ```js
268
+ {
269
+ helpers:{
270
+ WebDriver: {
271
+ url: "YOUR_DESIRED_HOST",
272
+ user: "YOUR_BROWSERSTACK_USER",
273
+ key: "YOUR_BROWSERSTACK_KEY",
274
+ capabilities: {
275
+ "browserName": "chrome",
276
+
277
+ // only set this if you're using BrowserStackLocal to test a local domain
278
+ // "browserstack.local": true,
279
+
280
+ // set this option to tell browserstack to provide addition debugging info
281
+ // "browserstack.debug": true,
282
+ }
283
+ }
284
+ }
285
+ }
286
+ ```
287
+
288
+ #### SauceLabs
289
+
290
+ SauceLabs can be configured via wdio service, which should be installed additionally:
291
+
292
+ npm i @wdio/sauce-service --save
293
+
294
+ It is important to make sure it is compatible with current webdriverio version.
295
+
296
+ Enable `wdio` plugin in plugins list and add `sauce` service:
297
+
298
+ ```js
299
+ plugins: {
300
+ wdio: {
301
+ enabled: true,
302
+ services: ['sauce'],
303
+ user: ... ,// saucelabs username
304
+ key: ... // saucelabs api key
305
+ // additional config, from sauce service
306
+ }
307
+ }
308
+ ```
309
+
310
+ See [complete reference on webdriver.io][9].
311
+
312
+ > Alternatively, use [codeceptjs-saucehelper][10] for better reporting.
313
+
314
+ #### BrowserStack
315
+
316
+ BrowserStack can be configured via wdio service, which should be installed additionally:
317
+
318
+ npm i @wdio/browserstack-service --save
319
+
320
+ It is important to make sure it is compatible with current webdriverio version.
321
+
322
+ Enable `wdio` plugin in plugins list and add `browserstack` service:
323
+
324
+ ```js
325
+ plugins: {
326
+ wdio: {
327
+ enabled: true,
328
+ services: ['browserstack'],
329
+ user: ... ,// browserstack username
330
+ key: ... // browserstack api key
331
+ // additional config, from browserstack service
332
+ }
333
+ }
334
+ ```
335
+
336
+ See [complete reference on webdriver.io][11].
337
+
338
+ > Alternatively, use [codeceptjs-bshelper][12] for better reporting.
339
+
340
+ #### TestingBot
341
+
342
+ > **Recommended**: use official [TestingBot Helper][13].
343
+
344
+ Alternatively, TestingBot can be configured via wdio service, which should be installed additionally:
345
+
346
+ npm i @wdio/testingbot-service --save
347
+
348
+ It is important to make sure it is compatible with current webdriverio version.
349
+
350
+ Enable `wdio` plugin in plugins list and add `testingbot` service:
351
+
352
+ ```js
353
+ plugins: {
354
+ wdio: {
355
+ enabled: true,
356
+ services: ['testingbot'],
357
+ user: ... ,// testingbot key
358
+ key: ... // testingbot secret
359
+ // additional config, from testingbot service
360
+ }
361
+ }
362
+ ```
363
+
364
+ See [complete reference on webdriver.io][14].
365
+
366
+ #### Applitools
367
+
368
+ Visual testing via Applitools service
369
+
370
+ > Use [CodeceptJS Applitools Helper][15] with Applitools wdio service.
371
+
372
+ ### Multiremote Capabilities
373
+
374
+ This is a work in progress but you can control two browsers at a time right out of the box.
375
+ Individual control is something that is planned for a later version.
376
+
377
+ Here is the [webdriverio docs][16] on the subject
378
+
379
+ ```js
380
+ {
381
+ helpers: {
382
+ WebDriver: {
383
+ "multiremote": {
384
+ "MyChrome": {
385
+ "desiredCapabilities": {
386
+ "browserName": "chrome"
387
+ }
388
+ },
389
+ "MyFirefox": {
390
+ "desiredCapabilities": {
391
+ "browserName": "firefox"
392
+ }
393
+ }
394
+ }
395
+ }
396
+ }
397
+ }
398
+ ```
399
+
400
+ ## Access From Helpers
401
+
402
+ Receive a WebDriver client from a custom helper by accessing `browser` property:
403
+
404
+ ```js
405
+ const { WebDriver } = this.helpers;
406
+ const browser = WebDriver.browser
407
+ ```
408
+
409
+ ## Methods
410
+
411
+ ### Parameters
412
+
413
+ * `config` &#x20;
414
+
415
+ ### _isShadowLocator
416
+
417
+ Check if locator is type of "Shadow"
418
+
419
+ #### Parameters
420
+
421
+ * `locator` **[object][17]**&#x20;
422
+
423
+ ### _locate
424
+
425
+ Get elements by different locator types, including strict locator.
426
+ Should be used in custom helpers:
427
+
428
+ ```js
429
+ this.helpers['WebDriver']._locate({name: 'password'}).then //...
430
+ ```
431
+
432
+ #### Parameters
433
+
434
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
435
+ * `smartWait`
436
+
437
+ ### _locateByRole
438
+
439
+ Locate elements by ARIA role using WebdriverIO accessibility selectors
440
+
441
+ #### Parameters
442
+
443
+ * `locator` **[object][17]** role locator object { role: string, text?: string, exact?: boolean }
444
+
445
+ ### _locateCheckable
446
+
447
+ Find a checkbox by providing human-readable text:
448
+
449
+ ```js
450
+ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').then // ...
451
+ ```
452
+
453
+ #### Parameters
454
+
455
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
456
+
457
+ ### _locateClickable
458
+
459
+ Find a clickable element by providing human-readable text:
460
+
461
+ ```js
462
+ const els = await this.helpers.WebDriver._locateClickable('Next page');
463
+ const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages');
464
+ ```
465
+
466
+ #### Parameters
467
+
468
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
469
+ * `context` &#x20;
470
+
471
+ ### _locateFields
472
+
473
+ Find field elements by providing human-readable text:
474
+
475
+ ```js
476
+ this.helpers['WebDriver']._locateFields('Your email').then // ...
477
+ ```
478
+
479
+ #### Parameters
480
+
481
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
482
+
483
+ ### _locateShadow
484
+
485
+ Locate Element within the Shadow Dom
486
+
487
+ #### Parameters
488
+
489
+ * `locator` **[object][17]**&#x20;
490
+
491
+ ### _smartWait
492
+
493
+ Smart Wait to locate an element
494
+
495
+ #### Parameters
496
+
497
+ * `locator` **[object][17]**&#x20;
498
+
499
+ ### acceptPopup
500
+
501
+ Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt.
502
+ Don't confuse popups with modal windows, as created by [various
503
+ libraries][19].
504
+
505
+ ### amOnPage
506
+
507
+ Opens a web page in a browser. Requires relative or absolute url.
508
+ If url starts with `/`, opens a web page of a site defined in `url` config parameter.
509
+
510
+ ```js
511
+ I.amOnPage('/'); // opens main page of website
512
+ I.amOnPage('https://github.com'); // opens github
513
+ I.amOnPage('/login'); // opens a login page
514
+ ```
515
+
516
+ #### Parameters
517
+
518
+ * `url` **[string][18]** url path or global url.
519
+
520
+ Returns **void** automatically synchronized promise through #recorder
521
+
522
+ ### appendField
523
+
524
+ Appends text to a input field or textarea.
525
+ Field is located by name, label, CSS or XPath
526
+
527
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
528
+
529
+ ```js
530
+ I.appendField('#myTextField', 'appended');
531
+ // typing secret
532
+ I.appendField('password', secret('123456'));
533
+ // within a context
534
+ I.appendField('name', 'John', '.form-container');
535
+ ```
536
+
537
+ #### Parameters
538
+
539
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator
540
+ * `value` **[string][18]** text value to append.
541
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
542
+
543
+ Returns **void** automatically synchronized promise through #recorder
544
+
545
+ ### attachFile
546
+
547
+ Appium: not tested
548
+
549
+ Attaches a file to element located by label, name, CSS or XPath
550
+ Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located).
551
+ File will be uploaded to remote system (if tests are running remotely).
552
+
553
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
554
+
555
+ ```js
556
+ I.attachFile('Avatar', 'data/avatar.jpg');
557
+ I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
558
+ // within a context
559
+ I.attachFile('Avatar', 'data/avatar.jpg', '.form-container');
560
+ ```
561
+
562
+ If the locator points to a non-file-input element (e.g., a dropzone area),
563
+ the file will be dropped onto that element using drag-and-drop events.
564
+
565
+ ```js
566
+ I.attachFile('#dropzone', 'data/avatar.jpg');
567
+ ```
568
+
569
+ #### Parameters
570
+
571
+ * `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
572
+ * `pathToFile` **[string][18]** local file path relative to codecept.conf.ts or codecept.conf.js config file.
573
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
574
+
575
+ Returns **void** automatically synchronized promise through #recorder
576
+
577
+ ### blur
578
+
579
+ Remove focus from a text input, button, etc.
580
+ Calls [blur][20] on the element.
581
+
582
+ Examples:
583
+
584
+ ```js
585
+ I.blur('.text-area')
586
+ ```
587
+
588
+ ```js
589
+ //element `#product-tile` is focused
590
+ I.see('#add-to-cart-btn');
591
+ I.blur('#product-tile')
592
+ I.dontSee('#add-to-cart-btn');
593
+ ```
594
+
595
+ #### Parameters
596
+
597
+ * `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
598
+ * `options` **any?** Playwright only: [Additional options][21] for available options object as 2nd argument.
599
+
600
+ Returns **void** automatically synchronized promise through #recorder
601
+
602
+ ### cancelPopup
603
+
604
+ Dismisses the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`.
605
+
606
+ ### checkOption
607
+
608
+ Appium: not tested
609
+ Selects a checkbox or radio button.
610
+ Element is located by label or name or CSS or XPath.
611
+
612
+ The second parameter is an optional context (CSS or XPath locator) to narrow the search.
613
+
614
+ ```js
615
+ I.checkOption('#agree');
616
+ I.checkOption('I Agree to Terms and Conditions');
617
+ I.checkOption('agree', '//form');
618
+ ```
619
+
620
+ #### Parameters
621
+
622
+ * `field` **([string][18] | [object][17])** checkbox located by label | name | CSS | XPath | strict locator.
623
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
624
+
625
+ Returns **void** automatically synchronized promise through #recorder
626
+
627
+ ### clearCookie
628
+
629
+ Clears a cookie by name,
630
+ if none provided clears all cookies.
631
+
632
+ ```js
633
+ I.clearCookie();
634
+ I.clearCookie('test');
635
+ ```
636
+
637
+ #### Parameters
638
+
639
+ * `cookie` **[string][18]?** (optional, `null` by default) cookie name
640
+
641
+ ### clearField
642
+
643
+ Clears a `<textarea>` or text `<input>` element's value.
644
+
645
+ The second parameter is an optional context (CSS or XPath locator) to narrow the search.
646
+
647
+ ```js
648
+ I.clearField('Email');
649
+ I.clearField('user[email]');
650
+ I.clearField('#email');
651
+ // within a context
652
+ I.clearField('Email', '.form-container');
653
+ ```
654
+
655
+ #### Parameters
656
+
657
+ * `field` &#x20;
658
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
659
+ * `editable` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
660
+
661
+ Returns **void** automatically synchronized promise through #recorder.
662
+
663
+ ### click
664
+
665
+ Perform a click on a link or a button, given by a locator.
666
+ If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
667
+ For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
668
+ For images, the "alt" attribute and inner text of any parent links are searched.
669
+
670
+ If no locator is provided, defaults to clicking the body element (`'//body'`).
671
+
672
+ The second parameter is a context (CSS or XPath locator) to narrow the search.
673
+
674
+ ```js
675
+ // click body element (default)
676
+ I.click();
677
+ // simple link
678
+ I.click('Logout');
679
+ // button of form
680
+ I.click('Submit');
681
+ // CSS button
682
+ I.click('#form input[type=submit]');
683
+ // XPath
684
+ I.click('//form/*[@type=submit]');
685
+ // link in context
686
+ I.click('Logout', '#nav');
687
+ // using strict locator
688
+ I.click({css: 'nav a.login'});
689
+ // using ARIA role locator
690
+ I.click({role: 'button', name: 'Submit'});
691
+ ```
692
+
693
+ > ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][22].
694
+
695
+ #### Parameters
696
+
697
+ * `locator` **([string][18] | [object][17])** (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
698
+ * `context` **([string][18]? | [object][17] | null)** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
699
+
700
+ Returns **void** automatically synchronized promise through #recorder
701
+
702
+ ### clickXY
703
+
704
+ Performs click at specific coordinates.
705
+ If locator is provided, the coordinates are relative to the element's top-left corner.
706
+ If locator is not provided, the coordinates are relative to the body element.
707
+
708
+ ```js
709
+ // Click at coordinates (100, 200) relative to body
710
+ I.clickXY(100, 200);
711
+
712
+ // Click at coordinates (50, 30) relative to element's top-left corner
713
+ I.clickXY('#someElement', 50, 30);
714
+ ```
715
+
716
+ #### Parameters
717
+
718
+ * `locator` **([string][18] | [object][17] | [number][23])** Element to click on or X coordinate if no element.
719
+ * `x` **[number][23]?** X coordinate relative to element's top-left, or Y coordinate if locator is a number.
720
+ * `y` **[number][23]?** Y coordinate relative to element's top-left.
721
+
722
+ Returns **[Promise][24]<void>**&#x20;
723
+
724
+ ### closeCurrentTab
725
+
726
+ Close current tab.
727
+
728
+ ```js
729
+ I.closeCurrentTab();
730
+ ```
731
+
732
+ Returns **void** automatically synchronized promise through #recorder
733
+
734
+ ### closeOtherTabs
735
+
736
+ Close all tabs except for the current one.
737
+
738
+ ```js
739
+ I.closeOtherTabs();
740
+ ```
741
+
742
+ Returns **void** automatically synchronized promise through #recorder
743
+
744
+ ### defineTimeout
745
+
746
+ Set [WebDriver timeouts][25] in realtime.
747
+
748
+ Timeouts are expected to be passed as object:
749
+
750
+ ```js
751
+ I.defineTimeout({ script: 5000 });
752
+ I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
753
+ ```
754
+
755
+ #### Parameters
756
+
757
+ * `timeouts` **any** WebDriver timeouts object.
758
+
759
+ ### dontSee
760
+
761
+ Opposite to `see`. Checks that a text is not present on a page.
762
+ Use context parameter to narrow down the search.
763
+
764
+ ```js
765
+ I.dontSee('Login'); // assume we are already logged in.
766
+ I.dontSee('Login', '.nav'); // no login inside .nav element
767
+ ```
768
+
769
+ #### Parameters
770
+
771
+ * `text` **[string][18]** which is not present.
772
+ * `context` **([string][18] | [object][17])?** (optional) element located by CSS|XPath|strict locator in which to perfrom search.
773
+
774
+ Returns **void** automatically synchronized promise through #recorder
775
+
776
+ ### dontSeeCheckboxIsChecked
777
+
778
+ Appium: not tested
779
+ Verifies that the specified checkbox is not checked.
780
+
781
+ ```js
782
+ I.dontSeeCheckboxIsChecked('#agree'); // located by ID
783
+ I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
784
+ I.dontSeeCheckboxIsChecked('agree'); // located by name
785
+ ```
786
+
787
+ #### Parameters
788
+
789
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
790
+
791
+ Returns **void** automatically synchronized promise through #recorder
792
+
793
+ ### dontSeeCookie
794
+
795
+ Checks that cookie with given name does not exist.
796
+
797
+ ```js
798
+ I.dontSeeCookie('auth'); // no auth cookie
799
+ ```
800
+
801
+ #### Parameters
802
+
803
+ * `name` **[string][18]** cookie name.
804
+
805
+ Returns **void** automatically synchronized promise through #recorder
806
+
807
+ ### dontSeeCurrentPathEquals
808
+
809
+ Checks that current URL path does NOT match the expected path.
810
+ Query strings and URL fragments are ignored.
811
+
812
+ ```js
813
+ I.dontSeeCurrentPathEquals('/form'); // fails for '/form', '/form?user=1', '/form#section'
814
+ I.dontSeeCurrentPathEquals('/'); // fails for '/', '/?user=ok', '/#top'
815
+ ```
816
+
817
+ #### Parameters
818
+
819
+ * `path` **[string][18]** value to check.
820
+
821
+ Returns **void** automatically synchronized promise through #recorder
822
+
823
+ ### dontSeeCurrentUrlEquals
824
+
825
+ Checks that current url is not equal to provided one.
826
+ If a relative url provided, a configured url will be prepended to it.
827
+
828
+ ```js
829
+ I.dontSeeCurrentUrlEquals('/login'); // relative url are ok
830
+ I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok
831
+ ```
832
+
833
+ #### Parameters
834
+
835
+ * `url` **[string][18]** value to check.
836
+
837
+ Returns **void** automatically synchronized promise through #recorder
838
+
839
+ ### dontSeeElement
840
+
841
+ Opposite to `seeElement`. Checks that element is not visible (or in DOM)
842
+
843
+ The second parameter is a context (CSS or XPath locator) to narrow the search.
844
+
845
+ ```js
846
+ I.dontSeeElement('.modal'); // modal is not shown
847
+ I.dontSeeElement('.modal', '#container');
848
+ ```
849
+
850
+ #### Parameters
851
+
852
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|Strict locator.
853
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
854
+
855
+ Returns **void** automatically synchronized promise through #recorder
856
+
857
+ ### dontSeeElementInDOM
858
+
859
+ Opposite to `seeElementInDOM`. Checks that element is not on page.
860
+
861
+ ```js
862
+ I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
863
+ ```
864
+
865
+ #### Parameters
866
+
867
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|Strict locator.
868
+
869
+ Returns **void** automatically synchronized promise through #recorder
870
+
871
+ ### dontSeeInCurrentUrl
872
+
873
+ Checks that current url does not contain a provided fragment.
874
+
875
+ #### Parameters
876
+
877
+ * `url` **[string][18]** value to check.
878
+
879
+ Returns **void** automatically synchronized promise through #recorder
880
+
881
+ ### dontSeeInField
882
+
883
+ Checks that value of input field or textarea doesn't equal to given value
884
+ Opposite to `seeInField`.
885
+
886
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
887
+
888
+ ```js
889
+ I.dontSeeInField('email', 'user@user.com'); // field by name
890
+ I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
891
+ // within a context
892
+ I.dontSeeInField('Name', 'old_value', '.form-container');
893
+ ```
894
+
895
+ #### Parameters
896
+
897
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
898
+ * `value` **([string][18] | [object][17])** value to check.
899
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
900
+
901
+ Returns **void** automatically synchronized promise through #recorder
902
+
903
+ ### dontSeeInSource
904
+
905
+ Checks that the current page does not contains the given string in its raw source code.
906
+
907
+ ```js
908
+ I.dontSeeInSource('<!--'); // no comments in source
909
+ ```
910
+
911
+ #### Parameters
912
+
913
+ * `text` &#x20;
914
+ * `value` **[string][18]** to check.
915
+
916
+ Returns **void** automatically synchronized promise through #recorder
917
+
918
+ ### dontSeeInTitle
919
+
920
+ Checks that title does not contain text.
921
+
922
+ ```js
923
+ I.dontSeeInTitle('Error');
924
+ ```
925
+
926
+ #### Parameters
927
+
928
+ * `text` **[string][18]** value to check.
929
+
930
+ Returns **void** automatically synchronized promise through #recorder
931
+
932
+ ### doubleClick
933
+
934
+ Performs a double-click on an element matched by link|button|label|CSS or XPath.
935
+ Context can be specified as second parameter to narrow search.
936
+
937
+ ```js
938
+ I.doubleClick('Edit');
939
+ I.doubleClick('Edit', '.actions');
940
+ I.doubleClick({css: 'button.accept'});
941
+ I.doubleClick('.btn.edit');
942
+ ```
943
+
944
+ #### Parameters
945
+
946
+ * `locator` **([string][18] | [object][17])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
947
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
948
+
949
+ Returns **void** automatically synchronized promise through #recorder
950
+
951
+ ### dragAndDrop
952
+
953
+ Appium: not tested
954
+ Drag an item to a destination element.
955
+
956
+ ```js
957
+ I.dragAndDrop('#dragHandle', '#container');
958
+ ```
959
+
960
+ #### Parameters
961
+
962
+ * `srcElement` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
963
+ * `destElement` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
964
+
965
+ Returns **void** automatically synchronized promise through #recorder
966
+
967
+ ### dragSlider
968
+
969
+ Drag the scrubber of a slider to a given position
970
+ For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
971
+
972
+ ```js
973
+ I.dragSlider('#slider', 30);
974
+ I.dragSlider('#slider', -70);
975
+ ```
976
+
977
+ #### Parameters
978
+
979
+ * `locator` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
980
+ * `offsetX` **[number][23]** position to drag.
981
+
982
+ Returns **void** automatically synchronized promise through #recorder
983
+
984
+ ### executeAsyncScript
985
+
986
+ Executes async script on page.
987
+ Provided function should execute a passed callback (as first argument) to signal it is finished.
988
+
989
+ Example: In Vue.js to make components completely rendered we are waiting for [nextTick][26].
990
+
991
+ ```js
992
+ I.executeAsyncScript(function(done) {
993
+ Vue.nextTick(done); // waiting for next tick
994
+ });
995
+ ```
996
+
997
+ By passing value to `done()` function you can return values.
998
+ Additional arguments can be passed as well, while `done` function is always last parameter in arguments list.
999
+
1000
+ ```js
1001
+ let val = await I.executeAsyncScript(function(url, done) {
1002
+ // in browser context
1003
+ $.ajax(url, { success: (data) => done(data); }
1004
+ }, 'http://ajax.callback.url/');
1005
+ ```
1006
+
1007
+ #### Parameters
1008
+
1009
+ * `args` **...any** to be passed to function.
1010
+ * `fn` **([string][18] | [function][27])** function to be executed in browser context.
1011
+
1012
+ Returns **[Promise][24]<any>** script return value
1013
+
1014
+ ### executeScript
1015
+
1016
+ Wraps [execute][28] command.
1017
+
1018
+ Executes sync script on a page.
1019
+ Pass arguments to function as additional parameters.
1020
+ Will return execution result to a test.
1021
+ In this case you should use async function and await to receive results.
1022
+
1023
+ Example with jQuery DatePicker:
1024
+
1025
+ ```js
1026
+ // change date of jQuery DatePicker
1027
+ I.executeScript(function() {
1028
+ // now we are inside browser context
1029
+ $('date').datetimepicker('setDate', new Date());
1030
+ });
1031
+ ```
1032
+
1033
+ Can return values. Don't forget to use `await` to get them.
1034
+
1035
+ ```js
1036
+ let date = await I.executeScript(function(el) {
1037
+ // only basic types can be returned
1038
+ return $(el).datetimepicker('getDate').toString();
1039
+ }, '#date'); // passing jquery selector
1040
+ ```
1041
+
1042
+ #### Parameters
1043
+
1044
+ * `args` **...any** to be passed to function.
1045
+ * `fn` **([string][18] | [function][27])** function to be executed in browser context.
1046
+
1047
+ Returns **[Promise][24]<any>** script return value
1048
+
1049
+ ### fillField
1050
+
1051
+ Fills a text field or textarea, after clearing its value, with the given string.
1052
+ Field is located by name, label, CSS, or XPath.
1053
+
1054
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
1055
+
1056
+ ```js
1057
+ // by label
1058
+ I.fillField('Email', 'hello@world.com');
1059
+ // by name
1060
+ I.fillField('password', secret('123456'));
1061
+ // by CSS
1062
+ I.fillField('form#login input[name=username]', 'John');
1063
+ // or by strict locator
1064
+ I.fillField({css: 'form#login input[name=username]'}, 'John');
1065
+ // by ARIA role locator
1066
+ I.fillField({role: 'textbox', name: 'Email'}, 'hello@world.com');
1067
+ // within a context
1068
+ I.fillField('Name', 'John', '#section2');
1069
+ ```
1070
+
1071
+ > ℹ️ ARIA role locators (`{role, name}`) match fields by their accessible name and survive markup refactors. See [Locators][22].
1072
+
1073
+ #### Parameters
1074
+
1075
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
1076
+ * `value` **([string][18] | [object][17])** text value to fill.
1077
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
1078
+
1079
+ Returns **void** automatically synchronized promise through #recorder{{ custom }}
1080
+
1081
+ ### focus
1082
+
1083
+ Calls [focus][20] on the matching element.
1084
+
1085
+ Examples:
1086
+
1087
+ ```js
1088
+ I.dontSee('#add-to-cart-btn');
1089
+ I.focus('#product-tile')
1090
+ I.see('#add-to-cart-bnt');
1091
+ ```
1092
+
1093
+ #### Parameters
1094
+
1095
+ * `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
1096
+ * `options` **any?** Playwright only: [Additional options][29] for available options object as 2nd argument.
1097
+
1098
+ Returns **void** automatically synchronized promise through #recorder
1099
+
1100
+ ### forceClick
1101
+
1102
+ Perform an emulated click on a link or a button, given by a locator.
1103
+ Unlike normal click instead of sending native event, emulates a click with JavaScript.
1104
+ This works on hidden, animated or inactive elements as well.
1105
+
1106
+ If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
1107
+ For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
1108
+ For images, the "alt" attribute and inner text of any parent links are searched.
1109
+
1110
+ The second parameter is a context (CSS or XPath locator) to narrow the search.
1111
+
1112
+ ```js
1113
+ // simple link
1114
+ I.forceClick('Logout');
1115
+ // button of form
1116
+ I.forceClick('Submit');
1117
+ // CSS button
1118
+ I.forceClick('#form input[type=submit]');
1119
+ // XPath
1120
+ I.forceClick('//form/*[@type=submit]');
1121
+ // link in context
1122
+ I.forceClick('Logout', '#nav');
1123
+ // using strict locator
1124
+ I.forceClick({css: 'nav a.login'});
1125
+ ```
1126
+
1127
+ #### Parameters
1128
+
1129
+ * `locator` **([string][18] | [object][17])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
1130
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
1131
+
1132
+ Returns **void** automatically synchronized promise through #recorder
1133
+
1134
+ ### forceRightClick
1135
+
1136
+ Emulates right click on an element.
1137
+ Unlike normal click instead of sending native event, emulates a click with JavaScript.
1138
+ This works on hidden, animated or inactive elements as well.
1139
+
1140
+ If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
1141
+ For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
1142
+ For images, the "alt" attribute and inner text of any parent links are searched.
1143
+
1144
+ The second parameter is a context (CSS or XPath locator) to narrow the search.
1145
+
1146
+ ```js
1147
+ // simple link
1148
+ I.forceRightClick('Menu');
1149
+ ```
1150
+
1151
+ #### Parameters
1152
+
1153
+ * `locator` **([string][18] | [object][17])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
1154
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.
1155
+
1156
+ Returns **void** automatically synchronized promise through #recorder
1157
+
1158
+ ### grabAllWindowHandles
1159
+
1160
+ Get all Window Handles.
1161
+ Useful for referencing a specific handle when calling `I.switchToWindow(handle)`
1162
+
1163
+ ```js
1164
+ const windows = await I.grabAllWindowHandles();
1165
+ ```
1166
+
1167
+ Returns **[Promise][24]<[Array][30]<[string][18]>>**&#x20;
1168
+
1169
+ ### grabAttributeFrom
1170
+
1171
+ Retrieves an attribute from an element located by CSS or XPath and returns it to test.
1172
+ Resumes test execution, so **should be used inside async with `await`** operator.
1173
+ If more than one element is found - attribute of first element is returned.
1174
+
1175
+ ```js
1176
+ let hint = await I.grabAttributeFrom('#tooltip', 'title');
1177
+ ```
1178
+
1179
+ #### Parameters
1180
+
1181
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1182
+ * `attr` **[string][18]** attribute name.
1183
+
1184
+ Returns **[Promise][24]<[string][18]>** attribute value
1185
+
1186
+ ### grabAttributeFromAll
1187
+
1188
+ Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
1189
+ Resumes test execution, so **should be used inside async with `await`** operator.
1190
+
1191
+ ```js
1192
+ let hints = await I.grabAttributeFromAll('.tooltip', 'title');
1193
+ ```
1194
+
1195
+ #### Parameters
1196
+
1197
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1198
+ * `attr` **[string][18]** attribute name.
1199
+
1200
+ Returns **[Promise][24]<[Array][30]<[string][18]>>** attribute value
1201
+
1202
+ ### grabBrowserLogs
1203
+
1204
+ Get JS log from browser. Log buffer is reset after each request.
1205
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1206
+
1207
+ ```js
1208
+ let logs = await I.grabBrowserLogs();
1209
+ console.log(JSON.stringify(logs))
1210
+ ```
1211
+
1212
+ Returns **([Promise][24]<[Array][30]<[object][17]>> | [undefined][31])** all browser logs
1213
+
1214
+ ### grabCookie
1215
+
1216
+ Gets a cookie object by name.
1217
+ If none provided gets all cookies.
1218
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1219
+
1220
+ ```js
1221
+ let cookie = await I.grabCookie('auth');
1222
+ assert(cookie.value, '123456');
1223
+ ```
1224
+
1225
+ #### Parameters
1226
+
1227
+ * `name` **[string][18]?** cookie name.
1228
+
1229
+ Returns **any** attribute value
1230
+
1231
+ ### grabCssPropertyFrom
1232
+
1233
+ Grab CSS property for given locator
1234
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1235
+ If more than one element is found - value of first element is returned.
1236
+
1237
+ ```js
1238
+ const value = await I.grabCssPropertyFrom('h3', 'font-weight');
1239
+ ```
1240
+
1241
+ #### Parameters
1242
+
1243
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1244
+ * `cssProperty` **[string][18]** CSS property name.
1245
+
1246
+ Returns **[Promise][24]<[string][18]>** CSS value
1247
+
1248
+ ### grabCssPropertyFromAll
1249
+
1250
+ Grab array of CSS properties for given locator
1251
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1252
+
1253
+ ```js
1254
+ const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
1255
+ ```
1256
+
1257
+ #### Parameters
1258
+
1259
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1260
+ * `cssProperty` **[string][18]** CSS property name.
1261
+
1262
+ Returns **[Promise][24]<[Array][30]<[string][18]>>** CSS value
1263
+
1264
+ ### grabCurrentUrl
1265
+
1266
+ Get current URL from browser.
1267
+ Resumes test execution, so should be used inside an async function.
1268
+
1269
+ ```js
1270
+ let url = await I.grabCurrentUrl();
1271
+ console.log(`Current URL is [${url}]`);
1272
+ ```
1273
+
1274
+ Returns **[Promise][24]<[string][18]>** current URL
1275
+
1276
+ ### grabCurrentWindowHandle
1277
+
1278
+ Get the current Window Handle.
1279
+ Useful for referencing it when calling `I.switchToWindow(handle)`
1280
+
1281
+ ```js
1282
+ const window = await I.grabCurrentWindowHandle();
1283
+ ```
1284
+
1285
+ Returns **[Promise][24]<[string][18]>**&#x20;
1286
+
1287
+ ### grabElementBoundingRect
1288
+
1289
+ Grab the width, height, location of given locator.
1290
+ Provide `width` or `height`as second param to get your desired prop.
1291
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1292
+
1293
+ Returns an object with `x`, `y`, `width`, `height` keys.
1294
+
1295
+ ```js
1296
+ const value = await I.grabElementBoundingRect('h3');
1297
+ // value is like { x: 226.5, y: 89, width: 527, height: 220 }
1298
+ ```
1299
+
1300
+ To get only one metric use second parameter:
1301
+
1302
+ ```js
1303
+ const width = await I.grabElementBoundingRect('h3', 'width');
1304
+ // width == 527
1305
+ ```
1306
+
1307
+ #### Parameters
1308
+
1309
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1310
+ * `prop` &#x20;
1311
+ * `elementSize` **[string][18]?** x, y, width or height of the given element.
1312
+
1313
+ Returns **([Promise][24]<DOMRect> | [Promise][24]<[number][23]>)** Element bounding rectangle
1314
+
1315
+ ### grabHTMLFrom
1316
+
1317
+ Retrieves the innerHTML from an element located by CSS or XPath and returns it to test.
1318
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1319
+ If more than one element is found - HTML of first element is returned.
1320
+
1321
+ ```js
1322
+ let postHTML = await I.grabHTMLFrom('#post');
1323
+ ```
1324
+
1325
+ #### Parameters
1326
+
1327
+ * `locator` &#x20;
1328
+ * `element` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1329
+
1330
+ Returns **[Promise][24]<[string][18]>** HTML code for an element
1331
+
1332
+ ### grabHTMLFromAll
1333
+
1334
+ Retrieves all the innerHTML from elements located by CSS or XPath and returns it to test.
1335
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1336
+
1337
+ ```js
1338
+ let postHTMLs = await I.grabHTMLFromAll('.post');
1339
+ ```
1340
+
1341
+ #### Parameters
1342
+
1343
+ * `locator` &#x20;
1344
+ * `element` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1345
+
1346
+ Returns **[Promise][24]<[Array][30]<[string][18]>>** HTML code for an element
1347
+
1348
+ ### grabNumberOfOpenTabs
1349
+
1350
+ Grab number of open tabs.
1351
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1352
+
1353
+ ```js
1354
+ let tabs = await I.grabNumberOfOpenTabs();
1355
+ ```
1356
+
1357
+ Returns **[Promise][24]<[number][23]>** number of open tabs
1358
+
1359
+ ### grabNumberOfVisibleElements
1360
+
1361
+ Grab number of visible elements by locator.
1362
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1363
+
1364
+ ```js
1365
+ let numOfElements = await I.grabNumberOfVisibleElements('p');
1366
+ ```
1367
+
1368
+ #### Parameters
1369
+
1370
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1371
+
1372
+ Returns **[Promise][24]<[number][23]>** number of visible elements
1373
+
1374
+ ### grabPageScrollPosition
1375
+
1376
+ Retrieves a page scroll position and returns it to test.
1377
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1378
+
1379
+ ```js
1380
+ let { x, y } = await I.grabPageScrollPosition();
1381
+ ```
1382
+
1383
+ Returns **[Promise][24]<PageScrollPosition>** scroll position
1384
+
1385
+ ### grabPopupText
1386
+
1387
+ Grab the text within the popup. If no popup is visible then it will return null.
1388
+
1389
+ ```js
1390
+ await I.grabPopupText();
1391
+ ```
1392
+
1393
+ Returns **[Promise][24]<[string][18]>**&#x20;
1394
+
1395
+ ### grabSource
1396
+
1397
+ Retrieves page source and returns it to test.
1398
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1399
+
1400
+ ```js
1401
+ let pageSource = await I.grabSource();
1402
+ ```
1403
+
1404
+ Returns **[Promise][24]<[string][18]>** source code
1405
+
1406
+ ### grabTextFrom
1407
+
1408
+ Retrieves a text from an element located by CSS or XPath and returns it to test.
1409
+ Resumes test execution, so **should be used inside async with `await`** operator.
1410
+
1411
+ ```js
1412
+ let pin = await I.grabTextFrom('#pin');
1413
+ ```
1414
+
1415
+ If multiple elements found returns first element.
1416
+
1417
+ #### Parameters
1418
+
1419
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1420
+
1421
+ Returns **[Promise][24]<[string][18]>** attribute value
1422
+
1423
+ ### grabTextFromAll
1424
+
1425
+ Retrieves all texts from an element located by CSS or XPath and returns it to test.
1426
+ Resumes test execution, so **should be used inside async with `await`** operator.
1427
+
1428
+ ```js
1429
+ let pins = await I.grabTextFromAll('#pin li');
1430
+ ```
1431
+
1432
+ #### Parameters
1433
+
1434
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1435
+
1436
+ Returns **[Promise][24]<[Array][30]<[string][18]>>** attribute value
1437
+
1438
+ ### grabTitle
1439
+
1440
+ Retrieves a page title and returns it to test.
1441
+ Resumes test execution, so **should be used inside async with `await`** operator.
1442
+
1443
+ ```js
1444
+ let title = await I.grabTitle();
1445
+ ```
1446
+
1447
+ Returns **[Promise][24]<[string][18]>** title
1448
+
1449
+ ### grabValueFrom
1450
+
1451
+ Retrieves a value from a form element located by CSS or XPath and returns it to test.
1452
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1453
+ If more than one element is found - value of first element is returned.
1454
+
1455
+ ```js
1456
+ let email = await I.grabValueFrom('input[name=email]');
1457
+ ```
1458
+
1459
+ #### Parameters
1460
+
1461
+ * `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
1462
+
1463
+ Returns **[Promise][24]<[string][18]>** attribute value
1464
+
1465
+ ### grabValueFromAll
1466
+
1467
+ Retrieves an array of value from a form located by CSS or XPath and returns it to test.
1468
+ Resumes test execution, so **should be used inside async function with `await`** operator.
1469
+
1470
+ ```js
1471
+ let inputs = await I.grabValueFromAll('//form/input');
1472
+ ```
1473
+
1474
+ #### Parameters
1475
+
1476
+ * `locator` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
1477
+
1478
+ Returns **[Promise][24]<[Array][30]<[string][18]>>** attribute value
1479
+
1480
+ ### grabWebElement
1481
+
1482
+ Grab WebElement for given locator
1483
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1484
+
1485
+ ```js
1486
+ const webElement = await I.grabWebElement('#button');
1487
+ ```
1488
+
1489
+ #### Parameters
1490
+
1491
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1492
+
1493
+ Returns **[Promise][24]<any>** WebElement of being used Web helper
1494
+
1495
+ ### grabWebElements
1496
+
1497
+ Grab WebElements for given locator
1498
+ Resumes test execution, so **should be used inside an async function with `await`** operator.
1499
+
1500
+ ```js
1501
+ const webElements = await I.grabWebElements('#button');
1502
+ ```
1503
+
1504
+ #### Parameters
1505
+
1506
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1507
+
1508
+ Returns **[Promise][24]<any>** WebElement of being used Web helper
1509
+
1510
+ ### moveCursorTo
1511
+
1512
+ Moves cursor to element matched by locator.
1513
+ Extra shift can be set with offsetX and offsetY options.
1514
+
1515
+ An optional `context` (as a second parameter) can be specified to narrow the search to an element within a parent.
1516
+ When the second argument is a non-number (string or locator object), it is treated as context.
1517
+
1518
+ ```js
1519
+ I.moveCursorTo('.tooltip');
1520
+ I.moveCursorTo('#submit', 5,5);
1521
+ I.moveCursorTo('#submit', '.container');
1522
+ ```
1523
+
1524
+ #### Parameters
1525
+
1526
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1527
+ * `xOffset` &#x20;
1528
+ * `yOffset` &#x20;
1529
+ * `offsetX` **([number][23] | [string][18] | [object][17])** (optional, `0` by default) X-axis offset or context locator.
1530
+ * `offsetY` **[number][23]** (optional, `0` by default) Y-axis offset.
1531
+
1532
+ Returns **void** automatically synchronized promise through #recorder
1533
+
1534
+ ### openNewTab
1535
+
1536
+ Open new tab and switch to it.
1537
+
1538
+ ```js
1539
+ I.openNewTab();
1540
+ ```
1541
+
1542
+ #### Parameters
1543
+
1544
+ * `url`
1545
+ * `windowName`
1546
+
1547
+ Returns **void** automatically synchronized promise through #recorder
1548
+
1549
+ ### pressKey
1550
+
1551
+ *Note:* In case a text field or textarea is focused be aware that some browsers do not respect active modifier when combining modifier keys with other keys.
1552
+
1553
+ Presses a key in the browser (on a focused element).
1554
+
1555
+ *Hint:* For populating text field or textarea, it is recommended to use [`fillField`][32].
1556
+
1557
+ ```js
1558
+ I.pressKey('Backspace');
1559
+ ```
1560
+
1561
+ To press a key in combination with modifier keys, pass the sequence as an array. All modifier keys (`'Alt'`, `'Control'`, `'Meta'`, `'Shift'`) will be released afterwards.
1562
+
1563
+ ```js
1564
+ I.pressKey(['Control', 'Z']);
1565
+ ```
1566
+
1567
+ For specifying operation modifier key based on operating system it is suggested to use `'CommandOrControl'`.
1568
+ This will press `'Command'` (also known as `'Meta'`) on macOS machines and `'Control'` on non-macOS machines.
1569
+
1570
+ ```js
1571
+ I.pressKey(['CommandOrControl', 'Z']);
1572
+ ```
1573
+
1574
+ Some of the supported key names are:
1575
+
1576
+ * `'AltLeft'` or `'Alt'`
1577
+ * `'AltRight'`
1578
+ * `'ArrowDown'`
1579
+ * `'ArrowLeft'`
1580
+ * `'ArrowRight'`
1581
+ * `'ArrowUp'`
1582
+ * `'Backspace'`
1583
+ * `'Clear'`
1584
+ * `'ControlLeft'` or `'Control'`
1585
+ * `'ControlRight'`
1586
+ * `'Command'`
1587
+ * `'CommandOrControl'`
1588
+ * `'Delete'`
1589
+ * `'End'`
1590
+ * `'Enter'`
1591
+ * `'Escape'`
1592
+ * `'F1'` to `'F12'`
1593
+ * `'Home'`
1594
+ * `'Insert'`
1595
+ * `'MetaLeft'` or `'Meta'`
1596
+ * `'MetaRight'`
1597
+ * `'Numpad0'` to `'Numpad9'`
1598
+ * `'NumpadAdd'`
1599
+ * `'NumpadDecimal'`
1600
+ * `'NumpadDivide'`
1601
+ * `'NumpadMultiply'`
1602
+ * `'NumpadSubtract'`
1603
+ * `'PageDown'`
1604
+ * `'PageUp'`
1605
+ * `'Pause'`
1606
+ * `'Return'`
1607
+ * `'ShiftLeft'` or `'Shift'`
1608
+ * `'ShiftRight'`
1609
+ * `'Space'`
1610
+ * `'Tab'`
1611
+
1612
+ #### Parameters
1613
+
1614
+ * `key` **([string][18] | [Array][30]<[string][18]>)** key or array of keys to press.
1615
+
1616
+ Returns **void** automatically synchronized promise through #recorder
1617
+
1618
+ ### pressKeyDown
1619
+
1620
+ Presses a key in the browser and leaves it in a down state.
1621
+
1622
+ To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][33]).
1623
+
1624
+ ```js
1625
+ I.pressKeyDown('Control');
1626
+ I.click('#element');
1627
+ I.pressKeyUp('Control');
1628
+ ```
1629
+
1630
+ #### Parameters
1631
+
1632
+ * `key` **[string][18]** name of key to press down.
1633
+
1634
+ Returns **void** automatically synchronized promise through #recorder
1635
+
1636
+ ### pressKeyUp
1637
+
1638
+ Releases a key in the browser which was previously set to a down state.
1639
+
1640
+ To make combinations with modifier key and user operation (e.g. `'Control'` + [`click`][33]).
1641
+
1642
+ ```js
1643
+ I.pressKeyDown('Control');
1644
+ I.click('#element');
1645
+ I.pressKeyUp('Control');
1646
+ ```
1647
+
1648
+ #### Parameters
1649
+
1650
+ * `key` **[string][18]** name of key to release.
1651
+
1652
+ Returns **void** automatically synchronized promise through #recorder
1653
+
1654
+ ### refreshPage
1655
+
1656
+ Reload the current page.
1657
+
1658
+ ```js
1659
+ I.refreshPage();
1660
+ ```
1661
+
1662
+ Returns **void** automatically synchronized promise through #recorder
1663
+
1664
+ ### resizeWindow
1665
+
1666
+ Appium: not tested in web, in apps doesn't work
1667
+
1668
+ Resize the current window to provided width and height.
1669
+ First parameter can be set to `maximize`.
1670
+
1671
+ #### Parameters
1672
+
1673
+ * `width` **[number][23]** width in pixels or `maximize`.
1674
+ * `height` **[number][23]** height in pixels.
1675
+
1676
+ Returns **void** automatically synchronized promise through #recorder
1677
+
1678
+ ### rightClick
1679
+
1680
+ Performs right click on a clickable element matched by semantic locator, CSS or XPath.
1681
+
1682
+ ```js
1683
+ // right click element with id el
1684
+ I.rightClick('#el');
1685
+ // right click link or button with text "Click me"
1686
+ I.rightClick('Click me');
1687
+ // right click button with text "Click me" inside .context
1688
+ I.rightClick('Click me', '.context');
1689
+ ```
1690
+
1691
+ #### Parameters
1692
+
1693
+ * `locator` **([string][18] | [object][17])** clickable element located by CSS|XPath|strict locator.
1694
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS|XPath|strict locator.
1695
+
1696
+ Returns **void** automatically synchronized promise through #recorder
1697
+
1698
+ ### runInWeb
1699
+
1700
+ Placeholder for ~ locator only test case write once run on both Appium and WebDriver.
1701
+
1702
+ #### Parameters
1703
+
1704
+ * `fn` &#x20;
1705
+
1706
+ ### runOnAndroid
1707
+
1708
+ Placeholder for ~ locator only test case write once run on both Appium and WebDriver.
1709
+
1710
+ #### Parameters
1711
+
1712
+ * `caps` **any**&#x20;
1713
+ * `fn` **any**&#x20;
1714
+
1715
+ ### runOnIOS
1716
+
1717
+ Placeholder for ~ locator only test case write once run on both Appium and WebDriver.
1718
+
1719
+ #### Parameters
1720
+
1721
+ * `caps` **any**&#x20;
1722
+ * `fn` **any**&#x20;
1723
+
1724
+ ### saveElementScreenshot
1725
+
1726
+ Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
1727
+ Filename is relative to output folder.
1728
+
1729
+ ```js
1730
+ I.saveElementScreenshot(`#submit`,'debug.png');
1731
+ ```
1732
+
1733
+ #### Parameters
1734
+
1735
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1736
+ * `fileName` **[string][18]** file name to save.
1737
+
1738
+ Returns **void** automatically synchronized promise through #recorder
1739
+
1740
+ ### saveScreenshot
1741
+
1742
+ Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
1743
+ Filename is relative to output folder.
1744
+ Optionally resize the window to the full available page `scrollHeight` and `scrollWidth` to capture the entire page by passing `true` in as the second argument.
1745
+
1746
+ ```js
1747
+ I.saveScreenshot('debug.png');
1748
+ I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
1749
+ ```
1750
+
1751
+ #### Parameters
1752
+
1753
+ * `fileName` **[string][18]** file name to save.
1754
+ * `fullPage` **[boolean][34]** (optional, `false` by default) flag to enable fullscreen screenshot mode.
1755
+
1756
+ Returns **void** automatically synchronized promise through #recorder
1757
+
1758
+ ### scrollIntoView
1759
+
1760
+ Scroll element into viewport.
1761
+
1762
+ ```js
1763
+ I.scrollIntoView('#submit');
1764
+ I.scrollIntoView('#submit', true);
1765
+ I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "center" });
1766
+ ```
1767
+
1768
+ #### Parameters
1769
+
1770
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1771
+ * `scrollIntoViewOptions` **(ScrollIntoViewOptions | [boolean][34])** either alignToTop=true|false or scrollIntoViewOptions. See [https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView][35].
1772
+
1773
+ Returns **void** automatically synchronized promise through #recorder
1774
+
1775
+ ### scrollPageToBottom
1776
+
1777
+ Scroll page to the bottom.
1778
+
1779
+ ```js
1780
+ I.scrollPageToBottom();
1781
+ ```
1782
+
1783
+ Returns **void** automatically synchronized promise through #recorder
1784
+
1785
+ ### scrollPageToTop
1786
+
1787
+ Scroll page to the top.
1788
+
1789
+ ```js
1790
+ I.scrollPageToTop();
1791
+ ```
1792
+
1793
+ Returns **void** automatically synchronized promise through #recorder
1794
+
1795
+ ### scrollTo
1796
+
1797
+ Scrolls to element matched by locator.
1798
+ Extra shift can be set with offsetX and offsetY options.
1799
+
1800
+ ```js
1801
+ I.scrollTo('footer');
1802
+ I.scrollTo('#submit', 5, 5);
1803
+ ```
1804
+
1805
+ #### Parameters
1806
+
1807
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1808
+ * `offsetX` **[number][23]** (optional, `0` by default) X-axis offset.
1809
+ * `offsetY` **[number][23]** (optional, `0` by default) Y-axis offset.
1810
+
1811
+ Returns **void** automatically synchronized promise through #recorder
1812
+
1813
+ ### see
1814
+
1815
+ Checks that a page contains a visible text.
1816
+ Use context parameter to narrow down the search.
1817
+
1818
+ ```js
1819
+ I.see('Welcome'); // text welcome on a page
1820
+ I.see('Welcome', '.content'); // text inside .content div
1821
+ I.see('Register', {css: 'form.register'}); // use strict locator
1822
+ ```
1823
+
1824
+ #### Parameters
1825
+
1826
+ * `text` **[string][18]** expected on page.
1827
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
1828
+
1829
+ Returns **void** automatically synchronized promise through #recorder
1830
+
1831
+ ### seeAttributesOnElements
1832
+
1833
+ Checks that all elements with given locator have given attributes.
1834
+
1835
+ ```js
1836
+ I.seeAttributesOnElements('//form', { method: "post"});
1837
+ ```
1838
+
1839
+ #### Parameters
1840
+
1841
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1842
+ * `attributes` **[object][17]** attributes and their values to check.
1843
+
1844
+ Returns **void** automatically synchronized promise through #recorder
1845
+
1846
+ ### seeCheckboxIsChecked
1847
+
1848
+ Appium: not tested
1849
+ Verifies that the specified checkbox is checked.
1850
+
1851
+ ```js
1852
+ I.seeCheckboxIsChecked('Agree');
1853
+ I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
1854
+ I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
1855
+ ```
1856
+
1857
+ #### Parameters
1858
+
1859
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
1860
+
1861
+ Returns **void** automatically synchronized promise through #recorder
1862
+
1863
+ ### seeCookie
1864
+
1865
+ Checks that cookie with given name exists.
1866
+
1867
+ ```js
1868
+ I.seeCookie('Auth');
1869
+ ```
1870
+
1871
+ #### Parameters
1872
+
1873
+ * `name` **[string][18]** cookie name.
1874
+
1875
+ Returns **void** automatically synchronized promise through #recorder
1876
+
1877
+ ### seeCssPropertiesOnElements
1878
+
1879
+ Checks that all elements with given locator have given CSS properties.
1880
+
1881
+ ```js
1882
+ I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
1883
+ ```
1884
+
1885
+ #### Parameters
1886
+
1887
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1888
+ * `cssProperties` **[object][17]** object with CSS properties and their values to check.
1889
+
1890
+ Returns **void** automatically synchronized promise through #recorder
1891
+
1892
+ ### seeCurrentPathEquals
1893
+
1894
+ Checks that current URL path matches the expected path.
1895
+ Query strings and URL fragments are ignored.
1896
+
1897
+ ```js
1898
+ I.seeCurrentPathEquals('/info'); // passes for '/info', '/info?user=1', '/info#section'
1899
+ I.seeCurrentPathEquals('/'); // passes for '/', '/?user=ok', '/#top'
1900
+ ```
1901
+
1902
+ #### Parameters
1903
+
1904
+ * `path` **[string][18]** value to check.
1905
+
1906
+ Returns **void** automatically synchronized promise through #recorder
1907
+
1908
+ ### seeCurrentUrlEquals
1909
+
1910
+ Checks that current url is equal to provided one.
1911
+ If a relative url provided, a configured url will be prepended to it.
1912
+ So both examples will work:
1913
+
1914
+ ```js
1915
+ I.seeCurrentUrlEquals('/register');
1916
+ I.seeCurrentUrlEquals('http://my.site.com/register');
1917
+ ```
1918
+
1919
+ #### Parameters
1920
+
1921
+ * `url` **[string][18]** value to check.
1922
+
1923
+ Returns **void** automatically synchronized promise through #recorder
1924
+
1925
+ ### seeElement
1926
+
1927
+ Checks that a given Element is visible
1928
+ Element is located by CSS or XPath.
1929
+
1930
+ The second parameter is a context (CSS or XPath locator) to narrow the search.
1931
+
1932
+ ```js
1933
+ I.seeElement('#modal');
1934
+ I.seeElement('#modal', '#container');
1935
+ // using ARIA role locator
1936
+ I.seeElement({role: 'dialog'});
1937
+ ```
1938
+
1939
+ > ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][22].
1940
+
1941
+ #### Parameters
1942
+
1943
+ * `locator` **([string][18] | [object][17])** located by CSS|XPath|strict locator.
1944
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
1945
+
1946
+ Returns **void** automatically synchronized promise through #recorder
1947
+
1948
+ ### seeElementInDOM
1949
+
1950
+ Checks that a given Element is present in the DOM
1951
+ Element is located by CSS or XPath.
1952
+
1953
+ ```js
1954
+ I.seeElementInDOM('#modal');
1955
+ ```
1956
+
1957
+ #### Parameters
1958
+
1959
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
1960
+
1961
+ Returns **void** automatically synchronized promise through #recorder
1962
+
1963
+ ### seeInCurrentUrl
1964
+
1965
+ Checks that current url contains a provided fragment.
1966
+
1967
+ ```js
1968
+ I.seeInCurrentUrl('/register'); // we are on registration page
1969
+ ```
1970
+
1971
+ #### Parameters
1972
+
1973
+ * `url` **[string][18]** a fragment to check
1974
+
1975
+ Returns **void** automatically synchronized promise through #recorder
1976
+
1977
+ ### seeInField
1978
+
1979
+ Checks that the given input field or textarea equals to given value.
1980
+ For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
1981
+
1982
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
1983
+
1984
+ ```js
1985
+ I.seeInField('Username', 'davert');
1986
+ I.seeInField({css: 'form textarea'},'Type your comment here');
1987
+ I.seeInField('form input[type=hidden]','hidden_value');
1988
+ I.seeInField('#searchform input','Search');
1989
+ // within a context
1990
+ I.seeInField('Name', 'John', '.form-container');
1991
+ ```
1992
+
1993
+ #### Parameters
1994
+
1995
+ * `field` **([string][18] | [object][17])** located by label|name|CSS|XPath|strict locator.
1996
+ * `value` **([string][18] | [object][17])** value to check.
1997
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
1998
+
1999
+ Returns **void** automatically synchronized promise through #recorder
2000
+
2001
+ ### seeInPopup
2002
+
2003
+ Checks that the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`, contains the
2004
+ given string.
2005
+
2006
+ #### Parameters
2007
+
2008
+ * `text` **[string][18]** value to check.
2009
+
2010
+ ### seeInSource
2011
+
2012
+ Checks that the current page contains the given string in its raw source code.
2013
+
2014
+ ```js
2015
+ I.seeInSource('<h1>Green eggs &amp; ham</h1>');
2016
+ ```
2017
+
2018
+ #### Parameters
2019
+
2020
+ * `text` **[string][18]** value to check.
2021
+
2022
+ Returns **void** automatically synchronized promise through #recorder
2023
+
2024
+ ### seeInTitle
2025
+
2026
+ Checks that title contains text.
2027
+
2028
+ ```js
2029
+ I.seeInTitle('Home Page');
2030
+ ```
2031
+
2032
+ #### Parameters
2033
+
2034
+ * `text` **[string][18]** text value to check.
2035
+
2036
+ Returns **void** automatically synchronized promise through #recorder
2037
+
2038
+ ### seeNumberOfElements
2039
+
2040
+ Asserts that an element appears a given number of times in the DOM.
2041
+ Element is located by label or name or CSS or XPath.
2042
+
2043
+ ```js
2044
+ I.seeNumberOfElements('#submitBtn', 1);
2045
+ ```
2046
+
2047
+ #### Parameters
2048
+
2049
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2050
+ * `num` **[number][23]** number of elements.
2051
+
2052
+ Returns **void** automatically synchronized promise through #recorder
2053
+
2054
+ ### seeNumberOfVisibleElements
2055
+
2056
+ Asserts that an element is visible a given number of times.
2057
+ Element is located by CSS or XPath.
2058
+
2059
+ ```js
2060
+ I.seeNumberOfVisibleElements('.buttons', 3);
2061
+ ```
2062
+
2063
+ #### Parameters
2064
+
2065
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2066
+ * `num` **[number][23]** number of elements.
2067
+
2068
+ Returns **void** automatically synchronized promise through #recorder
2069
+
2070
+ ### seeTextEquals
2071
+
2072
+ Checks that text is equal to provided one.
2073
+
2074
+ ```js
2075
+ I.seeTextEquals('text', 'h1');
2076
+ ```
2077
+
2078
+ #### Parameters
2079
+
2080
+ * `text` **[string][18]** element value to check.
2081
+ * `context` **([string][18] | [object][17])?** element located by CSS|XPath|strict locator.
2082
+
2083
+ Returns **void** automatically synchronized promise through #recorder
2084
+
2085
+ ### seeTitleEquals
2086
+
2087
+ Checks that title is equal to provided one.
2088
+
2089
+ ```js
2090
+ I.seeTitleEquals('Test title.');
2091
+ ```
2092
+
2093
+ #### Parameters
2094
+
2095
+ * `text` **[string][18]** value to check.
2096
+
2097
+ Returns **void** automatically synchronized promise through #recorder
2098
+
2099
+ ### selectOption
2100
+
2101
+ Selects an option in a drop-down select.
2102
+ Field is searched by label | name | CSS | XPath.
2103
+ Option is selected by visible text or by value.
2104
+
2105
+ The third parameter is an optional context (CSS or XPath locator) to narrow the search.
2106
+
2107
+ ```js
2108
+ I.selectOption('Choose Plan', 'Monthly'); // select by label
2109
+ I.selectOption('subscription', 'Monthly'); // match option by text
2110
+ I.selectOption('subscription', '0'); // or by value
2111
+ I.selectOption('//form/select[@name=account]','Premium');
2112
+ I.selectOption('form select[name=account]', 'Premium');
2113
+ I.selectOption({css: 'form select[name=account]'}, 'Premium');
2114
+ // within a context
2115
+ I.selectOption('age', '21-60', '#section2');
2116
+ ```
2117
+
2118
+ Provide an array for the second argument to select multiple options.
2119
+
2120
+ ```js
2121
+ I.selectOption('Which OS do you use?', ['Android', 'iOS']);
2122
+ ```
2123
+
2124
+ #### Parameters
2125
+
2126
+ * `select` **([string][18] | [object][17])** field located by label|name|CSS|XPath|strict locator.
2127
+ * `option` **([string][18] | [Array][30]<any>)** visible text or value of option.
2128
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
2129
+
2130
+ Returns **void** automatically synchronized promise through #recorder
2131
+
2132
+ ### setCookie
2133
+
2134
+ Uses Selenium's JSON [cookie format][36].
2135
+ Sets cookie(s).
2136
+
2137
+ Can be a single cookie object or an array of cookies:
2138
+
2139
+ ```js
2140
+ I.setCookie({name: 'auth', value: true});
2141
+
2142
+ // as array
2143
+ I.setCookie([
2144
+ {name: 'auth', value: true},
2145
+ {name: 'agree', value: true}
2146
+ ]);
2147
+ ```
2148
+
2149
+ #### Parameters
2150
+
2151
+ * `cookie` **(Cookie | [Array][30]<Cookie>)** a cookie object or array of cookie objects.
2152
+
2153
+ Returns **void** automatically synchronized promise through #recorder
2154
+
2155
+ ### switchTo
2156
+
2157
+ Switches frame or in case of null locator reverts to parent.
2158
+
2159
+ ```js
2160
+ I.switchTo('iframe'); // switch to first iframe
2161
+ I.switchTo(); // switch back to main page
2162
+ ```
2163
+
2164
+ #### Parameters
2165
+
2166
+ * `locator` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS|XPath|strict locator.
2167
+
2168
+ Returns **void** automatically synchronized promise through #recorder
2169
+
2170
+ ### switchToNextTab
2171
+
2172
+ Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
2173
+
2174
+ ```js
2175
+ I.switchToNextTab();
2176
+ I.switchToNextTab(2);
2177
+ ```
2178
+
2179
+ #### Parameters
2180
+
2181
+ * `num` **[number][23]?** (optional) number of tabs to switch forward, default: 1.
2182
+ * `sec` **([number][23] | null)?** (optional) time in seconds to wait.
2183
+
2184
+ Returns **void** automatically synchronized promise through #recorder
2185
+
2186
+ ### switchToPreviousTab
2187
+
2188
+ Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
2189
+
2190
+ ```js
2191
+ I.switchToPreviousTab();
2192
+ I.switchToPreviousTab(2);
2193
+ ```
2194
+
2195
+ #### Parameters
2196
+
2197
+ * `num` **[number][23]?** (optional) number of tabs to switch backward, default: 1.
2198
+ * `sec` **[number][23]??** (optional) time in seconds to wait.
2199
+
2200
+ Returns **void** automatically synchronized promise through #recorder
2201
+
2202
+ ### switchToWindow
2203
+
2204
+ Switch to the window with a specified handle.
2205
+
2206
+ ```js
2207
+ const windows = await I.grabAllWindowHandles();
2208
+ // ... do something
2209
+ await I.switchToWindow( windows[0] );
2210
+
2211
+ const window = await I.grabCurrentWindowHandle();
2212
+ // ... do something
2213
+ await I.switchToWindow( window );
2214
+ ```
2215
+
2216
+ #### Parameters
2217
+
2218
+ * `window` **[string][18]** name of window handle.
2219
+
2220
+ ### type
2221
+
2222
+ Types out the given text into an active field.
2223
+ To slow down typing use a second parameter, to set interval between key presses.
2224
+ *Note:* Should be used when [`fillField`][32] is not an option.
2225
+
2226
+ ```js
2227
+ // passing in a string
2228
+ I.type('Type this out.');
2229
+
2230
+ // typing values with a 100ms interval
2231
+ I.type('4141555311111111', 100);
2232
+
2233
+ // passing in an array
2234
+ I.type(['T', 'E', 'X', 'T']);
2235
+
2236
+ // passing a secret
2237
+ I.type(secret('123456'));
2238
+ ```
2239
+
2240
+ #### Parameters
2241
+
2242
+ * `keys` &#x20;
2243
+ * `delay` **[number][23]?** (optional) delay in ms between key presses
2244
+ * `key` **([string][18] | [Array][30]<[string][18]>)** or array of keys to type.
2245
+
2246
+ Returns **void** automatically synchronized promise through #recorder
2247
+
2248
+ ### uncheckOption
2249
+
2250
+ Appium: not tested
2251
+ Unselects a checkbox or radio button.
2252
+ Element is located by label or name or CSS or XPath.
2253
+
2254
+ The second parameter is an optional context (CSS or XPath locator) to narrow the search.
2255
+
2256
+ ```js
2257
+ I.uncheckOption('#agree');
2258
+ I.uncheckOption('I Agree to Terms and Conditions');
2259
+ I.uncheckOption('agree', '//form');
2260
+ ```
2261
+
2262
+ #### Parameters
2263
+
2264
+ * `field` **([string][18] | [object][17])** checkbox located by label | name | CSS | XPath | strict locator.
2265
+ * `context` **([string][18]? | [object][17])** (optional, `null` by default) element located by CSS | XPath | strict locator.
2266
+
2267
+ Returns **void** automatically synchronized promise through #recorder
2268
+
2269
+ ### useWebDriverTo
2270
+
2271
+ Use [webdriverio][37] API inside a test.
2272
+
2273
+ First argument is a description of an action.
2274
+ Second argument is async function that gets this helper as parameter.
2275
+
2276
+ { [`browser`][37]) } object from WebDriver API is available.
2277
+
2278
+ ```js
2279
+ I.useWebDriverTo('open multiple windows', async ({ browser }) {
2280
+ // create new window
2281
+ await browser.newWindow('https://webdriver.io');
2282
+ });
2283
+ ```
2284
+
2285
+ #### Parameters
2286
+
2287
+ * `description` **[string][18]** used to show in logs.
2288
+ * `fn` **[function][27]** async functuion that executed with WebDriver helper as argument
2289
+
2290
+ ### wait
2291
+
2292
+ Pauses execution for a number of seconds.
2293
+
2294
+ ```js
2295
+ I.wait(2); // wait 2 secs
2296
+ ```
2297
+
2298
+ #### Parameters
2299
+
2300
+ * `sec` **[number][23]** number of second to wait.
2301
+
2302
+ Returns **void** automatically synchronized promise through #recorder
2303
+
2304
+ ### waitCurrentPathEquals
2305
+
2306
+ {{> waitCurrentPathEquals }}
2307
+
2308
+ #### Parameters
2309
+
2310
+ * `path` &#x20;
2311
+ * `sec`
2312
+
2313
+ ### waitForClickable
2314
+
2315
+ Waits for element to be clickable (by default waits for 1sec).
2316
+ Element can be located by CSS or XPath.
2317
+
2318
+ ```js
2319
+ I.waitForClickable('.btn.continue');
2320
+ I.waitForClickable('.btn.continue', 5); // wait for 5 secs
2321
+ ```
2322
+
2323
+ #### Parameters
2324
+
2325
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2326
+ * `waitTimeout` &#x20;
2327
+ * `sec` **[number][23]?** (optional, `1` by default) time in seconds to wait
2328
+
2329
+ Returns **void** automatically synchronized promise through #recorder
2330
+
2331
+ ### waitForCookie
2332
+
2333
+ Waits for the specified cookie in the cookies.
2334
+
2335
+ ```js
2336
+ I.waitForCookie("token");
2337
+ ```
2338
+
2339
+ #### Parameters
2340
+
2341
+ * `name` **[string][18]** expected cookie name.
2342
+ * `sec` **[number][23]** (optional, `3` by default) time in seconds to wait
2343
+
2344
+ Returns **void** automatically synchronized promise through #recorder
2345
+
2346
+ ### waitForDetached
2347
+
2348
+ Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
2349
+ Element can be located by CSS or XPath.
2350
+
2351
+ ```js
2352
+ I.waitForDetached('#popup');
2353
+ ```
2354
+
2355
+ #### Parameters
2356
+
2357
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2358
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2359
+
2360
+ Returns **void** automatically synchronized promise through #recorder
2361
+
2362
+ ### waitForElement
2363
+
2364
+ Waits for element to be present on page (by default waits for 1sec).
2365
+ Element can be located by CSS or XPath.
2366
+
2367
+ ```js
2368
+ I.waitForElement('.btn.continue');
2369
+ I.waitForElement('.btn.continue', 5); // wait for 5 secs
2370
+ ```
2371
+
2372
+ #### Parameters
2373
+
2374
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2375
+ * `sec` **[number][23]?** (optional, `1` by default) time in seconds to wait
2376
+
2377
+ Returns **void** automatically synchronized promise through #recorder
2378
+
2379
+ ### waitForEnabled
2380
+
2381
+ Waits for element to become enabled (by default waits for 1sec).
2382
+ Element can be located by CSS or XPath.
2383
+
2384
+ #### Parameters
2385
+
2386
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2387
+ * `sec` **[number][23]** (optional) time in seconds to wait, 1 by default.
2388
+
2389
+ Returns **void** automatically synchronized promise through #recorder
2390
+
2391
+ ### waitForFunction
2392
+
2393
+ Waits for a function to return true (waits for 1 sec by default).
2394
+ Running in browser context.
2395
+
2396
+ ```js
2397
+ I.waitForFunction(fn[, [args[, timeout]])
2398
+ ```
2399
+
2400
+ ```js
2401
+ I.waitForFunction(() => window.requests == 0);
2402
+ I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
2403
+ I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
2404
+ ```
2405
+
2406
+ #### Parameters
2407
+
2408
+ * `fn` **([string][18] | [function][27])** to be executed in browser context.
2409
+ * `argsOrSec` **([Array][30]<any> | [number][23])?** (optional, `1` by default) arguments for function or seconds.
2410
+ * `sec` **[number][23]?** (optional, `1` by default) time in seconds to wait
2411
+
2412
+ Returns **void** automatically synchronized promise through #recorder
2413
+
2414
+ ### waitForInvisible
2415
+
2416
+ Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
2417
+ Element can be located by CSS or XPath.
2418
+
2419
+ ```js
2420
+ I.waitForInvisible('#popup');
2421
+ ```
2422
+
2423
+ #### Parameters
2424
+
2425
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2426
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2427
+
2428
+ Returns **void** automatically synchronized promise through #recorder
2429
+
2430
+ ### waitForNumberOfTabs
2431
+
2432
+ Waits for number of tabs.
2433
+
2434
+ ```js
2435
+ I.waitForNumberOfTabs(2);
2436
+ ```
2437
+
2438
+ #### Parameters
2439
+
2440
+ * `expectedTabs` **[number][23]** expecting the number of tabs.
2441
+ * `sec` **[number][23]** number of secs to wait.
2442
+
2443
+ Returns **void** automatically synchronized promise through #recorder
2444
+
2445
+ ### waitForText
2446
+
2447
+ Waits for a text to appear (by default waits for 1sec).
2448
+ Element can be located by CSS or XPath.
2449
+ Narrow down search results by providing context.
2450
+
2451
+ ```js
2452
+ I.waitForText('Thank you, form has been submitted');
2453
+ I.waitForText('Thank you, form has been submitted', 5, '#modal');
2454
+ ```
2455
+
2456
+ #### Parameters
2457
+
2458
+ * `text` **[string][18]** to wait for.
2459
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2460
+ * `context` **([string][18] | [object][17])?** (optional) element located by CSS|XPath|strict locator.
2461
+
2462
+ Returns **void** automatically synchronized promise through #recorder
2463
+
2464
+ ### waitForValue
2465
+
2466
+ Waits for the specified value to be in value attribute.
2467
+
2468
+ ```js
2469
+ I.waitForValue('//input', "GoodValue");
2470
+ ```
2471
+
2472
+ #### Parameters
2473
+
2474
+ * `field` **([string][18] | [object][17])** input field.
2475
+ * `value` **[string][18]** expected value.
2476
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2477
+
2478
+ Returns **void** automatically synchronized promise through #recorder
2479
+
2480
+ ### waitForVisible
2481
+
2482
+ Waits for an element to become visible on a page (by default waits for 1sec).
2483
+ Element can be located by CSS or XPath.
2484
+
2485
+ ```js
2486
+ I.waitForVisible('#popup');
2487
+ ```
2488
+
2489
+ #### Parameters
2490
+
2491
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2492
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2493
+
2494
+ Returns **void** automatically synchronized promise through #recorder
2495
+
2496
+ ### waitInUrl
2497
+
2498
+ Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
2499
+
2500
+ ```js
2501
+ I.waitInUrl('/info', 2);
2502
+ ```
2503
+
2504
+ #### Parameters
2505
+
2506
+ * `urlPart` **[string][18]** value to check.
2507
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2508
+
2509
+ Returns **void** automatically synchronized promise through #recorder
2510
+
2511
+ ### waitNumberOfVisibleElements
2512
+
2513
+ Waits for a specified number of elements on the page.
2514
+
2515
+ ```js
2516
+ I.waitNumberOfVisibleElements('a', 3);
2517
+ ```
2518
+
2519
+ #### Parameters
2520
+
2521
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2522
+ * `num` **[number][23]** number of elements.
2523
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2524
+
2525
+ Returns **void** automatically synchronized promise through #recorder
2526
+
2527
+ ### waitToHide
2528
+
2529
+ Waits for an element to hide (by default waits for 1sec).
2530
+ Element can be located by CSS or XPath.
2531
+
2532
+ ```js
2533
+ I.waitToHide('#popup');
2534
+ ```
2535
+
2536
+ #### Parameters
2537
+
2538
+ * `locator` **([string][18] | [object][17])** element located by CSS|XPath|strict locator.
2539
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2540
+
2541
+ Returns **void** automatically synchronized promise through #recorder
2542
+
2543
+ ### waitUrlEquals
2544
+
2545
+ Waits for the entire URL to match the expected
2546
+
2547
+ ```js
2548
+ I.waitUrlEquals('/info', 2);
2549
+ I.waitUrlEquals('http://127.0.0.1:8000/info');
2550
+ ```
2551
+
2552
+ #### Parameters
2553
+
2554
+ * `urlPart` **[string][18]** value to check.
2555
+ * `sec` **[number][23]** (optional, `1` by default) time in seconds to wait
2556
+
2557
+ Returns **void** automatically synchronized promise through #recorder
2558
+
2559
+ [1]: http://webdriver.io/
2560
+
2561
+ [2]: https://webdriver.io/blog/2023/07/31/driver-management/
2562
+
2563
+ [3]: https://codecept.io/webdriver/#testing-with-webdriver
2564
+
2565
+ [4]: http://webdriver.io/guide/getstarted/configuration.html
2566
+
2567
+ [5]: https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/IE/Options.html
2568
+
2569
+ [6]: https://aerokube.com/selenoid/latest/
2570
+
2571
+ [7]: https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities
2572
+
2573
+ [8]: http://webdriver.io/guide/usage/cloudservices.html
2574
+
2575
+ [9]: https://webdriver.io/docs/sauce-service.html
2576
+
2577
+ [10]: https://github.com/puneet0191/codeceptjs-saucehelper/
2578
+
2579
+ [11]: https://webdriver.io/docs/browserstack-service.html
2580
+
2581
+ [12]: https://github.com/PeterNgTr/codeceptjs-bshelper
2582
+
2583
+ [13]: https://github.com/testingbot/codeceptjs-tbhelper
2584
+
2585
+ [14]: https://webdriver.io/docs/testingbot-service.html
2586
+
2587
+ [15]: https://github.com/PeterNgTr/codeceptjs-applitoolshelper
2588
+
2589
+ [16]: http://webdriver.io/guide/usage/multiremote.html
2590
+
2591
+ [17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
2592
+
2593
+ [18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
2594
+
2595
+ [19]: http://jster.net/category/windows-modals-popups
2596
+
2597
+ [20]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
2598
+
2599
+ [21]: https://playwright.dev/docs/api/class-locator#locator-blur
2600
+
2601
+ [22]: /locators#aria-locators
2602
+
2603
+ [23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
2604
+
2605
+ [24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
2606
+
2607
+ [25]: https://webdriver.io/docs/timeouts.html
2608
+
2609
+ [26]: https://vuejs.org/v2/api/#Vue-nextTick
2610
+
2611
+ [27]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
2612
+
2613
+ [28]: http://webdriver.io/api/protocol/execute.html
2614
+
2615
+ [29]: https://playwright.dev/docs/api/class-locator#locator-focus
2616
+
2617
+ [30]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
2618
+
2619
+ [31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
2620
+
2621
+ [32]: #fillfield
2622
+
2623
+ [33]: #click
2624
+
2625
+ [34]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
2626
+
2627
+ [35]: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
2628
+
2629
+ [36]: https://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object
2630
+
2631
+ [37]: https://webdriver.io/docs/api.html
2632
+
2633
+ [38]: https://webdriver.io/docs/api/webdriverBidi/
2634
+
2635
+ [39]: http://codecept.io/acceptance/#smartwait
2636
+
2637
+ [40]: http://webdriver.io/docs/timeouts.html
2638
+
2639
+ [41]: https://webdriver.io/docs/configuration/#loglevel