codeceptjs 2.3.4 → 2.4.1

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 (269) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +28 -6
  3. package/bin/codecept.js +42 -0
  4. package/docs/advanced.md +45 -1
  5. package/docs/angular.md +3 -3
  6. package/docs/basics.md +162 -118
  7. package/docs/bdd.md +30 -5
  8. package/docs/best.md +8 -6
  9. package/docs/books.md +6 -1
  10. package/docs/build/Appium.js +95 -85
  11. package/docs/build/FileSystem.js +48 -3
  12. package/docs/build/GraphQL.js +3 -2
  13. package/docs/build/GraphQLDataFactory.js +1 -0
  14. package/docs/build/Mochawesome.js +3 -2
  15. package/docs/build/MockRequest.js +23 -5
  16. package/docs/build/Nightmare.js +87 -128
  17. package/docs/build/Protractor.js +107 -155
  18. package/docs/build/Puppeteer.js +190 -174
  19. package/docs/build/REST.js +13 -9
  20. package/docs/build/SeleniumWebdriver.js +0 -17
  21. package/docs/build/TestCafe.js +164 -158
  22. package/docs/build/WebDriver.js +236 -211
  23. package/docs/build/WebDriverIO.js +218 -187
  24. package/docs/changelog.md +57 -1
  25. package/docs/commands.md +41 -2
  26. package/docs/community-helpers.md +12 -1
  27. package/docs/configuration.md +5 -2
  28. package/docs/continuous-integration.md +22 -0
  29. package/docs/{helpers.md → custom-helpers.md} +16 -10
  30. package/docs/data.md +7 -6
  31. package/docs/detox.md +6 -6
  32. package/docs/email.md +4 -2
  33. package/docs/examples.md +22 -3
  34. package/docs/helpers/ApiDataFactory.md +15 -13
  35. package/docs/helpers/Appium.md +1011 -468
  36. package/docs/helpers/Detox.md +33 -26
  37. package/docs/helpers/FileSystem.md +43 -13
  38. package/docs/helpers/GraphQL.md +17 -15
  39. package/docs/helpers/GraphQLDataFactory.md +15 -13
  40. package/docs/helpers/Mochawesome.md +3 -1
  41. package/docs/helpers/MockRequest.md +37 -19
  42. package/docs/helpers/Nightmare.md +129 -240
  43. package/docs/helpers/Polly.md +1 -1
  44. package/docs/helpers/Protractor.md +157 -298
  45. package/docs/helpers/Puppeteer.md +216 -335
  46. package/docs/helpers/REST.md +29 -24
  47. package/docs/helpers/TestCafe.md +137 -235
  48. package/docs/helpers/WebDriver.md +250 -347
  49. package/docs/hooks.md +14 -10
  50. package/docs/index.md +112 -0
  51. package/docs/installation.md +3 -1
  52. package/docs/locators.md +19 -8
  53. package/docs/mobile-react-native-locators.md +2 -2
  54. package/docs/mobile.md +5 -3
  55. package/docs/nightmare.md +2 -1
  56. package/docs/pageobjects.md +4 -2
  57. package/docs/parallel.md +4 -2
  58. package/docs/plugins.md +41 -15
  59. package/docs/puppeteer.md +8 -6
  60. package/docs/quickstart.md +130 -0
  61. package/docs/react.md +4 -2
  62. package/docs/reports.md +6 -4
  63. package/docs/testcafe.md +10 -8
  64. package/docs/translation.md +4 -2
  65. package/docs/ui.md +56 -0
  66. package/docs/videos.md +11 -2
  67. package/docs/visual.md +7 -5
  68. package/docs/vue.md +121 -0
  69. package/docs/webapi/appendField.mustache +1 -1
  70. package/docs/webapi/attachFile.mustache +1 -1
  71. package/docs/webapi/checkOption.mustache +2 -2
  72. package/docs/webapi/clearCookie.mustache +1 -1
  73. package/docs/webapi/click.mustache +2 -2
  74. package/docs/webapi/clickLink.mustache +2 -2
  75. package/docs/webapi/dontSee.mustache +1 -2
  76. package/docs/webapi/dontSeeCheckboxIsChecked.mustache +1 -1
  77. package/docs/webapi/dontSeeElement.mustache +1 -1
  78. package/docs/webapi/dontSeeElementInDOM.mustache +1 -1
  79. package/docs/webapi/dontSeeInField.mustache +1 -1
  80. package/docs/webapi/doubleClick.mustache +2 -2
  81. package/docs/webapi/downloadFile.mustache +1 -1
  82. package/docs/webapi/dragSlider.mustache +1 -1
  83. package/docs/webapi/executeAsyncScript.mustache +2 -1
  84. package/docs/webapi/executeScript.mustache +2 -1
  85. package/docs/webapi/fillField.mustache +1 -1
  86. package/docs/webapi/grabAttributeFrom.mustache +1 -1
  87. package/docs/webapi/grabBrowserLogs.mustache +1 -1
  88. package/docs/webapi/grabCookie.mustache +2 -2
  89. package/docs/webapi/grabCssPropertyFrom.mustache +1 -1
  90. package/docs/webapi/grabHTMLFrom.mustache +1 -1
  91. package/docs/webapi/grabNumberOfVisibleElements.mustache +1 -1
  92. package/docs/webapi/grabPageScrollPosition.mustache +1 -1
  93. package/docs/webapi/grabTextFrom.mustache +2 -2
  94. package/docs/webapi/grabValueFrom.mustache +1 -1
  95. package/docs/webapi/moveCursorTo.mustache +3 -3
  96. package/docs/webapi/pressKey.mustache +1 -1
  97. package/docs/webapi/pressKeyWithKeyNormalization.mustache +1 -1
  98. package/docs/webapi/rightClick.mustache +2 -2
  99. package/docs/webapi/saveScreenshot.mustache +1 -1
  100. package/docs/webapi/scrollIntoView.mustache +10 -0
  101. package/docs/webapi/scrollTo.mustache +3 -3
  102. package/docs/webapi/see.mustache +1 -1
  103. package/docs/webapi/seeAttributesOnElements.mustache +1 -1
  104. package/docs/webapi/seeCheckboxIsChecked.mustache +1 -1
  105. package/docs/webapi/seeCssPropertiesOnElements.mustache +1 -1
  106. package/docs/webapi/seeElement.mustache +1 -1
  107. package/docs/webapi/seeElementInDOM.mustache +1 -1
  108. package/docs/webapi/seeInField.mustache +1 -1
  109. package/docs/webapi/seeNumberOfElements.mustache +1 -1
  110. package/docs/webapi/seeNumberOfVisibleElements.mustache +1 -1
  111. package/docs/webapi/seeTextEquals.mustache +8 -0
  112. package/docs/webapi/selectOption.mustache +2 -2
  113. package/docs/webapi/switchTo.mustache +1 -1
  114. package/docs/webapi/uncheckOption.mustache +2 -2
  115. package/docs/webapi/waitForClickable.mustache +10 -0
  116. package/docs/webapi/waitForDetached.mustache +2 -2
  117. package/docs/webapi/waitForElement.mustache +2 -2
  118. package/docs/webapi/waitForEnabled.mustache +2 -2
  119. package/docs/webapi/waitForFunction.mustache +2 -2
  120. package/docs/webapi/waitForInvisible.mustache +2 -2
  121. package/docs/webapi/waitForText.mustache +2 -2
  122. package/docs/webapi/waitForValue.mustache +1 -1
  123. package/docs/webapi/waitForVisible.mustache +2 -2
  124. package/docs/webapi/waitInUrl.mustache +1 -1
  125. package/docs/webapi/waitNumberOfVisibleElements.mustache +2 -2
  126. package/docs/webapi/waitToHide.mustache +2 -2
  127. package/docs/webapi/waitUntil.mustache +3 -2
  128. package/docs/webapi/waitUrlEquals.mustache +1 -1
  129. package/docs/webdriver.md +20 -18
  130. package/docs/wiki/.git/FETCH_HEAD +1 -0
  131. package/docs/wiki/.git/HEAD +1 -0
  132. package/docs/wiki/.git/ORIG_HEAD +1 -0
  133. package/docs/wiki/.git/config +11 -0
  134. package/docs/wiki/.git/description +1 -0
  135. package/docs/wiki/.git/hooks/applypatch-msg.sample +15 -0
  136. package/docs/wiki/.git/hooks/commit-msg.sample +24 -0
  137. package/docs/wiki/.git/hooks/fsmonitor-watchman.sample +114 -0
  138. package/docs/wiki/.git/hooks/post-update.sample +8 -0
  139. package/docs/wiki/.git/hooks/pre-applypatch.sample +14 -0
  140. package/docs/wiki/.git/hooks/pre-commit.sample +49 -0
  141. package/docs/wiki/.git/hooks/pre-push.sample +53 -0
  142. package/docs/wiki/.git/hooks/pre-rebase.sample +169 -0
  143. package/docs/wiki/.git/hooks/pre-receive.sample +24 -0
  144. package/docs/wiki/.git/hooks/prepare-commit-msg.sample +42 -0
  145. package/docs/wiki/.git/hooks/update.sample +128 -0
  146. package/docs/wiki/.git/index +0 -0
  147. package/docs/wiki/.git/info/exclude +6 -0
  148. package/docs/wiki/.git/logs/HEAD +4 -0
  149. package/docs/wiki/.git/logs/refs/heads/master +4 -0
  150. package/docs/wiki/.git/logs/refs/remotes/origin/HEAD +1 -0
  151. package/docs/wiki/.git/logs/refs/remotes/origin/master +3 -0
  152. package/docs/wiki/.git/objects/00/d216b0774d15db2d0a2a0d4ce249b5251acc55 +3 -0
  153. package/docs/wiki/.git/objects/09/01d87c5241905fdfe3493cfe8f04df4a2685ea +0 -0
  154. package/docs/wiki/.git/objects/0d/bdd0c20c4deb6a8cc81dbbf32ecf8c09238983 +2 -0
  155. package/docs/wiki/.git/objects/1a/c29e4fa82422c52392f22f0f2b8d1a759535bf +0 -0
  156. package/docs/wiki/.git/objects/27/12f92898d3e8f68e229b6cda76570d6c66d781 +0 -0
  157. package/docs/wiki/.git/objects/2d/dbe22c257166b648928eeb9460ecfb71ba702d +0 -0
  158. package/docs/wiki/.git/objects/2f/c942ec3773efd2678d9ff98035c61fcded81a1 +0 -0
  159. package/docs/wiki/.git/objects/40/a2856342c67796b48911a256b764fb06888b94 +5 -0
  160. package/docs/wiki/.git/objects/47/53181844fc4dc563cf3aa5e80462243cb58d38 +0 -0
  161. package/docs/wiki/.git/objects/4e/24a95fb2e4f8ffef51f19b694451a205c06f10 +3 -0
  162. package/docs/wiki/.git/objects/73/31ebd96f3c7e08a9f63f05a25f939afa0d4de1 +0 -0
  163. package/docs/wiki/.git/objects/86/19cbb2289caa502e33fccf0ed14eecf6ba2ba0 +0 -0
  164. package/docs/wiki/.git/objects/a4/72f797d9d74b87c9f71a2b1539d75bb07d1e35 +0 -0
  165. package/docs/wiki/.git/objects/c9/9f3e4bd227d6b050b2e416f9876df49583dbf6 +0 -0
  166. package/docs/wiki/.git/objects/ca/e609b4ef3e0ef85fcbe0d68d1a58246584b915 +0 -0
  167. package/docs/wiki/.git/objects/d5/8386ca72f6d550548f3d71d74e3ac73d5ad488 +0 -0
  168. package/docs/wiki/.git/objects/d9/c6874a6de524bdafeb563a20d847f4fdd59a86 +0 -0
  169. package/docs/wiki/.git/objects/f1/c944675bb38b40ae553b0be36c14674c79af54 +0 -0
  170. package/docs/wiki/.git/objects/pack/pack-28da0fc7e6c08d4c5350717bfbb7b1c53e8198ad.idx +0 -0
  171. package/docs/wiki/.git/objects/pack/pack-28da0fc7e6c08d4c5350717bfbb7b1c53e8198ad.pack +0 -0
  172. package/docs/wiki/.git/packed-refs +2 -0
  173. package/docs/wiki/.git/refs/heads/master +1 -0
  174. package/docs/wiki/.git/refs/remotes/origin/HEAD +1 -0
  175. package/docs/wiki/.git/refs/remotes/origin/master +1 -0
  176. package/docs/wiki/Books-&-Posts.md +27 -0
  177. package/docs/wiki/Community-Helpers.md +41 -0
  178. package/docs/wiki/Examples.md +138 -0
  179. package/docs/wiki/Home.md +11 -0
  180. package/docs/wiki/Release-process.md +25 -0
  181. package/docs/wiki/Roadmap.md +23 -0
  182. package/docs/wiki/Videos.md +19 -0
  183. package/lib/actor.js +18 -1
  184. package/lib/assert/error.js +3 -3
  185. package/lib/codecept.js +9 -6
  186. package/lib/command/configMigrate.js +7 -6
  187. package/lib/command/definitions.js +98 -350
  188. package/lib/command/generate.js +22 -17
  189. package/lib/command/gherkin/init.js +2 -1
  190. package/lib/command/gherkin/snippets.js +6 -6
  191. package/lib/command/gherkin/steps.js +0 -1
  192. package/lib/command/info.js +40 -0
  193. package/lib/command/init.js +54 -41
  194. package/lib/command/run-multiple.js +5 -4
  195. package/lib/command/run-rerun.js +39 -0
  196. package/lib/command/run-workers.js +4 -6
  197. package/lib/command/run.js +8 -18
  198. package/lib/command/utils.js +23 -2
  199. package/lib/command/workers/runTests.js +1 -2
  200. package/lib/config.js +10 -4
  201. package/lib/container.js +31 -6
  202. package/lib/data/dataTableArgument.js +31 -0
  203. package/lib/data/table.js +4 -0
  204. package/lib/event.js +65 -1
  205. package/lib/helper/Appium.js +52 -38
  206. package/lib/helper/FileSystem.js +48 -3
  207. package/lib/helper/GraphQL.js +3 -2
  208. package/lib/helper/GraphQLDataFactory.js +1 -0
  209. package/lib/helper/Mochawesome.js +3 -2
  210. package/lib/helper/MockRequest.js +23 -5
  211. package/lib/helper/Nightmare.js +5 -6
  212. package/lib/helper/Protractor.js +7 -8
  213. package/lib/helper/Puppeteer.js +76 -20
  214. package/lib/helper/REST.js +13 -9
  215. package/lib/helper/SeleniumWebdriver.js +0 -17
  216. package/lib/helper/TestCafe.js +84 -36
  217. package/lib/helper/WebDriver.js +113 -59
  218. package/lib/helper/WebDriverIO.js +43 -59
  219. package/lib/helper/clientscripts/nightmare.js +66 -4
  220. package/lib/helper/scripts/isElementClickable.js +24 -0
  221. package/lib/helper.js +34 -10
  222. package/lib/history.js +1 -1
  223. package/lib/hooks.js +2 -1
  224. package/lib/index.js +19 -0
  225. package/lib/interfaces/bdd.js +4 -0
  226. package/lib/interfaces/featureConfig.js +10 -3
  227. package/lib/interfaces/gherkin.js +6 -2
  228. package/lib/interfaces/scenarioConfig.js +17 -6
  229. package/lib/listener/config.js +1 -1
  230. package/lib/listener/exit.js +6 -0
  231. package/lib/listener/steps.js +0 -1
  232. package/lib/listener/trace.js +0 -1
  233. package/lib/locator.js +67 -2
  234. package/lib/output.js +53 -0
  235. package/lib/parser.js +2 -71
  236. package/lib/pause.js +3 -2
  237. package/lib/plugin/allure.js +41 -22
  238. package/lib/plugin/autoLogin.js +4 -1
  239. package/lib/plugin/pauseOnFail.js +38 -0
  240. package/lib/plugin/puppeteerCoverage.js +8 -7
  241. package/lib/plugin/screenshotOnFail.js +13 -8
  242. package/lib/plugin/stepByStepReport.js +7 -6
  243. package/lib/plugin/wdio.js +2 -1
  244. package/lib/recorder.js +85 -7
  245. package/lib/rerun.js +81 -0
  246. package/lib/secret.js +6 -0
  247. package/lib/session.js +9 -2
  248. package/lib/step.js +37 -2
  249. package/lib/store.js +5 -1
  250. package/lib/ui.js +34 -8
  251. package/lib/utils.js +6 -13
  252. package/lib/within.js +5 -0
  253. package/package.json +49 -29
  254. package/typings/Mocha.d.ts +21 -0
  255. package/typings/Protractor.d.ts +16 -0
  256. package/typings/index.d.ts +169 -0
  257. package/typings/jsdoc.conf.js +34 -0
  258. package/typings/jsdoc.namespace.js +29 -0
  259. package/typings/types.d.ts +9827 -0
  260. package/typings/utils.d.ts +7 -0
  261. package/docs/acceptance.md +0 -409
  262. package/docs/api/codecept.md +0 -75
  263. package/docs/api/config.md +0 -49
  264. package/docs/api/container.md +0 -66
  265. package/docs/api/helper.md +0 -116
  266. package/docs/api/output.md +0 -67
  267. package/docs/api/recorder.md +0 -63
  268. package/docs/helpers/SeleniumWebdriver.md +0 -92
  269. package/docs/helpers/WebDriverIO.md +0 -1671
package/docs/hooks.md CHANGED
@@ -1,8 +1,9 @@
1
1
  ---
2
- id: hooks
2
+ permalink: /hooks
3
3
  title: Bootstrap / Teardown / Plugins
4
4
  ---
5
5
 
6
+ # Bootstrap / Teardown / Plugins
6
7
 
7
8
  CodeceptJS provides API to run custom code before and after the test and inject custom listeners into the event system.
8
9
 
@@ -131,7 +132,7 @@ First, `bootstrapAll` is called. Then two `bootstrap` runs in each of workers. T
131
132
 
132
133
  The `bootstrapAll` and `teardownAll` hooks are preferred to use for setting up common logic of tested project: to start application server or database, to start webdriver's grid.
133
134
 
134
- The `bootstrap` and `teardown` hooks are used for setting up each testing browser: to create unique [cloud testing server](https://codecept.io/helpers/WebDriverIO#cloud-providers) connection or to create specific browser-related test data in database (like users with names with browsername in it).
135
+ The `bootstrap` and `teardown` hooks are used for setting up each testing browser: to create unique [cloud testing server](/helpers/WebDriverIO#cloud-providers) connection or to create specific browser-related test data in database (like users with names with browsername in it).
135
136
 
136
137
  Same as `bootstrap` and `teardown`, there are 3 ways to define `bootstrapAll` and `teardownAll` functions:
137
138
 
@@ -239,7 +240,7 @@ module.exports = {
239
240
 
240
241
  Plugins allow to use CodeceptJS internal API to extend functionality. Use internal event dispatcher, container, output, promise recorder, to create your own reporters, test listeners, etc.
241
242
 
242
- CodeceptJS includes [built-in plugins](https://codecept.io/plugins/) which extend basic functionality and can be turned on and off on purpose. Taking them as [examples](https://github.com/Codeception/CodeceptJS/tree/master/lib/plugin) you can develop your custom plugins.
243
+ CodeceptJS includes [built-in plugins](/plugins/) which extend basic functionality and can be turned on and off on purpose. Taking them as [examples](https://github.com/Codeception/CodeceptJS/tree/master/lib/plugin) you can develop your custom plugins.
243
244
 
244
245
  A plugin is a basic JS module returning a function. Plugins can have individual configs which are passed into this function:
245
246
 
@@ -284,7 +285,7 @@ Several plugins can be enabled as well:
284
285
 
285
286
  ### Example: Execute code for a specific group of tests
286
287
 
287
- If you need to execute some code before a group of tests, you can [mark these tests with a same tag](https://codecept.io/advanced/#tags). Then to listen for tests where this tag is included (see [test object api](#test-object)).
288
+ If you need to execute some code before a group of tests, you can [mark these tests with a same tag](/advanced/#tags). Then to listen for tests where this tag is included (see [test object api](#test-object)).
288
289
 
289
290
  Let's say we need to populate database for a group of tests.
290
291
 
@@ -399,7 +400,9 @@ Test events provide a test object with following fields:
399
400
  * `tags` array of tags for this test
400
401
  * `file` path to a file with a test.
401
402
  * `steps` array of executed steps (available only in `test.passed`, `test.failed`, `test.finished` event)
402
-
403
+ * `skipInfo` additional test options when test skipped
404
+ * * `message` string with reason for skip
405
+ * * `description` string with test body
403
406
  and others
404
407
 
405
408
  #### Step Object
@@ -530,18 +533,19 @@ if (config.myKey == 'value') {
530
533
 
531
534
  ## Custom Runner
532
535
 
536
+ > 📺 [Watch this](https://www.youtube.com/watch?v=3eZtVL0Ad0A) material on YouTube
537
+
533
538
  CodeceptJS can be imported and used in custom runners.
534
539
  To initialize Codecept you need to create Config and Container objects.
535
540
 
536
541
  ```js
537
- let Container = require('codeceptjs').container;
538
- let Codecept = require('codeceptjs').codecept;
542
+ const { container: Container, codecept: Codecept } = require('codeceptjs').container;
539
543
 
540
- let config = { helpers: { WebDriver: { browser: 'chrome', url: 'http://localhost' } } };
541
- let opts = { steps: true };
544
+ const config = { helpers: { WebDriver: { browser: 'chrome', url: 'http://localhost' } } };
545
+ const opts = { steps: true };
542
546
 
543
547
  // create runner
544
- let codecept = new Codecept(config, opts);
548
+ const codecept = new Codecept(config, opts);
545
549
 
546
550
  // initialize codeceptjs in current dir
547
551
  codecept.initGlobals(__dirname);
package/docs/index.md CHANGED
@@ -0,0 +1,112 @@
1
+ ---
2
+ layout: Landing
3
+ sidebar: false
4
+ actionText: Quickstart
5
+ actionLink: /quickstart
6
+ ---
7
+
8
+ ::: slot pause
9
+ ## Write a Test with Interactive Pause
10
+
11
+ Open a browser on an empty page and pause execution.
12
+ Type in commands to complete the test scenario.
13
+
14
+ Successful commands will be saved into a file.
15
+
16
+ ```js
17
+ Scenario('Checkout test', () => {
18
+ I.amOnPage('/checkout');
19
+ pause();
20
+ })
21
+ ```
22
+ Copy commands from a file into a test. A test is ready!
23
+ :::
24
+
25
+ ::: slot write
26
+ ## Write Tests from UI
27
+
28
+ With CodeceptUI you can write your tests without closing a browser at all.
29
+
30
+ Write initial commands and execute a test. An interactive pause will be started when test finishes.
31
+
32
+ Share one browser accross test runs to save time on opening a browser.
33
+ :::
34
+
35
+
36
+ ::: slot autocomplete
37
+ ## Powered with IntelliSense
38
+
39
+ Use auto-completion writing a test fast.
40
+
41
+ We use TypeScript type definitions that are automatically updated for custom steps and page objects.
42
+
43
+ Writing a test in Visual Studio Code is as easy as picking a correct action and putting a parameter. It's really that nice!
44
+
45
+ :::
46
+
47
+
48
+ ::: slot ui
49
+
50
+ ## Watch & Run Tests from UI
51
+
52
+ We have a flexible interactive web runner which allows you to watch, debug, and write your tests in a web mode.
53
+
54
+ Features:
55
+
56
+ * Toggle headless/window mode with one click
57
+ * See HTML snapshot of each step
58
+ * Works with WebDriver, Puppeteer, TestCafe
59
+ * Shows step-by-step execution
60
+ * Integrated with your local IDE
61
+
62
+ :::
63
+
64
+
65
+ ::: slot run
66
+
67
+ ## Print a Test
68
+
69
+ Each executed step will be printed on screen when running with `--steps`
70
+ ```js
71
+ Scenario('Checkout test', () => {
72
+ I.amOnPage('/checkout');
73
+ I.fillField('First name', 'davert');
74
+ I.fillField('#lastName', 'mik');
75
+ I.fillField('Promo code', '123345')
76
+ //...
77
+ })
78
+ ```
79
+
80
+ :::
81
+
82
+ ::: slot code
83
+
84
+ ## Realworld Example
85
+
86
+ Can we use it for long scenarios? Sure!
87
+
88
+ ```js
89
+ const faker = require('faker'); // Use 3rd-party JS code
90
+
91
+ Feature('Store');
92
+
93
+ Scenario('Create a new store', async (I, login, SettingsPage) => {
94
+ const storeName = faker.lorem.slug();
95
+ login('customer'); // Login customer from saved cookies
96
+ I.mockRequest('GET', '/support-chat'); // Mock HTTP requests with Polly
97
+ SettingsPage.open(); // Use Page objects
98
+ I.dontSee(storeName, '.settings'); // Assert text not present inside an element (located by CSS)
99
+ I.click('Add', '.settings'); // Click link by text inside element (located by CSS)
100
+ I.fillField('Store Name', storeName); // Fill fields by labels or placeholders
101
+ I.fillField('Email', faker.internet.email());
102
+ I.fillField('Telephone', faker.phone.phoneNumberFormat());
103
+ I.selectInDropdown('Status', 'Active'); // Use custom methods
104
+ I.retry(2).click('Create'); // Auto-retry flaky step
105
+ I.waitInUrl('/settings/setup/stores'); // Explicit waiter
106
+ I.see(storeName, '.settings'); // Assert text present inside an element (located by CSS)
107
+ const storeId = await I.grabTextFrom('#store-id'); // use await to get information from browser
108
+ I.say(`Created a store with ${storeId}`); // print custom comments
109
+ }).tag('stores');`;
110
+
111
+ ```
112
+ :::
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: installation
2
+ permalink: /installation
3
3
  title: Installation
4
4
  ---
5
5
 
6
+ # Installation
7
+
6
8
  ## Local
7
9
 
8
10
  Use NPM install CodeceptJS:
package/docs/locators.md CHANGED
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: locators
2
+ permalink: /locators
3
3
  title: Locators
4
4
  ---
5
5
 
6
+ # Locators
7
+
6
8
  CodeceptJS provides flexible strategies for locating elements:
7
9
 
8
10
  * [CSS and XPath locators](#css-and-xpath)
@@ -13,11 +15,11 @@ CodeceptJS provides flexible strategies for locating elements:
13
15
 
14
16
  Most methods in CodeceptJS use locators which can be either a string or an object.
15
17
 
16
- If the locator is an object, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator.
18
+ If the locator is an object, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, `react`, or `class`) and the value being the locator itself. This is called a "strict" locator.
17
19
 
18
20
  Examples:
19
21
 
20
- * {id: 'foo'} matches `<div id="foo">`
22
+ * {permalink: /'foo'} matches `<div id="foo">`
21
23
  * {name: 'foo'} matches `<div name="foo">`
22
24
  * {css: 'input[type=input][value=foo]'} matches `<input type="input" value="foo">`
23
25
  * {xpath: "//input[@type='submit'][contains(@value, 'foo')]"} matches `<input type="submit" value="foobar">`
@@ -38,8 +40,17 @@ For example, here's the heuristic used for the `fillField` method:
38
40
  5. If nothing found, check if there is a label with specified text for input element.
39
41
  6. If nothing found, throw an `ElementNotFound` exception.
40
42
 
41
- Be warned that fuzzy locators can be significantly slower than strict locators.
42
- If speed is a concern, it's recommended you stick with explicitly specifying the locator type via object syntax.
43
+ > ⚠ Be warned that fuzzy locators can be significantly slower than strict locators. If speed is a concern, it's recommended you stick with explicitly specifying the locator type via object syntax.
44
+
45
+ It is recommended to avoid using implicit CSS locators in methods like `fillField` or `click`, where semantic locators are allowed.
46
+ Use locator type to speed up search by various locator strategies.
47
+
48
+ ```js
49
+ // will search for "input[type=password]" text before trying to search by CSS
50
+ I.fillField('input[type=password]', '123456');
51
+ // replace with strict locator
52
+ I.fillField({ css: 'input[type=password]' }, '123456');
53
+ ```
43
54
 
44
55
  ## CSS and XPath
45
56
 
@@ -216,7 +227,7 @@ locate('button').after('.btn-cancel');
216
227
 
217
228
  ID locators are best to select the exact semantic element in web and mobile testing:
218
229
 
219
- * `#user` or `{ id: 'user' }` finds element with id="user"
230
+ * `#user` or `{ permalink: /'user' }` finds element with id="user"
220
231
  * `~user` finds element with accessibility id "user" (in Mobile testing) or with `aria-label=user`.
221
232
 
222
233
  ## Custom Locators
@@ -224,7 +235,7 @@ ID locators are best to select the exact semantic element in web and mobile test
224
235
  CodeceptJS allows to create custom locator strategies and use them in tests. This way you can define your own handling of elements using specially prepared attributes of elements.
225
236
 
226
237
  What if you use special test attributes for locators such as `data-qa`, `data-test`, `test-id`, etc.
227
- We created [customLocator plugin](https://codecept.io/plugins#customlocator) to declare rules for locating element.
238
+ We created [customLocator plugin](/plugins#customlocator) to declare rules for locating element.
228
239
 
229
240
  Instead of writing a full CSS locator like `[data-qa-id=user_name]` simplify it to `$user_name`.
230
241
 
@@ -237,7 +248,7 @@ I.click('$register_button');
237
248
 
238
249
  This plugin requires two options: locator prefix and actual attribute to match.
239
250
 
240
- > ℹ See [customLocator Plugin](https://codecept.io/plugins#customlocator) reference to learn how to set it up.
251
+ > ℹ See [customLocator Plugin](/plugins#customlocator) reference to learn how to set it up.
241
252
 
242
253
  If you need more control over custom locators see how declare them manually without using a customLocator plugin.
243
254
 
@@ -46,14 +46,14 @@ You could do it just by changing `automationName` in the `helpers` section of th
46
46
  ```
47
47
  Then you could locate components using XPath expression:
48
48
  ```js
49
- I.tap({android: '//*[@view-tag="someButton"]', ios: '~someButton'})
49
+ I.tap({andropermalink: /'//*[@view-tag="someButton"]', ios: '~someButton'})
50
50
  ```
51
51
  This way test would work for both platforms without any changes in code.
52
52
  To simplify things further you could write a helper function:
53
53
  ```js
54
54
  function tid(id) {
55
55
  return {
56
- android: `//*[@view-tag="${id}"]`,
56
+ andropermalink: /`//*[@view-tag="${id}"]`,
57
57
  ios: '~' + id
58
58
  }
59
59
  }
package/docs/mobile.md CHANGED
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: mobile
2
+ permalink: /mobile
3
3
  title: Mobile Testing with Appium
4
4
  ---
5
5
 
6
+ # Mobile Testing with Appium
7
+
6
8
  CodeceptJS allows to test mobile and hybrid apps in a similar manner web applications are tested.
7
9
  Such tests are executed using [Appium](http://appium.io) on emulated or physical devices. Also, Appium allows to test web application on mobile devices.
8
10
 
@@ -17,7 +19,7 @@ I.see('davert@codecept.io', '~email of the customer'));
17
19
  I.clearField('~email of the customer'));
18
20
  I.dontSee('Nothing special', '~email of the customer'));
19
21
  I.seeElement({
20
- android: 'android.widget.Button',
22
+ andropermalink: /'android.widget.Button',
21
23
  ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'
22
24
  });
23
25
  ```
@@ -260,7 +262,7 @@ It is often happen that mobile applications behave similarly on different platfo
260
262
  CodeceptJS provides a way to specify different locators for Android and iOS platforms:
261
263
 
262
264
  ```js
263
- I.click({android: '//android.widget.Button', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});
265
+ I.click({andropermalink: /'//android.widget.Button', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});
264
266
  ```
265
267
 
266
268
  In case some code should be executed on one platform and ignored on others use `runOnAndroid` and `runOnIOS` methods:
package/docs/nightmare.md CHANGED
@@ -1,8 +1,9 @@
1
1
  ---
2
- id: nightmare
2
+ permalink: /nightmare
3
3
  title: Testing with Nightmare
4
4
  ---
5
5
 
6
+ # Testing with Nightmare
6
7
 
7
8
  Selenium WebDriver is considered to be standard for end to end testing of web applications.
8
9
  Despite its popularity it have its drawbacks, it requires a real browser and Selenium server to control it.
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: pageobjects
2
+ permalink: /pageobjects
3
3
  title: Page Objects
4
4
  ---
5
5
 
6
+ # Page Objects
7
+
6
8
  UI of your web application has interaction areas which can be shared across different tests.
7
9
  To avoid code duplication you can put common locators and methods into one place.
8
10
 
@@ -185,8 +187,8 @@ class AttachFile {
185
187
  }
186
188
 
187
189
  // For inheritance
188
- exports.AttachFile = AttachFile
189
190
  module.exports = new AttachFile();
191
+ module.exports.AttachFile = AttachFile;
190
192
  ```
191
193
 
192
194
  ## Page Fragments
package/docs/parallel.md CHANGED
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: parallel
2
+ permalink: /parallel
3
3
  title: Parallel Execution
4
4
  ---
5
5
 
6
+ # Parallel Execution
7
+
6
8
  CodeceptJS has two engines for running tests in parallel:
7
9
 
8
10
  * `run-workers` - which spawns [NodeJS Worker](https://nodejs.org/api/worker_threads.html) in a thread. Tests are split by scenarios, scenarios are mixed between groups, each worker runs tests from its own group.
@@ -134,7 +136,7 @@ Output is printed for all running processes. Each line is tagged with a suite an
134
136
 
135
137
  ### Hooks
136
138
 
137
- Hooks are available when using the `run-multiple` command to perform actions before the test suites start and after the test suites have finished. See [Hooks](https://codecept.io/hooks/#bootstrap-teardown) for an example.
139
+ Hooks are available when using the `run-multiple` command to perform actions before the test suites start and after the test suites have finished. See [Hooks](/hooks/#bootstrap-teardown) for an example.
138
140
 
139
141
 
140
142
  ### Parallel Execution
package/docs/plugins.md CHANGED
@@ -1,5 +1,7 @@
1
1
  ---
2
- id: plugins
2
+ permalink: plugins
3
+ sidebarDepth:
4
+ sidebar: auto
3
5
  title: Plugins
4
6
  ---
5
7
 
@@ -372,6 +374,28 @@ I.click('=sign-up'); // matches => [data-qa=sign-up]
372
374
 
373
375
  - `config`
374
376
 
377
+ ## pauseOnFail
378
+
379
+ Automatically launches [interactive pause][4] when a test fails.
380
+
381
+ Useful for debugging flaky tests on local environment.
382
+ Add this plugin to config file:
383
+
384
+ ```js
385
+ plugins: {
386
+ pauseOnFail: {},
387
+ }
388
+ ```
389
+
390
+ Unlike other plugins, `pauseOnFail` is not recommended to be enabled by default.
391
+ Enable it manually on each run via `-p` option:
392
+
393
+ npx codeceptjs run -p pauseOnFail
394
+
395
+ ### Parameters
396
+
397
+ - `config`
398
+
375
399
  ## puppeteerCoverage
376
400
 
377
401
  Dumps puppeteers code coverage after every test.
@@ -403,9 +427,9 @@ Possible config options:
403
427
 
404
428
  Links:
405
429
 
406
- - [https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage][4]
407
- - [https://github.com/istanbuljs/puppeteer-to-istanbul][5]
408
- - [https://github.com/gotwarlost/istanbul][6]
430
+ - [https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage][5]
431
+ - [https://github.com/istanbuljs/puppeteer-to-istanbul][6]
432
+ - [https://github.com/gotwarlost/istanbul][7]
409
433
 
410
434
  ### Parameters
411
435
 
@@ -509,7 +533,7 @@ Possible config options:
509
533
 
510
534
  ## stepByStepReport
511
535
 
512
- ![step-by-step-report][7]
536
+ ![step-by-step-report][8]
513
537
 
514
538
  Generates step by step report for a test.
515
539
  After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
@@ -554,7 +578,7 @@ This plugin allows to run webdriverio services like:
554
578
  - browserstack
555
579
  - appium
556
580
 
557
- A complete list of all available services can be found on [webdriverio website][8].
581
+ A complete list of all available services can be found on [webdriverio website][9].
558
582
 
559
583
  ###### Setup
560
584
 
@@ -566,7 +590,7 @@ See examples below:
566
590
 
567
591
  ###### Selenium Standalone Service
568
592
 
569
- Install `@wdio/selenium-standalone-service` package, as [described here][9].
593
+ Install `@wdio/selenium-standalone-service` package, as [described here][10].
570
594
  It is important to make sure it is compatible with current webdriverio version.
571
595
 
572
596
  Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -585,7 +609,7 @@ Please note, this service can be used with Protractor helper as well!
585
609
 
586
610
  ##### Sauce Service
587
611
 
588
- Install `@wdio/sauce-service` package, as [described here][10].
612
+ Install `@wdio/sauce-service` package, as [described here][11].
589
613
  It is important to make sure it is compatible with current webdriverio version.
590
614
 
591
615
  Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -621,16 +645,18 @@ In the same manner additional services from webdriverio can be installed, enable
621
645
 
622
646
  [3]: https://codecept.io/locators#custom-locators
623
647
 
624
- [4]: https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage
648
+ [4]: /basics/#pause
649
+
650
+ [5]: https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage
625
651
 
626
- [5]: https://github.com/istanbuljs/puppeteer-to-istanbul
652
+ [6]: https://github.com/istanbuljs/puppeteer-to-istanbul
627
653
 
628
- [6]: https://github.com/gotwarlost/istanbul
654
+ [7]: https://github.com/gotwarlost/istanbul
629
655
 
630
- [7]: https://codecept.io/img/codeceptjs-slideshow.gif
656
+ [8]: https://codecept.io/img/codeceptjs-slideshow.gif
631
657
 
632
- [8]: https://webdriver.io
658
+ [9]: https://webdriver.io
633
659
 
634
- [9]: https://webdriver.io/docs/selenium-standalone-service.html
660
+ [10]: https://webdriver.io/docs/selenium-standalone-service.html
635
661
 
636
- [10]: https://webdriver.io/docs/sauce-service.html
662
+ [11]: https://webdriver.io/docs/sauce-service.html
package/docs/puppeteer.md CHANGED
@@ -1,8 +1,10 @@
1
1
  ---
2
- id: puppeteer
2
+ permalink: /puppeteer
3
3
  title: Testing with Puppeteer
4
4
  ---
5
5
 
6
+ # Testing with Puppeteer
7
+
6
8
  Among all Selenium alternatives the most interesting emerging ones are tools developed around Google Chrome [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). And the most prominent one is [Puppeteer](https://github.com/GoogleChrome/puppeteer). It operates over Google Chrome directly without requiring additional tools like ChromeDriver. So tests setup with Puppeteer can be started with npm install only. If you want get faster and simpler to setup tests, Puppeteer would be your choice.
7
9
 
8
10
  CodeceptJS uses Puppeteer to improve end to end testing experience. No need to learn the syntax of a new tool, all drivers in CodeceptJS share the same API.
@@ -41,7 +43,7 @@ npx codeceptjs init
41
43
 
42
44
  You will be asked for a Helper to use, you should select Puppeteer and provide url of a website you are testing.
43
45
 
44
- > Puppeteer can also work with Firefox. [Learn how to set it up](https://codecept.io/helpers/Puppeteer-firefox)
46
+ > Puppeteer can also work with Firefox. [Learn how to set it up](/helpers/Puppeteer-firefox)
45
47
 
46
48
  ## Configuring
47
49
 
@@ -127,7 +129,7 @@ I.seeElement({xpath: '//body/header'});
127
129
 
128
130
  ### Interactive Pause
129
131
 
130
- It's easy to start writing a test if you use [interactive pause](https://codecept.io/basics#debug). Just open a web page and pause execution.
132
+ It's easy to start writing a test if you use [interactive pause](/basics#debug). Just open a web page and pause execution.
131
133
 
132
134
  ```js
133
135
  Feature('Sample Test');
@@ -191,7 +193,7 @@ within('.todoapp', () => {
191
193
  I.see('0 items left', '.todo-count');
192
194
  ```
193
195
 
194
- > [▶ Learn more about basic commands](https://codecept.io/basics#writing-tests)
196
+ > [▶ Learn more about basic commands](/basics#writing-tests)
195
197
 
196
198
  CodeceptJS allows you to implement custom actions like `I.createTodo` or use **PageObjects**. Learn how to improve your tests in [PageObjects](http://codecept.io/pageobjects/) guide.
197
199
 
@@ -204,7 +206,7 @@ When you run tests with Puppeteer you can control those requests by mocking them
204
206
 
205
207
  Also you can replace real request with a one explicitly defined. This is useful when you want to isolate application testing from a backend. For instance, if you don't want to save data to database, and you know the request which performs save, you can mock the request, so application will treat this as valid response, but no data will be actually saved.
206
208
 
207
- To mock requests enable additional helper [MockRequest](https://codecept.io/helpers/MockRequest) (which is based on Polly.js).
209
+ To mock requests enable additional helper [MockRequest](/helpers/MockRequest) (which is based on Polly.js).
208
210
 
209
211
  ```js
210
212
  helpers: {
@@ -234,7 +236,7 @@ I.mockRequest('POST', '/api/users', { user: 'davert' });
234
236
  I.mockRequest('GET', '/api/users/1', 404, { error: 'User not found' });
235
237
  ```
236
238
 
237
- > See [`mockRequest` API](https://codecept.io/helpers/MockRequest#mockrequest)
239
+ > See [`mockRequest` API](/helpers/MockRequest#mockrequest)
238
240
 
239
241
  To see `mockRequest` method in intellisense auto completion don't forget to run `codeceptjs def` command:
240
242
 
@@ -0,0 +1,130 @@
1
+ ---
2
+ permalink: quickstart
3
+ title: Quickstart
4
+ layout: Section
5
+ sidebar: true
6
+ ---
7
+
8
+ ::: slot sidebar
9
+
10
+ #### Use WebDriver for classical Selenium setup
11
+
12
+ <small>
13
+ This gives you access to rich Selenium ecosystem and cross-browser support for majority of browsers and devices.
14
+ </small>
15
+
16
+
17
+ <a href="/webdriver" class="button extended" >Start with WebDriver &raquo;</a>
18
+
19
+ <small>
20
+
21
+ WebDriver support is implemented via [webdriverio](https://webdriver.io) library
22
+
23
+ </small>
24
+
25
+ ---
26
+
27
+ #### Use TestCafe for cross-browser testing without Selenium
28
+
29
+ <small>
30
+ TestCafe provides cross-browser support without Selenium. TestCafe tests are faster, require no extra tooling and faster than regular Selenium. However, can be less stable.
31
+ </small>
32
+
33
+ <a href="/testcafe" class="button green extended" >Start with TestCafe &raquo;</a>
34
+
35
+ ---
36
+
37
+ * [Mobile Testing with Appium »](/mobile)
38
+ * [Testing with Protractor »](/angular)
39
+ * [Testing with NigthmareJS »](/nightmare)
40
+
41
+ :::
42
+
43
+ # Quickstart
44
+
45
+ > Puppeteer is a great way to start if you need fast end 2 end tests in Chrome browser. No Selenium required!
46
+
47
+ If you need cross-browser support check alternative installations with WebDriver or TestCafe &rarr;
48
+
49
+ <video onclick="this.paused ? this.play() : this.pause();" src="/img/install.mp4" style="width: 100%" controls></video>
50
+
51
+ If you start with empty project initialize npm first:
52
+
53
+ ```
54
+ npm init -y
55
+ ```
56
+
57
+ 1) Install CodeceptJS with Puppeteer
58
+
59
+ ```
60
+ npm install codeceptjs puppeteer --save-dev
61
+ ```
62
+
63
+
64
+ 2) Initialize CodeceptJS in current directory by running:
65
+
66
+ ```
67
+ npx codeceptjs init
68
+ ```
69
+
70
+ (use `node node_modules/.bin/codeceptjs` if you have issues with npx)
71
+
72
+ 3) Answer questions. Agree on defaults, when asked to select helpers choose **Puppeteer**.
73
+
74
+ ```
75
+ ? What helpers do you want to use?
76
+ ◯ WebDriver
77
+ ◯ Protractor
78
+ ❯◉ Puppeteer
79
+ ◯ Appium
80
+ ◯ Nightmare
81
+ ◯ FileSystem
82
+ ```
83
+
84
+ 4) Create First Test.
85
+
86
+ ```
87
+ npx codeceptjs gt
88
+ ```
89
+
90
+ 5) Enter a test name. Open a generated file in your favorite JavaScript editor.
91
+
92
+ ```js
93
+ Feature('My First Test');
94
+
95
+ Scenario('test something', (I) => {
96
+
97
+ });
98
+ ```
99
+
100
+ 6) Write a simple scenario
101
+
102
+ ```js
103
+ Feature('My First Test');
104
+
105
+ Scenario('test something', (I) => {
106
+ I.amOnPage('https://github.com');
107
+ I.see('GitHub');
108
+ });
109
+ ```
110
+
111
+ 7) Run a test:
112
+
113
+ ```
114
+ npx codeceptjs run --steps
115
+ ```
116
+
117
+ The output should be similar to this:
118
+
119
+ ```bash
120
+ My First Test --
121
+ test something
122
+ I am on page "https://github.com"
123
+ I see "GitHub"
124
+ ✓ OK
125
+ ```
126
+
127
+ > [▶ Next: CodeceptJS Basics](/basics/)
128
+
129
+ > [▶ Next: CodeceptJS with Puppeteer](/puppeteer/)
130
+