codeceptjs 3.1.1 → 3.2.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 (70) hide show
  1. package/CHANGELOG.md +120 -0
  2. package/README.md +2 -3
  3. package/bin/codecept.js +1 -0
  4. package/docs/advanced.md +94 -60
  5. package/docs/basics.md +1 -1
  6. package/docs/bdd.md +55 -1
  7. package/docs/build/Appium.js +22 -4
  8. package/docs/build/FileSystem.js +1 -0
  9. package/docs/build/Playwright.js +40 -42
  10. package/docs/build/Protractor.js +9 -24
  11. package/docs/build/Puppeteer.js +28 -30
  12. package/docs/build/REST.js +1 -0
  13. package/docs/build/WebDriver.js +2 -24
  14. package/docs/changelog.md +120 -0
  15. package/docs/commands.md +21 -7
  16. package/docs/configuration.md +15 -2
  17. package/docs/custom-helpers.md +1 -36
  18. package/docs/helpers/Appium.md +49 -50
  19. package/docs/helpers/FileSystem.md +1 -1
  20. package/docs/helpers/Playwright.md +16 -18
  21. package/docs/helpers/Puppeteer.md +18 -18
  22. package/docs/helpers/REST.md +3 -1
  23. package/docs/helpers/WebDriver.md +1 -17
  24. package/docs/mobile-react-native-locators.md +3 -0
  25. package/docs/playwright.md +40 -0
  26. package/docs/plugins.md +187 -70
  27. package/docs/reports.md +23 -5
  28. package/lib/actor.js +20 -2
  29. package/lib/codecept.js +15 -2
  30. package/lib/command/info.js +1 -1
  31. package/lib/config.js +13 -1
  32. package/lib/container.js +3 -1
  33. package/lib/data/dataTableArgument.js +35 -0
  34. package/lib/helper/Appium.js +22 -4
  35. package/lib/helper/FileSystem.js +1 -0
  36. package/lib/helper/Playwright.js +40 -32
  37. package/lib/helper/Protractor.js +2 -14
  38. package/lib/helper/Puppeteer.js +21 -20
  39. package/lib/helper/REST.js +1 -0
  40. package/lib/helper/WebDriver.js +2 -14
  41. package/lib/index.js +2 -0
  42. package/lib/interfaces/featureConfig.js +3 -0
  43. package/lib/interfaces/gherkin.js +7 -1
  44. package/lib/interfaces/scenarioConfig.js +4 -0
  45. package/lib/listener/helpers.js +1 -0
  46. package/lib/listener/steps.js +21 -3
  47. package/lib/listener/timeout.js +71 -0
  48. package/lib/locator.js +3 -0
  49. package/lib/mochaFactory.js +13 -9
  50. package/lib/plugin/allure.js +6 -1
  51. package/lib/plugin/{puppeteerCoverage.js → coverage.js} +10 -22
  52. package/lib/plugin/customLocator.js +2 -2
  53. package/lib/plugin/retryFailedStep.js +4 -3
  54. package/lib/plugin/retryTo.js +130 -0
  55. package/lib/plugin/screenshotOnFail.js +1 -0
  56. package/lib/plugin/stepByStepReport.js +7 -0
  57. package/lib/plugin/stepTimeout.js +90 -0
  58. package/lib/plugin/subtitles.js +88 -0
  59. package/lib/plugin/tryTo.js +1 -1
  60. package/lib/recorder.js +21 -8
  61. package/lib/step.js +7 -2
  62. package/lib/store.js +2 -0
  63. package/lib/ui.js +2 -2
  64. package/package.json +6 -7
  65. package/typings/index.d.ts +8 -1
  66. package/typings/types.d.ts +104 -71
  67. package/docs/angular.md +0 -325
  68. package/docs/helpers/Protractor.md +0 -1658
  69. package/docs/webapi/waitUntil.mustache +0 -11
  70. package/typings/Protractor.d.ts +0 -16
package/CHANGELOG.md CHANGED
@@ -1,3 +1,123 @@
1
+ ## 3.2.1
2
+
3
+ > ♻️ This release fixes hanging of tests by reducing timeouts for automatic retries on failures.
4
+
5
+ * [retryFailedStep plugin] **New Defaults**: retries steps up to 3 times with factor of 1.5 (previously 5 with factor 2)
6
+ * [Playwright] - disabled retry on failed context actions (not needed anymore)
7
+ * [Puppeteer] - reduced retries on context failures to 3 times.
8
+ * [Playwright] Handling `crash` event to automatically close crashed pages.
9
+
10
+ ## 3.2.0
11
+
12
+ 🛩️ Features:
13
+
14
+ **[Timeouts](https://codecept.io/advanced/#timeout) implemented**
15
+ * global timeouts (via `timeout` config option).
16
+ * _Breaking change:_ timeout option expects **timeout in seconds**, not in milliseconds as it was previously.
17
+ * test timeouts (via `Scenario` and `Feature` options)
18
+ * _Breaking change:_ `Feature().timeout()` and `Scenario().timeout()` calls has no effect and are deprecated
19
+
20
+ ```js
21
+ // set timeout for every test in suite to 10 secs
22
+ Feature('tests with timeout', { timeout: 10 });
23
+
24
+ // set timeout for this test to 20 secs
25
+ Scenario('a test with timeout', { timeout: 20 }, ({ I }) => {});
26
+ ```
27
+
28
+ * step timeouts (See #3059 by @nikocanvacom)
29
+
30
+ ```js
31
+ // set step timeout to 5 secs
32
+ I.limitTime(5).click('Link');
33
+ ```
34
+ * `stepTimeout` plugin introduced to automatically add timeouts for each step (#3059 by @nikocanvacom).
35
+
36
+ [**retryTo**](/plugins/#retryto) plugin introduced to rerun a set of steps on failure:
37
+
38
+ ```js
39
+ // editing in text in iframe
40
+ // if iframe was not loaded - retry 5 times
41
+ await retryTo(() => {
42
+ I.switchTo('#editor frame');
43
+ I.fillField('textarea', 'value');
44
+ }, 5);
45
+ ```
46
+
47
+ * [Playwright] added `locale` configuration
48
+ * [WebDriver] upgraded to webdriverio v7
49
+
50
+ 🐛 Bugfixes:
51
+
52
+ * Fixed allure plugin "Unexpected endStep()" error in #3098 by @abhimanyupandian
53
+ * [Puppeteer] always close remote browser on test end. See #3054 by @mattonem
54
+ * stepbyStepReport Plugin: Disabled screenshots after test has failed. See #3119 by @ioannisChalkias
55
+
56
+
57
+ ## 3.1.3
58
+
59
+ 🛩️ Features:
60
+
61
+ * BDD Improvement. Added `DataTableArgument` class to work with table data structures.
62
+
63
+ ```js
64
+ const { DataTableArgument } = require('codeceptjs');
65
+ //...
66
+ Given('I have an employee card', (table) => {
67
+ const dataTableArgument = new DataTableArgument(table);
68
+ const hashes = dataTableArgument.hashes();
69
+ // hashes = [{ name: 'Harry', surname: 'Potter', position: 'Seeker' }];
70
+ const rows = dataTableArgument.rows();
71
+ // rows = [['Harry', 'Potter', Seeker]];
72
+ }
73
+ ```
74
+ See updated [BDD section](https://codecept.io/bdd/) for more API options. Thanks to @EgorBodnar
75
+
76
+ * Support `cjs` file extensions for config file: `codecept.conf.cjs`. See #3052 by @kalvenschraut
77
+ * API updates: Added `test.file` and `suite.file` properties to `test` and `suite` objects to use in helpers and plugins.
78
+
79
+ 🐛 Bugfixes:
80
+
81
+ * [Playwright] Fixed resetting `test.artifacts` for failing tests. See #3033 by @jancorvus. Fixes #3032
82
+ * [Playwright] Apply `basicAuth` credentials to all opened browser contexts. See #3036 by @nikocanvacom. Fixes #3035
83
+ * [WebDriver] Updated `webdriverio` default version to `^6.12.1`. See #3043 by @sridhareaswaran
84
+ * [Playwright] `I.haveRequestHeaders` affects all tabs. See #3049 by @jancorvus
85
+ * BDD: Fixed unhandled empty feature files. Fix #3046 by @abhimanyupandian
86
+ * Fixed `RangeError: Invalid string length` in `recorder.js` when running huge amount of tests.
87
+ * [Appium] Fixed definitions for `touchPerform`, `hideDeviceKeyboard`, `removeApp` by @mirao
88
+
89
+ 📖 Documentation:
90
+
91
+ * Added Testrail reporter [Reports Docs](https://codecept.io/reports/#testrail)
92
+
93
+
94
+ ## 3.1.2
95
+
96
+ 🛩️ Features:
97
+
98
+ * Added `coverage` plugin to generate code coverage for Playwright & Puppeteer. By @anirudh-modi
99
+ * Added `subtitle` plugin to generate subtitles for videos recorded with Playwright. By @anirudh-modi
100
+ * Configuration: `config.tests` to accept array of file patterns. See #2994 by @monsteramba
101
+
102
+ ```js
103
+ exports.config = {
104
+ tests: ['./*_test.js','./sampleTest.js'],
105
+ // ...
106
+ }
107
+ ```
108
+ * Notification is shown for test files without `Feature()`. See #3011 by @PeterNgTr
109
+
110
+ 🐛 Bugfixes:
111
+
112
+ * [Playwright] Fixed #2986 error is thrown when deleting a missing video. Fix by @hatufacci
113
+ * Fixed false positive result when invalid function is called in a helper. See #2997 by @abhimanyupandian
114
+ * [Appium] Removed full page mode for `saveScreenshot`. See #3002 by @nlespiaucq
115
+ * [Playwright] Fixed #3003 saving trace for a test with a long name. Fix by @hatufacci
116
+
117
+ 🎱 Other:
118
+
119
+ * Deprecated `puppeteerCoverage` plugin in favor of `coverage` plugin.
120
+
1
121
  ## 3.1.1
2
122
 
3
123
  * [Appium] Fixed #2759
package/README.md CHANGED
@@ -29,7 +29,7 @@ Scenario('check Welcome page on site', ({ I }) => {
29
29
 
30
30
  CodeceptJS tests are:
31
31
 
32
- * **Synchronous**. You don't need to care about callbacks, or promises, test scenarios are linear, your test should be too.
32
+ * **Synchronous**. You don't need to care about callbacks or promises or test scenarios which are linear. But, your tests should be linear.
33
33
  * Written from **user's perspective**. Every action is a method of `I`. That makes test easy to read, write and maintain even for non-tech persons.
34
34
  * Backend **API agnostic**. We don't know which WebDriver implementation is running this test. We can easily switch from WebDriverIO to Protractor or PhantomJS.
35
35
 
@@ -38,11 +38,10 @@ CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently C
38
38
  * [**Playwright**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Playwright.md) - is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.
39
39
  * [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.
40
40
  * [**WebDriver**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) - uses [webdriverio](http://webdriver.io/) to run tests via WebDriver protocol.
41
- * [**Protractor**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Protractor.md) - helper empowered by [Protractor](http://protractortest.org/) to run tests via WebDriver protocol.
42
41
  * [**TestCafe**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/TestCafe.md) - cheap and fast cross-browser test automation.
43
42
  * [**Nightmare**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Nightmare.md) - uses Electron and NightmareJS to run tests.
44
43
  * [**Appium**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Appium.md) - for **mobile testing** with Appium
45
- * [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - This is a wrapper on top of Detox library, aimied to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially good for React Native apps.
44
+ * [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.
46
45
 
47
46
  And more to come...
48
47
 
package/bin/codecept.js CHANGED
@@ -105,6 +105,7 @@ program.command('run [test]')
105
105
  .option('-c, --config [file]', 'configuration file to be used')
106
106
  .option('--features', 'run only *.feature files and skip tests')
107
107
  .option('--tests', 'run only JS test files and skip features')
108
+ .option('--no-timeouts', 'disable all timeouts')
108
109
  .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
109
110
 
110
111
  // mocha options
package/docs/advanced.md CHANGED
@@ -100,7 +100,7 @@ Scenario('update user profile', ({ }) => {
100
100
  All tests with `@tag` could be executed with `--grep @tag` option.
101
101
 
102
102
  ```sh
103
- codeceptjs run --grep @slow
103
+ npx codeceptjs run --grep @slow
104
104
  ```
105
105
 
106
106
  Use regex for more flexible filtering:
@@ -119,24 +119,30 @@ CodeceptJS provides a debug mode in which additional information is printed.
119
119
  It can be turned on with `--debug` flag.
120
120
 
121
121
  ```sh
122
- codeceptjs run --debug
122
+ npx codeceptjs run --debug
123
123
  ```
124
124
 
125
125
  to receive even more information turn on `--verbose` flag:
126
126
 
127
127
  ```sh
128
- codeceptjs run --verbose
128
+ npx codeceptjs run --verbose
129
129
  ```
130
130
 
131
- And don't forget that you can pause execution and enter **interactive console** mode by calling `pause()` inside your test.
131
+ > You can pause execution and enter **interactive console** mode by calling `pause()` inside your test.
132
132
 
133
- For advanced debugging use NodeJS debugger. In WebStorm IDE:
133
+ To see a complete internal debug of CodeceptJS use `DEBUG` env variable:
134
+
135
+ ```sh
136
+ DEBUG=codeceptjs:* npx codeceptjs run
137
+ ```
138
+
139
+ For an interactive debugging use NodeJS debugger. In **WebStorm**:
134
140
 
135
141
  ```sh
136
142
  node $NODE_DEBUG_OPTION ./node_modules/.bin/codeceptjs run
137
143
  ```
138
144
 
139
- For Visual Studio Code, add the following configuration in launch.json:
145
+ For **Visual Studio Code**, add the following configuration in launch.json:
140
146
 
141
147
  ```json
142
148
  {
@@ -180,29 +186,99 @@ You can use this options for build your own [plugins](https://codecept.io/hooks/
180
186
  });
181
187
  ```
182
188
 
183
- ### Timeout
189
+ ### Timeout <Badge text="Updated in 3.2" type="warning"/>
184
190
 
185
- By default there is no timeout for tests, however you can change this value for a specific suite:
191
+ Tests can get stuck due to various reasons such as network connection issues, crashed browser, etc.
192
+ This can make tests process hang. To prevent these situations timeouts can be used. Timeouts can be set explicitly for flaky parts of code, or implicitly in a config.
193
+
194
+ > Previous timeout implementation was disabled as it had no effect when dealing with steps and promises.
195
+
196
+ ### Steps Timeout
197
+
198
+ It is possible to limit a step execution to specified time with `I.limitTime` command.
199
+ It will set timeout in seconds for the next executed step:
186
200
 
187
201
  ```js
188
- Feature('Stop me').timeout(5000); // set timeout to 5s
202
+ // limit clicking to 5 seconds
203
+ I.limitTime(5).click('Link')
189
204
  ```
190
205
 
191
- or for the test:
206
+ It is possible to set a timeout for all steps implicitly (except waiters) using [stepTimeout plugin](/plugins/#steptimeout).
207
+
208
+ ### Tests Timeout
209
+
210
+ Test timeout can be set in seconds via Scenario options:
192
211
 
193
212
  ```js
194
- // set timeout to 1s
195
- Scenario("Stop me faster",({ I }) => {
196
- // test goes here
197
- }).timeout(1000);
213
+ // limit test to 20 seconds
214
+ Scenario('slow test that should be stopped', { timeout: 20 }, ({ I }) => {
215
+ // ...
216
+ })
217
+ ```
198
218
 
199
- // alternative
200
- Scenario("Stop me faster", {timeout: 1000},({ I }) => {});
219
+ This timeout can be set globally in `codecept.conf.js` in seconds:
201
220
 
202
- // disable timeout for this scenario
203
- Scenario("Don't stop me", {timeout: 0},({ I }) => {});
221
+ ```js
222
+ exports.config = {
223
+
224
+ // each test must not run longer than 5 mins
225
+ timeout: 300,
226
+
227
+ }
204
228
  ```
205
229
 
230
+ ### Suites Timeout
231
+
232
+ A timeout for a group of tests can be set on Feature level via options.
233
+
234
+ ```js
235
+ // limit all tests in this suite to 30 seconds
236
+ Feature('flaky tests', { timeout: 30 })
237
+ ```
238
+
239
+ ### Sum Up
240
+
241
+ Let's list all available timeout options.
242
+
243
+ Timeouts can be set globally in config:
244
+
245
+ ```js
246
+ // in codecept.confg.js:
247
+ { // ...
248
+ timeout: 30, // limit all tests in all suites to 30 secs
249
+
250
+ plugins: {
251
+ stepTimeout: {
252
+ enabled: true,
253
+ timeout: 10, // limit all steps except waiters to 10 secs
254
+ }
255
+ }
256
+ }
257
+
258
+ ```
259
+
260
+ or inside a test file:
261
+
262
+ ```js
263
+ // limit all tests in this suite to 10 secs
264
+ Feature('tests with timeout', { timeout: 10 });
265
+
266
+ // limit this test to 20 secs
267
+ Scenario('a test with timeout', { timeout: 20 }, ({ I }) => {
268
+ // limit step to 5 seconds
269
+ I.limitTime(5).click('Link');
270
+ });
271
+ ```
272
+
273
+ Global timeouts will be overridden by explicit timeouts of a test or steps.
274
+
275
+ ### Disable Timeouts
276
+
277
+ To execute tests ignoring all timeout settings use `--no-timeouts` option:
278
+
279
+ ```
280
+ npx codeceptjs run --no-timeouts
281
+ ```
206
282
 
207
283
  ## Dynamic Configuration
208
284
 
@@ -249,45 +325,3 @@ Please note that some config changes can't be applied on the fly. For instance,
249
325
 
250
326
  Configuration changes will be reverted after a test or a suite.
251
327
 
252
-
253
- ### Rerunning Flaky Tests Multiple Times <Badge text="Since 2.4" type="warning"/>
254
-
255
- End to end tests can be flaky for various reasons. Even when we can't do anything to solve this problem it we can do next two things:
256
-
257
- * Detect flaky tests in our suite
258
- * Fix flaky tests by rerunning them.
259
-
260
- Both tasks can be achieved with [`run-rerun` command](/commands/#run-rerun) which runs tests multiple times until all tests are passed.
261
-
262
- You should set min and max runs boundaries so when few tests fail in a row you can rerun them until they are succeeded.
263
-
264
- ```js
265
- // inside to codecept.conf.js
266
- exports.config = { // ...
267
- rerun: {
268
- // run 4 times until 1st success
269
- minSuccess: 1,
270
- maxReruns: 4,
271
- }
272
- }
273
- ```
274
-
275
- If you want to check all your tests for stability you can set high boundaries for minimal success:
276
-
277
- ```js
278
- // inside to codecept.conf.js
279
- exports.config = { // ...
280
- rerun: {
281
- // run all tests must pass exactly 5 times
282
- minSuccess: 5,
283
- maxReruns: 5,
284
- }
285
- }
286
- ```
287
-
288
- Now execute tests with `run-rerun` command:
289
-
290
- ```
291
- npx codeceptjs run-rerun
292
- ```
293
-
package/docs/basics.md CHANGED
@@ -108,7 +108,7 @@ I.seeElement({name: 'password'});
108
108
  I.seeElement({react: 'user-profile', props: {name: 'davert'}});
109
109
  ```
110
110
 
111
- In [mobile testing](http://codecept.io/mobile/#locating-elements) you can use `~` to specify the accessibility id to locate an element. In web application you can locate elements by their `aria-label` value.
111
+ In [mobile testing](https://codecept.io/mobile/#locating-elements) you can use `~` to specify the accessibility id to locate an element. In web application you can locate elements by their `aria-label` value.
112
112
 
113
113
  ```js
114
114
  // locate element by [aria-label] attribute in web
package/docs/bdd.md CHANGED
@@ -264,8 +264,10 @@ You can also use the `parse()` method to obtain an object that allow you to get
264
264
  - `raw()` - returns the table as a 2-D array
265
265
  - `rows()` - returns the table as a 2-D array, without the first row
266
266
  - `hashes()` - returns an array of objects where each row is converted to an object (column header is the key)
267
+ - `rowsHash()` - returns an object where each row corresponds to an entry(first column is the key, second column is the value)
268
+ - `transpose()` - transpose the data, returns nothing. To work with the transposed table use the methods above.
267
269
 
268
- If we use hashes() with the previous exemple :
270
+ If we use hashes() with the previous example :
269
271
 
270
272
  ```js
271
273
  Given('I have products in my cart', (table) => { // eslint-disable-line
@@ -281,7 +283,59 @@ Given('I have products in my cart', (table) => { // eslint-disable-line
281
283
  }
282
284
  });
283
285
  ```
286
+ Examples of tables using:
284
287
 
288
+ ```gherkin
289
+ Given I have a short employees card
290
+ | Harry | Potter |
291
+ | Chuck | Norris |
292
+ ```
293
+ ```js
294
+ const { DataTableArgument } = require('codeceptjs');
295
+ //...
296
+ Given('I have a short employees card', (table) => {
297
+ const dataTableArgument = new DataTableArgument(table);
298
+ const raw = dataTableArgument.raw();
299
+ // row = [['Harry', 'Potter'], ['Chuck', 'Norris']]
300
+ dataTableArgument.transpose();
301
+ const transposedRaw = dataTableArgument.raw();
302
+ // transposedRaw = [['Harry', 'Chuck'], ['Potter', 'Norris']];
303
+ }
304
+ );
305
+ ```
306
+ ```gherkin
307
+ Given I have an employee card
308
+ | name | surname | position |
309
+ | Harry | Potter | Seeker |
310
+ ```
311
+ ```js
312
+ const { DataTableArgument } = require('codeceptjs');
313
+ //...
314
+ Given('I have an employee card', (table) => {
315
+ const dataTableArgument = new DataTableArgument(table);
316
+ const hashes = dataTableArgument.hashes();
317
+ // hashes = [{ name: 'Harry', surname: 'Potter', position: 'Seeker' }];
318
+ const rows = dataTableArgument.rows();
319
+ // rows = [['Harry', 'Potter', Seeker]];
320
+ }
321
+ );
322
+ ```
323
+ ```gherkin
324
+ Given I have a formatted employee card
325
+ | name | Harry |
326
+ | surname | Potter |
327
+ | position | Seeker |
328
+ ```
329
+ ```js
330
+ const { DataTableArgument } = require('codeceptjs');
331
+ //...
332
+ Given('I have a formatted employee card', (table) => {
333
+ const dataTableArgument = new DataTableArgument(table);
334
+ const rawHash = dataTableArgument.rowsHash();
335
+ // rawHash = { name: 'Harry', surname: 'Potter', position: 'Seeker' };
336
+ }
337
+ );
338
+ ```
285
339
  ### Examples
286
340
 
287
341
  In case scenarios represent the same logic but differ on data, we can use *Scenario Outline* to provide different examples for the same behavior. Scenario outline is just like a basic scenario with some values replaced with placeholders, which are filled from a table. Each set of values is executed as a different test.
@@ -481,10 +481,11 @@ class Appium extends Webdriver {
481
481
  * ```js
482
482
  * I.removeApp('appName', 'com.example.android.apis');
483
483
  * ```
484
- * @param {string} appId
485
- * @param {string} bundleId String ID of bundle
486
484
  *
487
485
  * Appium: support only Android
486
+ *
487
+ * @param {string} appId
488
+ * @param {string} [bundleId] ID of bundle
488
489
  */
489
490
  async removeApp(appId, bundleId) {
490
491
  onlyForApps.call(this, 'Android');
@@ -820,9 +821,10 @@ class Appium extends Webdriver {
820
821
  * I.hideDeviceKeyboard('pressKey', 'Done');
821
822
  * ```
822
823
  *
823
- * @param {'tapOutside' | 'pressKey'} strategy desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
824
- *
825
824
  * Appium: support Android and iOS
825
+ *
826
+ * @param {'tapOutside' | 'pressKey'} [strategy] Desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
827
+ * @param {string} [key] Optional key
826
828
  */
827
829
  async hideDeviceKeyboard(strategy, key) {
828
830
  onlyForApps.call(this);
@@ -1162,6 +1164,8 @@ class Appium extends Webdriver {
1162
1164
  * ```
1163
1165
  *
1164
1166
  * Appium: support Android and iOS
1167
+ *
1168
+ * @param {Array} actions Array of touch actions
1165
1169
  */
1166
1170
  async touchPerform(actions) {
1167
1171
  onlyForApps.call(this);
@@ -1551,6 +1555,20 @@ class Appium extends Webdriver {
1551
1555
  return super.grabValueFrom(parseLocator.call(this, locator));
1552
1556
  }
1553
1557
 
1558
+ /**
1559
+ * Saves a screenshot to ouput folder (set in codecept.json or codecept.conf.js).
1560
+ * Filename is relative to output folder.
1561
+ *
1562
+ * ```js
1563
+ * I.saveScreenshot('debug.png');
1564
+ * ```
1565
+ *
1566
+ * @param {string} fileName file name to save.
1567
+ */
1568
+ async saveScreenshot(fileName) {
1569
+ return super.saveScreenshot(fileName, false);
1570
+ }
1571
+
1554
1572
  /**
1555
1573
  * Scroll element into viewport.
1556
1574
  *
@@ -91,6 +91,7 @@ class FileSystem extends Helper {
91
91
  * I.amInPath('output/downloads');
92
92
  * I.seeFileNameMatching('.pdf');
93
93
  * ```
94
+ * @param {string} text
94
95
  */
95
96
  seeFileNameMatching(text) {
96
97
  assert.ok(
@@ -80,6 +80,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
80
80
  * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
81
81
  * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
82
82
  * * `userAgent`: (optional) user-agent string.
83
+ * * `locale`: (optional) locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
83
84
  * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
84
85
  * * `chromium`: (optional) pass additional chromium options
85
86
  * * `electron`: (optional) pass additional electron options
@@ -197,6 +198,19 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
197
198
  * }
198
199
  * ```
199
200
  *
201
+ * #### Example #7: Launch test with a specifc user locale
202
+ *
203
+ * ```js
204
+ * {
205
+ * helpers: {
206
+ * Playwright : {
207
+ * url: "http://localhost",
208
+ * locale: "fr-FR",
209
+ * }
210
+ * }
211
+ * }
212
+ * ```
213
+ *
200
214
  * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
201
215
  *
202
216
  * ## Access From Helpers
@@ -341,19 +355,10 @@ class Playwright extends Helper {
341
355
  }
342
356
 
343
357
  async _before() {
344
- recorder.retry({
345
- retries: 5,
346
- when: err => {
347
- if (!err || typeof (err.message) !== 'string') {
348
- return false;
349
- }
350
- // ignore context errors
351
- return err.message.includes('context');
352
- },
353
- });
354
358
  if (this.options.restart && !this.options.manualStart) await this._startBrowser();
355
359
  if (!this.isRunning && !this.options.manualStart) await this._startBrowser();
356
360
 
361
+ this.isAuthenticated = false;
357
362
  if (this.isElectron) {
358
363
  this.browserContext = this.browser.context();
359
364
  } else if (this.userDataDir) {
@@ -364,8 +369,14 @@ class Playwright extends Helper {
364
369
  acceptDownloads: true,
365
370
  ...this.options.emulate,
366
371
  };
372
+ if (this.options.basicAuth) {
373
+ contextOptions.httpCredentials = this.options.basicAuth;
374
+ this.isAuthenticated = true;
375
+ }
367
376
  if (this.options.recordVideo) contextOptions.recordVideo = this.options.recordVideo;
368
377
  if (this.storageState) contextOptions.storageState = this.storageState;
378
+ if (this.options.userAgent) contextOptions.userAgent = this.options.userAgent;
379
+ if (this.options.locale) contextOptions.locale = this.options.locale;
369
380
  this.browserContext = await this.browser.newContext(contextOptions); // Adding the HTTPSError ignore in the context so that we can ignore those errors
370
381
  }
371
382
 
@@ -564,9 +575,14 @@ class Playwright extends Helper {
564
575
  this.page = page;
565
576
  if (!page) return;
566
577
  page.setDefaultNavigationTimeout(this.options.getPageTimeout);
578
+
579
+ page.on('crash', async () => {
580
+ console.log('ERROR: Page has crashed, closing page!');
581
+ await page.close();
582
+ });
567
583
  this.context = await this.page;
568
584
  this.contextLocator = null;
569
- if (this.config.browser === 'chrome') {
585
+ if (this.options.browser === 'chrome') {
570
586
  await page.bringToFront();
571
587
  }
572
588
  }
@@ -730,9 +746,9 @@ class Playwright extends Helper {
730
746
  url = this.options.url + url;
731
747
  }
732
748
 
733
- if (this.config.basicAuth && (this.isAuthenticated !== true)) {
749
+ if (this.options.basicAuth && (this.isAuthenticated !== true)) {
734
750
  if (url.includes(this.options.url)) {
735
- await this.browserContext.setHTTPCredentials(this.config.basicAuth);
751
+ await this.browserContext.setHTTPCredentials(this.options.basicAuth);
736
752
  this.isAuthenticated = true;
737
753
  }
738
754
  }
@@ -795,7 +811,7 @@ class Playwright extends Helper {
795
811
  if (!customHeaders) {
796
812
  throw new Error('Cannot send empty headers.');
797
813
  }
798
- return this.page.setExtraHTTPHeaders(customHeaders);
814
+ return this.browserContext.setExtraHTTPHeaders(customHeaders);
799
815
  }
800
816
 
801
817
  /**
@@ -2565,12 +2581,17 @@ class Playwright extends Helper {
2565
2581
 
2566
2582
  async _failed(test) {
2567
2583
  await this._withinEnd();
2584
+
2585
+ if (!test.artifacts) {
2586
+ test.artifacts = {};
2587
+ }
2588
+
2568
2589
  if (this.options.recordVideo && this.page.video()) {
2569
2590
  test.artifacts.video = await this.page.video().path();
2570
2591
  }
2571
2592
 
2572
2593
  if (this.options.trace) {
2573
- const path = `${global.output_dir}/trace/${clearString(test.title)}.zip`;
2594
+ const path = `${global.output_dir}/trace/${clearString(test.title).slice(0, 255)}.zip`;
2574
2595
  await this.browserContext.tracing.stop({ path });
2575
2596
  test.artifacts.trace = path;
2576
2597
  }
@@ -2581,7 +2602,7 @@ class Playwright extends Helper {
2581
2602
  if (this.options.keepVideoForPassedTests) {
2582
2603
  test.artifacts.video = await this.page.video().path();
2583
2604
  } else {
2584
- this.page.video().delete();
2605
+ this.page.video().delete().catch(e => {});
2585
2606
  }
2586
2607
  }
2587
2608
 
@@ -2946,11 +2967,11 @@ class Playwright extends Helper {
2946
2967
  }
2947
2968
 
2948
2969
  /**
2949
- * Waits for a network request.
2970
+ * Waits for a network response.
2950
2971
  *
2951
2972
  * ```js
2952
2973
  * I.waitForResponse('http://example.com/resource');
2953
- * I.waitForResponse(request => request.url() === 'http://example.com' && request.method() === 'GET');
2974
+ * I.waitForResponse(response => response.url() === 'https://example.com' && response.status() === 200);
2954
2975
  * ```
2955
2976
  *
2956
2977
  * @param {string|function} urlOrPredicate
@@ -3059,26 +3080,6 @@ class Playwright extends Helper {
3059
3080
  return this.page.waitForNavigation(opts);
3060
3081
  }
3061
3082
 
3062
- /**
3063
- * Waits for a function to return true (waits for 1sec by default).
3064
- *
3065
- * ```js
3066
- * I.waitUntil(() => window.requests == 0);
3067
- * I.waitUntil(() => window.requests == 0, 5);
3068
- * ```
3069
- *
3070
- * @param {function|string} fn function which is executed in browser context.
3071
- * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
3072
- * @param {string} [timeoutMsg=''] message to show in case of timeout fail.
3073
- * @param {?number} [interval=null]
3074
- */
3075
- async waitUntil(fn, sec = null) {
3076
- console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
3077
- const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
3078
- const context = await this._getContext();
3079
- return context.waitForFunction(fn, { timeout: waitTimeout });
3080
- }
3081
-
3082
3083
  async waitUntilExists(locator, sec) {
3083
3084
  console.log(`waitUntilExists deprecated:
3084
3085
  * use 'waitForElement' to wait for element to be attached
@@ -3541,13 +3542,10 @@ async function targetCreatedHandler(page) {
3541
3542
  });
3542
3543
  });
3543
3544
  page.on('console', (msg) => {
3544
- this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg._text || '') + msg.args().join(' '));
3545
+ this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg.text && msg.text() || msg._text || '') + msg.args().join(' '));
3545
3546
  consoleLogStore.add(msg);
3546
3547
  });
3547
3548
 
3548
- if (this.options.userAgent) {
3549
- await page.setUserAgent(this.options.userAgent);
3550
- }
3551
3549
  if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
3552
3550
  await page.setViewportSize(parseWindowSize(this.options.windowSize));
3553
3551
  }