codeceptjs 3.5.10 → 3.5.12-beta.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 (225) hide show
  1. package/README.md +3 -3
  2. package/lib/command/run-multiple.js +3 -1
  3. package/lib/command/run-workers.js +32 -1
  4. package/lib/command/workers/runTests.js +18 -2
  5. package/lib/helper/Expect.js +33 -33
  6. package/lib/helper/Playwright.js +49 -26
  7. package/lib/helper/Puppeteer.js +41 -19
  8. package/lib/helper/WebDriver.js +155 -48
  9. package/lib/helper/extras/PlaywrightReactVueLocator.js +38 -0
  10. package/lib/locator.js +17 -4
  11. package/lib/plugin/retryFailedStep.js +6 -2
  12. package/lib/plugin/retryTo.js +2 -2
  13. package/lib/plugin/tryTo.js +5 -4
  14. package/package.json +25 -22
  15. package/typings/index.d.ts +8 -5
  16. package/typings/promiseBasedTypes.d.ts +203 -75
  17. package/typings/types.d.ts +213 -145
  18. package/docs/advanced.md +0 -351
  19. package/docs/ai.md +0 -248
  20. package/docs/api.md +0 -323
  21. package/docs/basics.md +0 -979
  22. package/docs/bdd.md +0 -539
  23. package/docs/best.md +0 -237
  24. package/docs/books.md +0 -37
  25. package/docs/bootstrap.md +0 -135
  26. package/docs/build/ApiDataFactory.js +0 -410
  27. package/docs/build/Appium.js +0 -2027
  28. package/docs/build/Expect.js +0 -422
  29. package/docs/build/FileSystem.js +0 -228
  30. package/docs/build/GraphQL.js +0 -229
  31. package/docs/build/GraphQLDataFactory.js +0 -309
  32. package/docs/build/JSONResponse.js +0 -338
  33. package/docs/build/Mochawesome.js +0 -71
  34. package/docs/build/Nightmare.js +0 -2152
  35. package/docs/build/OpenAI.js +0 -126
  36. package/docs/build/Playwright.js +0 -5078
  37. package/docs/build/Protractor.js +0 -2706
  38. package/docs/build/Puppeteer.js +0 -3874
  39. package/docs/build/REST.js +0 -344
  40. package/docs/build/TestCafe.js +0 -2125
  41. package/docs/build/WebDriver.js +0 -4124
  42. package/docs/changelog.md +0 -2572
  43. package/docs/commands.md +0 -266
  44. package/docs/community-helpers.md +0 -58
  45. package/docs/configuration.md +0 -157
  46. package/docs/continuous-integration.md +0 -22
  47. package/docs/custom-helpers.md +0 -306
  48. package/docs/data.md +0 -379
  49. package/docs/detox.md +0 -235
  50. package/docs/docker.md +0 -136
  51. package/docs/email.md +0 -183
  52. package/docs/examples.md +0 -149
  53. package/docs/helpers/ApiDataFactory.md +0 -266
  54. package/docs/helpers/Appium.md +0 -1374
  55. package/docs/helpers/Detox.md +0 -586
  56. package/docs/helpers/Expect.md +0 -275
  57. package/docs/helpers/FileSystem.md +0 -152
  58. package/docs/helpers/GraphQL.md +0 -151
  59. package/docs/helpers/GraphQLDataFactory.md +0 -226
  60. package/docs/helpers/JSONResponse.md +0 -254
  61. package/docs/helpers/Mochawesome.md +0 -8
  62. package/docs/helpers/MockRequest.md +0 -377
  63. package/docs/helpers/Nightmare.md +0 -1305
  64. package/docs/helpers/OpenAI.md +0 -70
  65. package/docs/helpers/Playwright.md +0 -2706
  66. package/docs/helpers/Polly.md +0 -44
  67. package/docs/helpers/Protractor.md +0 -1769
  68. package/docs/helpers/Puppeteer-firefox.md +0 -86
  69. package/docs/helpers/Puppeteer.md +0 -2291
  70. package/docs/helpers/REST.md +0 -218
  71. package/docs/helpers/TestCafe.md +0 -1321
  72. package/docs/helpers/WebDriver.md +0 -2460
  73. package/docs/hooks.md +0 -340
  74. package/docs/index.md +0 -111
  75. package/docs/installation.md +0 -75
  76. package/docs/internal-api.md +0 -266
  77. package/docs/locators.md +0 -331
  78. package/docs/mobile-react-native-locators.md +0 -67
  79. package/docs/mobile.md +0 -338
  80. package/docs/pageobjects.md +0 -291
  81. package/docs/parallel.md +0 -400
  82. package/docs/playwright.md +0 -632
  83. package/docs/plugins.md +0 -1259
  84. package/docs/puppeteer.md +0 -316
  85. package/docs/quickstart.md +0 -162
  86. package/docs/react.md +0 -69
  87. package/docs/reports.md +0 -392
  88. package/docs/secrets.md +0 -36
  89. package/docs/shadow.md +0 -68
  90. package/docs/shared/keys.mustache +0 -31
  91. package/docs/shared/react.mustache +0 -1
  92. package/docs/testcafe.md +0 -174
  93. package/docs/translation.md +0 -247
  94. package/docs/tutorial.md +0 -271
  95. package/docs/typescript.md +0 -180
  96. package/docs/ui.md +0 -59
  97. package/docs/videos.md +0 -28
  98. package/docs/visual.md +0 -202
  99. package/docs/vue.md +0 -121
  100. package/docs/webapi/amOnPage.mustache +0 -11
  101. package/docs/webapi/appendField.mustache +0 -11
  102. package/docs/webapi/attachFile.mustache +0 -12
  103. package/docs/webapi/blur.mustache +0 -18
  104. package/docs/webapi/checkOption.mustache +0 -13
  105. package/docs/webapi/clearCookie.mustache +0 -9
  106. package/docs/webapi/clearField.mustache +0 -9
  107. package/docs/webapi/click.mustache +0 -25
  108. package/docs/webapi/clickLink.mustache +0 -8
  109. package/docs/webapi/closeCurrentTab.mustache +0 -7
  110. package/docs/webapi/closeOtherTabs.mustache +0 -8
  111. package/docs/webapi/dontSee.mustache +0 -11
  112. package/docs/webapi/dontSeeCheckboxIsChecked.mustache +0 -10
  113. package/docs/webapi/dontSeeCookie.mustache +0 -8
  114. package/docs/webapi/dontSeeCurrentUrlEquals.mustache +0 -10
  115. package/docs/webapi/dontSeeElement.mustache +0 -8
  116. package/docs/webapi/dontSeeElementInDOM.mustache +0 -8
  117. package/docs/webapi/dontSeeInCurrentUrl.mustache +0 -4
  118. package/docs/webapi/dontSeeInField.mustache +0 -11
  119. package/docs/webapi/dontSeeInSource.mustache +0 -8
  120. package/docs/webapi/dontSeeInTitle.mustache +0 -8
  121. package/docs/webapi/doubleClick.mustache +0 -13
  122. package/docs/webapi/downloadFile.mustache +0 -12
  123. package/docs/webapi/dragAndDrop.mustache +0 -9
  124. package/docs/webapi/dragSlider.mustache +0 -11
  125. package/docs/webapi/executeAsyncScript.mustache +0 -24
  126. package/docs/webapi/executeScript.mustache +0 -26
  127. package/docs/webapi/fillField.mustache +0 -16
  128. package/docs/webapi/focus.mustache +0 -13
  129. package/docs/webapi/forceClick.mustache +0 -28
  130. package/docs/webapi/forceRightClick.mustache +0 -18
  131. package/docs/webapi/grabAllWindowHandles.mustache +0 -7
  132. package/docs/webapi/grabAttributeFrom.mustache +0 -10
  133. package/docs/webapi/grabAttributeFromAll.mustache +0 -9
  134. package/docs/webapi/grabBrowserLogs.mustache +0 -9
  135. package/docs/webapi/grabCookie.mustache +0 -11
  136. package/docs/webapi/grabCssPropertyFrom.mustache +0 -11
  137. package/docs/webapi/grabCssPropertyFromAll.mustache +0 -10
  138. package/docs/webapi/grabCurrentUrl.mustache +0 -9
  139. package/docs/webapi/grabCurrentWindowHandle.mustache +0 -6
  140. package/docs/webapi/grabDataFromPerformanceTiming.mustache +0 -20
  141. package/docs/webapi/grabElementBoundingRect.mustache +0 -20
  142. package/docs/webapi/grabGeoLocation.mustache +0 -8
  143. package/docs/webapi/grabHTMLFrom.mustache +0 -10
  144. package/docs/webapi/grabHTMLFromAll.mustache +0 -9
  145. package/docs/webapi/grabNumberOfOpenTabs.mustache +0 -8
  146. package/docs/webapi/grabNumberOfVisibleElements.mustache +0 -9
  147. package/docs/webapi/grabPageScrollPosition.mustache +0 -8
  148. package/docs/webapi/grabPopupText.mustache +0 -5
  149. package/docs/webapi/grabSource.mustache +0 -8
  150. package/docs/webapi/grabTextFrom.mustache +0 -10
  151. package/docs/webapi/grabTextFromAll.mustache +0 -9
  152. package/docs/webapi/grabTitle.mustache +0 -8
  153. package/docs/webapi/grabValueFrom.mustache +0 -9
  154. package/docs/webapi/grabValueFromAll.mustache +0 -8
  155. package/docs/webapi/grabWebElement.mustache +0 -9
  156. package/docs/webapi/grabWebElements.mustache +0 -9
  157. package/docs/webapi/moveCursorTo.mustache +0 -12
  158. package/docs/webapi/openNewTab.mustache +0 -7
  159. package/docs/webapi/pressKey.mustache +0 -12
  160. package/docs/webapi/pressKeyDown.mustache +0 -12
  161. package/docs/webapi/pressKeyUp.mustache +0 -12
  162. package/docs/webapi/pressKeyWithKeyNormalization.mustache +0 -60
  163. package/docs/webapi/refreshPage.mustache +0 -6
  164. package/docs/webapi/resizeWindow.mustache +0 -6
  165. package/docs/webapi/rightClick.mustache +0 -14
  166. package/docs/webapi/saveElementScreenshot.mustache +0 -10
  167. package/docs/webapi/saveScreenshot.mustache +0 -12
  168. package/docs/webapi/say.mustache +0 -10
  169. package/docs/webapi/scrollIntoView.mustache +0 -11
  170. package/docs/webapi/scrollPageToBottom.mustache +0 -6
  171. package/docs/webapi/scrollPageToTop.mustache +0 -6
  172. package/docs/webapi/scrollTo.mustache +0 -12
  173. package/docs/webapi/see.mustache +0 -11
  174. package/docs/webapi/seeAttributesOnElements.mustache +0 -9
  175. package/docs/webapi/seeCheckboxIsChecked.mustache +0 -10
  176. package/docs/webapi/seeCookie.mustache +0 -8
  177. package/docs/webapi/seeCssPropertiesOnElements.mustache +0 -9
  178. package/docs/webapi/seeCurrentUrlEquals.mustache +0 -11
  179. package/docs/webapi/seeElement.mustache +0 -8
  180. package/docs/webapi/seeElementInDOM.mustache +0 -8
  181. package/docs/webapi/seeInCurrentUrl.mustache +0 -8
  182. package/docs/webapi/seeInField.mustache +0 -12
  183. package/docs/webapi/seeInPopup.mustache +0 -8
  184. package/docs/webapi/seeInSource.mustache +0 -7
  185. package/docs/webapi/seeInTitle.mustache +0 -8
  186. package/docs/webapi/seeNumberOfElements.mustache +0 -11
  187. package/docs/webapi/seeNumberOfVisibleElements.mustache +0 -10
  188. package/docs/webapi/seeTextEquals.mustache +0 -9
  189. package/docs/webapi/seeTitleEquals.mustache +0 -8
  190. package/docs/webapi/selectOption.mustache +0 -21
  191. package/docs/webapi/setCookie.mustache +0 -16
  192. package/docs/webapi/setGeoLocation.mustache +0 -12
  193. package/docs/webapi/switchTo.mustache +0 -9
  194. package/docs/webapi/switchToNextTab.mustache +0 -10
  195. package/docs/webapi/switchToPreviousTab.mustache +0 -10
  196. package/docs/webapi/type.mustache +0 -21
  197. package/docs/webapi/uncheckOption.mustache +0 -13
  198. package/docs/webapi/wait.mustache +0 -8
  199. package/docs/webapi/waitForClickable.mustache +0 -11
  200. package/docs/webapi/waitForDetached.mustache +0 -10
  201. package/docs/webapi/waitForElement.mustache +0 -11
  202. package/docs/webapi/waitForEnabled.mustache +0 -6
  203. package/docs/webapi/waitForFunction.mustache +0 -17
  204. package/docs/webapi/waitForInvisible.mustache +0 -10
  205. package/docs/webapi/waitForText.mustache +0 -13
  206. package/docs/webapi/waitForValue.mustache +0 -10
  207. package/docs/webapi/waitForVisible.mustache +0 -10
  208. package/docs/webapi/waitInUrl.mustache +0 -9
  209. package/docs/webapi/waitNumberOfVisibleElements.mustache +0 -10
  210. package/docs/webapi/waitToHide.mustache +0 -10
  211. package/docs/webapi/waitUrlEquals.mustache +0 -10
  212. package/docs/webdriver.md +0 -655
  213. package/docs/wiki/Books-&-Posts.md +0 -27
  214. package/docs/wiki/Community-Helpers-&-Plugins.md +0 -53
  215. package/docs/wiki/Converting-Playwright-to-Istanbul-Coverage.md +0 -61
  216. package/docs/wiki/Examples.md +0 -145
  217. package/docs/wiki/Google-Summer-of-Code-(GSoC)-2020.md +0 -68
  218. package/docs/wiki/Home.md +0 -16
  219. package/docs/wiki/Migration-to-Appium-v2---CodeceptJS.md +0 -83
  220. package/docs/wiki/Release-Process.md +0 -24
  221. package/docs/wiki/Roadmap.md +0 -23
  222. package/docs/wiki/Tests.md +0 -1393
  223. package/docs/wiki/Upgrading-to-CodeceptJS-3.md +0 -153
  224. package/docs/wiki/Videos.md +0 -19
  225. package/lib/helper/extras/PlaywrightReact.js +0 -9
package/docs/webdriver.md DELETED
@@ -1,655 +0,0 @@
1
- ---
2
- permalink: /webdriver
3
- title: Testing with WebDriver
4
- ---
5
-
6
- # Testing with WebDriver
7
-
8
- How does your client, manager, or tester, or any other non-technical person, know your web application is working? By opening the browser, accessing a site, clicking on links, filling in the forms, and actually seeing the content on a web page.
9
-
10
- End to End tests can cover standard but complex scenarios from a user's perspective. With e2e tests you can be confident that users, following all defined scenarios, won't get errors. We check **functionality of application and a user interface** (UI) as well.
11
-
12
- ## What is Selenium WebDriver
13
-
14
- The standard and proved way to run browser test automation over years is Selenium WebDriver. Over years this technology was standartized and works over all popular browsers and operating systems. There are cloud services like SauceLabs or BrowserStack which allow executing such browsers in the cloud. The superset of WebDriver protocol is also used to test [native and hybrid mobile applications](/mobile).
15
-
16
- Let's clarify the terms:
17
-
18
- * Selenium - is a toolset for browser test automation
19
- * WebDriver - a standard protocol for communicating between test framework and browsers
20
- * JSON Wire - an older version of such protocol
21
-
22
- We use [webdriverio](https://webdriver.io) library to run tests over WebDriver.
23
-
24
- To proceed you need to have [CodeceptJS installed](/quickstart#using-selenium-webdriver) and `WebDriver` helper selected.
25
-
26
- Selenium WebDriver may be complicated from start, as it requires following tools to be installed and started.
27
-
28
- 1. Selenium Server - to execute and send commands to browser
29
- 2. ChromeDriver or GeckoDriver - to allow browsers to run in automated mode.
30
-
31
- > Those tools can be easily installed via NPM. Use [selenium-standalone](https://www.npmjs.com/package/selenium-standalone) to automatically install them.
32
-
33
- You can also use `@wdio/selenium-standalone-service` package, to install and start Selenium Server for your tests automatically.
34
-
35
- ```
36
- npm i @wdio/selenium-standalone-service --save-dev
37
- ```
38
-
39
- Enable it in config inside plugins section:
40
-
41
- ```js
42
- exports.config = {
43
- // ...
44
- // inside condecept.conf.js
45
- plugins: {
46
- wdio: {
47
- enabled: true,
48
- services: ['selenium-standalone']
49
- }
50
- }
51
- }
52
- ```
53
-
54
- > ⚠ It is not recommended to use wdio plugin & selenium-standalone when running tests in parallel. Consider **switching to Selenoid** if you need parallel run or using cloud services.
55
-
56
-
57
- ## Configuring WebDriver
58
-
59
- WebDriver can be configured to run browser tests in window, headlessly, on a remote server or in a cloud.
60
-
61
- > By default CodeceptJS is already configured to run WebDriver tests locally with Chrome or Firefox. If you just need to start running tests - proceed to the next chapter.
62
-
63
- Configuration for WebDriver should be provided inside `codecept.conf.js` file under `helpers: WebDriver` section:
64
-
65
- ```js
66
- helpers: {
67
- WebDriver: {
68
- url: 'https://myapp.com',
69
- browser: 'chrome',
70
- host: '127.0.0.1',
71
- port: 4444,
72
- restart: false,
73
- windowSize: '1920x1680',
74
- desiredCapabilities: {
75
- chromeOptions: {
76
- args: [ /*"--headless",*/ "--disable-gpu", "--no-sandbox" ]
77
- }
78
- }
79
- },
80
- }
81
- ```
82
-
83
- By default CodeceptJS runs tests in the same browser window but clears cookies and local storage after each test. This behavior can be changed with these options:
84
-
85
- ```js
86
- // change to true to restart browser between tests
87
- restart: false,
88
- // don't change browser state and not clear cookies between tests
89
- keepBrowserState: true,
90
- keepCookies: true,
91
- ```
92
-
93
- > ▶ More config options available on [WebDriver helper reference](/helpers/WebDriver#configuration)
94
-
95
- ### ChromeDriver without Selenium
96
-
97
- If you want to run tests using raw ChromeDriver (which also supports WebDriver protocol) avoiding Selenium Server, you should provide following configuration:
98
-
99
- ```js
100
- port: 9515,
101
- browser: 'chrome',
102
- path: '/',
103
- ```
104
-
105
- > If you face issues connecting to WebDriver, please check that corresponding server is running on a specified port. If host is other than `localhost` or port is other than `4444`, update the configuration.
106
-
107
- ### Selenium in Docker (Selenoid)
108
-
109
- Browsers can be executed in Docker containers. This is useful when testing on Continous Integration server.
110
- We recommend using [Selenoid](https://aerokube.com/selenoid/) to run browsers in container.
111
-
112
- CodeceptJS has [Selenoid plugin](/plugins#selenoid) which can automagically load browser container setup.
113
-
114
-
115
- ### Headless Mode
116
-
117
- It is recommended to use `@codeceptjs/configure` package to easily toggle headless mode for WebDriver:
118
-
119
- ```js
120
- // inside codecept.conf.js
121
- const { setHeadlessWhen, setWindowSize } = require('@codeceptjs/configure');
122
-
123
- setHeadlessWhen(process.env.HEADLESS); // enables headless mode when HEADLESS environment variable exists
124
- ```
125
- This requires `@codeceptjs/configure` package to be installed.
126
-
127
- Alternatively, you can enable headless mode manually via desired capabilities.
128
-
129
- ### Desired Capabilities
130
-
131
- Additional configuration can be passed via `desiredCapabilities` option.
132
- For instance, this is how we can set to **run headless Chrome**:
133
-
134
- ```js
135
- desiredCapabilities: {
136
- chromeOptions: {
137
- args: [ "--headless", "--disable-gpu", "--window-size=1200,1000", "--no-sandbox" ]
138
- }
139
- }
140
- ```
141
-
142
- Next popular use case for capabilities is configuring what to do with unhandled alert popups.
143
-
144
- ```js
145
- desiredCapabilities: {
146
- // close all unexpected popups
147
- unexpectedAlertBehaviour: 'dismiss',
148
- }
149
- ```
150
-
151
- ### Cloud Providers
152
-
153
- WebDriver protocol works over HTTP, so you need to have a Selenium Server to be running or any other service that will launch a browser for you. That's why you may need to specify `host`, `port`, `protocol`, and `path` parameters.
154
-
155
- By default, those parameters are set to connect to local Selenium Server but they should be changed if you want to run tests via [Cloud Providers](/helpers/WebDriver#cloud-providers). You may also need `user` and `key` parameters to authenticate on cloud service.
156
-
157
- There are also [browser and platform specific capabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities). Services like SauceLabs, BrowserStack or browser vendors can provide their own specific capabilities for more tuning.
158
-
159
- Here is a sample BrowserStack config for running tests on iOS mobile browser:
160
-
161
- ```js
162
- helpers: {
163
- WebDriver: {
164
- host: 'hub.browserstack.com',
165
- path: '/wd/hub',
166
- url: 'http://WEBSITE:8080/renderer',
167
- user: 'xx', // credentials
168
- key: 'xx', // credentials
169
- browser: 'iphone',
170
- desiredCapabilities: {
171
- 'os_version' : '11',
172
- 'device' : 'iPhone 8', // you can select device
173
- 'real_mobile' : 'true', // real or emulated
174
- 'browserstack.local' : 'true',
175
- 'browserstack.debug' : 'true',
176
- 'browserstack.networkLogs' : 'true',
177
- 'browserstack.appium_version' : '1.9.1',
178
- 'browserstack.user' : 'xx', // credentials
179
- 'browserstack.key' : 'xx' // credentials
180
- }
181
- }
182
- ```
183
-
184
-
185
- ## Writing Tests
186
-
187
- CodeceptJS provides high-level API on top of WebDriver protocol. While most standard implementations focus on dealing with WebElements on page, CodeceptJS is about user scenarios and interactions. That's why you don't have a direct access to web elements inside a test, but it is proved that in majority of cases you don't need it. Tests written from user's perspective are simpler to write, understand, log and debug.
188
-
189
- > If you come from Java, Python or Ruby don't be afraid of a new syntax. It is more flexible than you think!
190
-
191
- A typical test case may look like this:
192
-
193
- ```js
194
- Feature('login');
195
-
196
- Scenario('login test', ({ I }) => {
197
- I.amOnPage('/login');
198
- I.fillField('Username', 'john');
199
- I.fillField('Password', '123456');
200
- I.click('Login');
201
- I.see('Welcome, John');
202
- });
203
- ```
204
-
205
- An empty test case can be created with `npx codeceptjs gt` command.
206
-
207
- ```
208
- npx codeceptjs gt
209
- ```
210
-
211
-
212
- ### Actions
213
-
214
- Tests consist with a scenario of user's action taken on a page. The most widely used ones are:
215
-
216
- * `amOnPage` - to open a webpage (accepts relative or absolute url)
217
- * `click` - to locate a button or link and click on it
218
- * `fillField` - to enter a text inside a field
219
- * `selectOption`, `checkOption` - to interact with a form
220
- * `wait*` to wait for some parts of page to be fully rendered (important for testing SPA)
221
- * `grab*` to get values from page sources
222
- * `see`, `dontSee` - to check for a text on a page
223
- * `seeElement`, `dontSeeElement` - to check for elements on a page
224
-
225
- > ℹ All actions are listed in [WebDriver helper reference](https://codecept.io/helpers/WebDriver/).*
226
-
227
- All actions which interact with elements **support CSS and XPath locators**. Actions like `click` or `fillField` by locate elements by their name or value on a page:
228
-
229
- ```js
230
- // search for link or button
231
- I.click('Login');
232
- // locate field by its label
233
- I.fillField('Name', 'Miles');
234
- // we can use input name
235
- I.fillField('user[email]','miles@davis.com');
236
- ```
237
-
238
- You can also specify the exact locator type with strict locators:
239
-
240
- ```js
241
- I.click({css: 'button.red'});
242
- I.fillField({name: 'user[email]'},'miles@davis.com');
243
- I.seeElement({xpath: '//body/header'});
244
- ```
245
-
246
- ### Interactive Pause
247
-
248
- It's easy to start writing a test if you use [interactive pause](/basics#debug). Just open a web page and pause execution.
249
-
250
- ```js
251
- Feature('Sample Test');
252
-
253
- Scenario('open my website', ({ I }) => {
254
- I.amOnPage('/');
255
- pause();
256
- });
257
- ```
258
-
259
- This is just enough to run a test, open a browser, and think what to do next to write a test case.
260
-
261
- When you execute such test with `npx codeceptjs run` command you may see the browser is started
262
-
263
- ```
264
- npx codeceptjs run --steps
265
- ```
266
-
267
- After a page is opened a full control of a browser is given to a terminal. Type in different commands such as `click`, `see`, `fillField` to write the test. A successful commands will be saved to `./output/cli-history` file and can be copied into a test.
268
-
269
- > ℹ All actions are listed in [WebDriver helper reference](/helpers/WebDriver).
270
-
271
- An interactive shell output may look like this:
272
-
273
- ```
274
- Interactive shell started
275
- Use JavaScript syntax to try steps in action
276
- - Press ENTER to run the next step
277
- - Press TAB twice to see all available commands
278
- - Type exit + Enter to exit the interactive shell
279
- I.fillField('.new-todo', 'Write a test')
280
- I.pressKey('Enter')
281
- I.
282
- Commands have been saved to /home/davert/demos/codeceptjs/output/cli-history
283
- ```
284
- After typing in successful commands you can copy them into a test.
285
-
286
- Here is a test checking basic [todo application](https://todomvc.com/).
287
-
288
- ```js
289
- Feature('TodoMVC');
290
-
291
- Scenario('create todo item', ({ I }) => {
292
- I.amOnPage('/examples/vue/');
293
- I.waitForElement('.new-todo');
294
- I.fillField('.new-todo', 'Write a test')
295
- I.pressKey('Enter');
296
- I.see('1 item left', '.todo-count');
297
- });
298
- ```
299
-
300
- > [▶ Working example of CodeceptJS WebDriver tests](https://github.com/DavertMik/codeceptjs-webdriver-example) for TodoMVC application.
301
-
302
- WebDriver helper supports standard [CSS/XPath and text locators](/locators) as well as non-trivial [React locators](/react) and [Shadow DOM](/shadow).
303
-
304
- ### Grabbers
305
-
306
- If you need to get element's value inside a test you can use `grab*` methods. They should be used with `await` operator inside `async` function:
307
-
308
- ```js
309
- const assert = require('assert');
310
- Scenario('get value of current tasks', async ({ I }) => {
311
- I.fillField('.todo', 'my first item');
312
- I.pressKey('Enter')
313
- I.fillField('.todo', 'my second item');
314
- I.pressKey('Enter')
315
- let numTodos = await I.grabTextFrom('.todo-count strong');
316
- assert.equal(2, numTodos);
317
- });
318
- ```
319
-
320
- ### Within
321
-
322
- In case some actions should be taken inside one element (a container or modal window or iframe) you can use `within` block to narrow the scope.
323
- Please take a note that you can't use within inside another within in Puppeteer helper:
324
-
325
- ```js
326
- await within('.todoapp', () => {
327
- I.fillField('.todo', 'my new item');
328
- I.pressKey('Enter')
329
- I.see('1 item left', '.todo-count');
330
- I.click('.todo-list input.toggle');
331
- });
332
- I.see('0 items left', '.todo-count');
333
- ```
334
-
335
- ### Each Element <Badge text="Since 3.3" type="warning"/>
336
-
337
- Usually, CodeceptJS performs an action on the first matched element.
338
- In case you want to do an action on each element found, use the special function `eachElement` which comes from [eachElement](https://codecept.io/plugins/#eachelement) plugin.
339
-
340
- `eachElement` function matches all elements by locator and performs a callback on each of those element. A callback function receives element of webdriverio. `eachElement` may perform arbitrary actions on a page, so the first argument should by a description of the actions performed. This description will be used for logging purposes.
341
-
342
- Usage example
343
-
344
- ```js
345
- await eachElement(
346
- 'click all checkboxes',
347
- 'input.custom-checkbox',
348
- async (el, index) => {
349
- await el.click();
350
- });
351
- );
352
- ```
353
-
354
- > ℹ Learn more about [eachElement plugin](/plugins/#eachelement)
355
-
356
-
357
- ## Waiting
358
-
359
- Web applications do not always respond instantly. That's why WebDriver protocol has methods to wait for changes on a page. CodeceptJS provides such commands prefixed with `wait*` so you could explicitly define what effects we wait for.
360
-
361
- Most popular "waiters" are:
362
-
363
- * `waitForText` - wait for text to appear on a page
364
- * `waitForElement` - wait for element to appear on a page
365
- * `waitForInvisible` - wait element to become invisible.
366
-
367
- By default, they will wait for 1 second. This number can be changed in WebDriver configuration:
368
-
369
- ```js
370
- // inside codecept.conf.js
371
- exports.config = {
372
- helpers: {
373
- WebDriver: {
374
- // WebDriver config goes here
375
- // wait for 5 seconds
376
- waitForTimeout: 5000
377
- }
378
- }
379
- }
380
- ```
381
-
382
- ## SmartWait
383
-
384
- It is possible to wait for elements pragmatically. If a test uses element which is not on a page yet, CodeceptJS will wait for few extra seconds before failing. This feature is based on [Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits) of Selenium. CodeceptJS enables implicit wait only when searching for a specific element and disables in all other cases. Thus, the performance of a test is not affected.
385
-
386
- SmartWait can be enabled by setting wait option in WebDriver config.
387
- Add `smartWait: 5000` to wait for additional 5s.
388
-
389
- ```js
390
- // inside codecept.conf.js
391
- exports.config = {
392
- helpers: {
393
- WebDriver: {
394
- // WebDriver config goes here
395
- // smart wait for 5 seconds
396
- smartWait: 5000
397
- }
398
- }
399
- }
400
- ```
401
-
402
- SmartWait works with a CSS/XPath locators in `click`, `seeElement` and other methods. See where it is enabled and where is not:
403
-
404
- ```js
405
- I.click('Login'); // DISABLED, not a locator
406
- I.fillField('user', 'davert'); // DISABLED, not a specific locator
407
- I.fillField({name: 'password'}, '123456'); // ENABLED, strict locator
408
- I.click('#login'); // ENABLED, locator is CSS ID
409
- I.see('Hello, Davert'); // DISABLED, Not a locator
410
- I.seeElement('#userbar'); // ENABLED
411
- I.dontSeeElement('#login'); // DISABLED, can't wait for element to hide
412
- I.seeNumberOfElements('button.link', 5); // DISABLED, can wait only for one element
413
-
414
- ```
415
-
416
- SmartWait doesn't check element for visibility, so tests may fail even element is on a page.
417
-
418
- Usage example:
419
-
420
- ```js
421
- // we use smartWait: 5000 instead of
422
- // I.waitForElement('#click-me', 5);
423
- // to wait for element on page
424
- I.click('#click-me');
425
- ```
426
-
427
- If it's hard to define what to wait, it is recommended to use [retries](/basics/#retries) to rerun flaky steps.
428
-
429
- ## Configuring CI
430
-
431
- To develop tests it's fine to use local Selenium Server and window mode. Setting up WebDriver on remote CI (Continous Integration) server is different. If there is no desktop and no window mode on CI.
432
-
433
- There are following options available:
434
-
435
- * Use headless Chrome or Firefox.
436
- * Use [Selenoid](/plugins/selenoid) to run browsers inside Docker containers.
437
- * Use paid [cloud services (SauceLabs, BrowserStack, TestingBot)](/helpers/WebDriver#cloud-providers).
438
-
439
- ## Video Recording
440
-
441
- When [Selenoid Plugin](/plugins#selenoid) is enabled video can be automatically recorded for each test.
442
-
443
- ## Auto Login
444
-
445
- To share the same user session across different tests CodeceptJS provides [autoLogin plugin](/plugins#autologin). It simplifies login management and reduces time consuming login operations. Instead of filling in login form before each test it saves the cookies of a valid user session and reuses it for next tests. If a session expires or doesn't exist, logs in a user again.
446
-
447
- This plugin requires some configuration but is very simple in use:
448
-
449
- ```js
450
- Scenario('do something with logged in user', ({ I, login }) => {
451
- login('user');
452
- I.see('Dashboard','h1');
453
- });
454
- ```
455
-
456
- With `autoLogin` plugin you can save cookies into a file and reuse same session on different runs.
457
-
458
- > [▶ How to set up autoLogin plugin](/plugins#autologin)
459
-
460
-
461
- ## Multiple Windows
462
-
463
- CodeceptJS allows to use several browser windows inside a test. Sometimes we are testing the functionality of websites that we cannot control, such as a closed-source managed package, and there are popups that either remain open for configuring data on the screen, or close as a result of clicking a window. We can use these functions in order to gain more control over which page is being tested with Codecept at any given time. For example:
464
-
465
- ```js
466
- const assert = require('assert');
467
-
468
- Scenario('should open main page of configured site, open a popup, switch to main page, then switch to popup, close popup, and go back to main page', async ({ I }) => {
469
- I.amOnPage('/');
470
- const handleBeforePopup = await I.grabCurrentWindowHandle();
471
- const urlBeforePopup = await I.grabCurrentUrl();
472
- const allHandlesBeforePopup = await I.grabAllWindowHandles();
473
- assert.equal(allHandlesBeforePopup.length, 1, 'Single Window');
474
-
475
- await I.executeScript(() => {
476
- window.open('https://www.w3schools.com/', 'new window', 'toolbar=yes,scrollbars=yes,resizable=yes,width=400,height=400');
477
- });
478
-
479
- const allHandlesAfterPopup = await I.grabAllWindowHandles();
480
- assert.equal(allHandlesAfterPopup.length, 2, 'Two Windows');
481
-
482
- await I.switchToWindow(allHandlesAfterPopup[1]);
483
- const urlAfterPopup = await I.grabCurrentUrl();
484
- assert.equal(urlAfterPopup, 'https://www.w3schools.com/', 'Expected URL: Popup');
485
-
486
- assert.equal(handleBeforePopup, allHandlesAfterPopup[0], 'Expected Window: Main Window');
487
- await I.switchToWindow(handleBeforePopup);
488
- const currentURL = await I.grabCurrentUrl();
489
- assert.equal(currentURL, urlBeforePopup, 'Expected URL: Main URL');
490
-
491
- await I.switchToWindow(allHandlesAfterPopup[1]);
492
- const urlAfterSwitchBack = await I.grabCurrentUrl();
493
- assert.equal(urlAfterSwitchBack, 'https://www.w3schools.com/', 'Expected URL: Popup');
494
- await I.closeCurrentTab();
495
-
496
- const allHandlesAfterPopupClosed = await I.grabAllWindowHandles();
497
- assert.equal(allHandlesAfterPopupClosed.length, 1, 'Single Window');
498
- const currentWindowHandle = await I.grabCurrentWindowHandle();
499
- assert.equal(currentWindowHandle, allHandlesAfterPopup[0], 'Expected Window: Main Window');
500
-
501
- });
502
- ```
503
-
504
- ## Mocking Requests
505
-
506
- When testing web application you can disable some of external requests calls by enabling HTTP mocking.
507
- 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.
508
-
509
- > **WebDriver has limited ability to mock requests**, so you can only mock only requests performed after page is loaded. This means that you can't block Google Analytics, or CDN calls, but you can mock API requests performed on user action.
510
-
511
- To mock requests enable additional helper [MockRequest](/helpers/MockRequest) (which is based on Polly.js).
512
-
513
- ```js
514
- helpers: {
515
- WebDriver: {
516
- // regular WebDriver config here
517
- },
518
- MockRequest: {}
519
- }
520
- ```
521
-
522
-
523
- The function `mockRequest` will be added to `I` object. You can use it to explicitly define which requests to block and which response they should return instead:
524
-
525
- ```js
526
- // block all Google Analytics calls
527
- I.mockRequest('/google-analytics/*path', 200);
528
- // return an empty successful response
529
- I.mockRequest('GET', '/api/users', 200);
530
- // block post requests to /api/users and return predefined object
531
- I.mockRequest('POST', '/api/users', { user: 'davert' });
532
- // return error request with body
533
- I.mockRequest('GET', '/api/users/1', 404, { error: 'User not found' });
534
- ```
535
-
536
- > In WebDriver mocking is disabled every time a new page is loaded. Hence, `startMocking` method should be called and the mocks should be updated, after navigating to a new page. This is a limitation of WebDriver. Consider using Puppeteer with MockRequest instead.
537
-
538
- ```js
539
- I.amOnPage('/xyz');
540
- I.mockRequest({ ... })
541
- I.click('Go to Next Page');
542
- // new page is loaded, mocking is disabled now. We need to set it up again
543
- // in WebDriver as we can't detect that the page was reloaded, so no mocking :(
544
- ```
545
-
546
- > See [`mockRequest` API](/helpers/MockRequest#mockrequest)
547
-
548
- To see `mockRequest` method in intellisense auto completion don't forget to run `codeceptjs def` command:
549
-
550
- ```
551
- npx codeceptjs def
552
- ```
553
-
554
- Mocking rules will be kept while a test is running. To stop mocking use `I.stopMocking()` command
555
-
556
-
557
- ## Accessing webdriverio API
558
-
559
- To get [webdriverio browser API](https://webdriver.io/docs/api.html) inside a test use [`I.useWebDriverTo`](/helpers/WebDriver/#usewebdriverto) method with a callback.
560
- To keep test readable provide a description of a callback inside the first parameter.
561
-
562
- ```js
563
- I.useWebDriverTo('do something with native webdriverio api', async ({ browser }) => {
564
- // use browser object here
565
- });
566
- ```
567
-
568
- > webdriverio commands are asynchronous so a callback function must be async.
569
-
570
- WebDriver helper can be obtained in this function as well. Use this to get full access to webdriverio elements inside the test.
571
-
572
- ```js
573
- I.useWebDriverTo('click all Save buttons', async (WebDriver) => {
574
- const els = await WebDriver._locateClickable('Save');
575
- for (let el of els) {
576
- await el.click();
577
- }
578
- });
579
- ```
580
-
581
- ## Extending WebDriver
582
-
583
- CodeceptJS doesn't aim to embrace all possible functionality of WebDriver. At some points you may find that some actions do not exist, however it is easy to add one. You will need to use WebDriver API from [webdriver.io](https://webdriver.io) library.
584
-
585
- To create new actions which will be added into `I.` object you need to create a new helper. This can be done with `codeceptjs gh` command.
586
-
587
- ```
588
- npx codeceptjs gh
589
- ```
590
-
591
- Name a new helper "Web". Now each method of a created class can be added to I object. Be sure to enable this helper in config:
592
-
593
- ```js
594
- exports.config = {
595
- helpers: {
596
- WebDriver: { /* WebDriver config goes here */ },
597
- WebHelper: {
598
- // load custom helper
599
- require: './web_helper.js'
600
- }
601
- }
602
- }
603
- ```
604
-
605
- > ℹ See [Custom Helper](/helpers) guide to see more examples.
606
-
607
- While implementing custom actions using WebDriver API please note that, there is two versions of protocol: WebDriver and JSON Wire. Depending on a browser version one of those protocols can be used. We can't know for sure which protocol is going to used, so we will need to implement an action using both APIs.
608
-
609
- ```js
610
- const Helper = codeceptjs.helper;
611
-
612
- class Web extends Helper {
613
-
614
- // method to drag an item to coordinates
615
- async dragToPoint(el, x, y) {
616
- // access browser object from WebDriver
617
- const browser = this.helpers.WebDriver.browser;
618
- await this.helpers.WebDriver.moveCursorTo(el);
619
-
620
- if (browser.isW3C) {
621
- // we use WebDriver protocol
622
- return browser.performActions([
623
- {"type": "pointerDown", "button": 0},
624
- {"type": "pointerMove", "origin": "pointer", "duration": 1000, x, y },
625
- {"type": "pointerUp", "button": 0}
626
- ]);
627
- }
628
-
629
- // we use JSON Wire protocol
630
- await browser.buttonDown(0);
631
- await browser.moveToElement(null, x, y);
632
- await browser.buttonUp(0);
633
- }
634
-
635
- // method which restarts browser
636
- async restartBrowser() {
637
- const browser = this.helpers.WebDriver.browser;
638
- await browser.reloadSession();
639
- await browser.maximizeWindow();
640
- }
641
-
642
- // method which goes to previous page
643
- async backToPreviousPage() {
644
- const browser = this.helpers.WebDriver.browser;
645
- await browser.back();
646
- }
647
- }
648
- ```
649
-
650
- When a helper is created, regenerate your step definitions, so you could see those actions when using [intellisense](/basics#intellisense):
651
-
652
- ```
653
- npx codeceptjs def
654
- ```
655
-
@@ -1,27 +0,0 @@
1
- ### [Practical End 2 End Testing with CodeceptJS](https://leanpub.com/codeceptjs/)
2
-
3
- A book by **Paul Vincent Beigang**
4
-
5
- [![](https://user-images.githubusercontent.com/220264/58870454-e2e8ce80-86c8-11e9-868e-7deefdde47ce.png)](https://leanpub.com/codeceptjs/)
6
-
7
- #### Contents:
8
-
9
- 1. Preparation for End 2 End Testing with CodeceptJS
10
- 1. Setup CodeceptJS with WebdriverIO
11
- 1. Create Your First CodeceptJS Test
12
- 1. Run Your First CodeceptJS Test Locally
13
- 1. Run Test on BrowserStack Against with the Safari Browser
14
- 1. How to Debug & Fix a Failing E2E Test
15
- 1. Run a CodeceptJS Test in GitLab´s Continuous Integration (CI) Environment
16
- 1. Delicious Test Reports With Allure
17
-
18
- ### Posts
19
-
20
- A list of good educational posts about CodeceptJS
21
-
22
- * [QA Automation From Zero-to-Hero with CodeceptJS End-to-End Testing](https://medium.com/@dan.ryan.emmons/qa-automation-from-zero-to-hero-with-codeceptjs-end-to-end-testing-719db9d6ff5c) by Dan Emmons
23
- * [Effective End2End Tests with CodeceptJS](https://hackernoon.com/effective-end-2-end-testing-in-javascript-with-codeceptjs-37c8d7d6a928) by @davertmik
24
- * [Customizing CodeceptJS Skeleton](https://medium.com/@successivetech/codeceptjs-skeleton-9ba86d3b45ec)
25
- * [Running End to End tests as Google Cloud Functions](https://hackernoon.com/running-end-to-end-tests-as-google-cloud-functions-f5e34ffc3984)
26
- * [End-To-End Testing With CodeceptJS](https://www.monterail.com/blog/end-to-end-testing-with-codeceptjs) by Piotr Michalski
27
- * [Getting started with CodeceptJS and Selenium WebDriver](https://medium.com/@garrettvorce/getting-started-with-selenium-and-codeceptjs-c0698e8df677)