codeceptjs 3.4.0 → 3.5.0

package/docs/helpers/Puppeteer.md

@@ -56,6 +56,7 @@ Type: [object][4]
 -   `manualStart` **[boolean][17]?** do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
 -   `browser` **[string][6]?** can be changed to `firefox` when using [puppeteer-firefox][2].
 -   `chrome` **[object][4]?** pass additional [Puppeteer run options][22].
+-   `highlightElement` **[boolean][17]?** highlight the interacting elements
 
 
 
@@ -296,6 +297,8 @@ Field is located by name, label, CSS or XPath
 
 ```js
 I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
 ```
 
 #### Parameters
@@ -1786,6 +1789,9 @@ I.type('4141555311111111', 100);
 
 // passing in an array
 I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
 ```
 
 #### Parameters

package/docs/helpers/REST.md

@@ -41,7 +41,8 @@ Type: [object][4]
       endpoint: 'http://site.com/api',
       prettyPrintJson: true,
       onRequest: (request) => {
-      request.headers.auth = '123';
+        request.headers.auth = '123';
+      }
     }
   }
 }
@@ -114,7 +115,7 @@ I.sendDeleteRequest('/api/users/1');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default, it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -129,7 +130,7 @@ I.sendGetRequest('/api/users.json');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default, it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 
@@ -166,8 +167,8 @@ I.sendPostRequest('/api/users.json', secret({ "email": "user@user.com" }));
 #### Parameters
 
 -   `url` **any** 
--   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][4]** the headers object to be sent. By default it is sent as an empty object 
+-   `payload` **any** the payload to be sent. By default, it is sent as an empty object 
+-   `headers` **[object][4]** the headers object to be sent. By default, it is sent as an empty object 
 
 Returns **[Promise][2]<any>** response
 

package/docs/helpers/TestCafe.md

@@ -116,6 +116,8 @@ Field is located by name, label, CSS or XPath
 
 ```js
 I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
 ```
 
 #### Parameters

package/docs/helpers/WebDriver.md

@@ -27,7 +27,7 @@ Type: [object][16]
 ### Properties
 
 -   `url` **[string][17]** base url of website to be tested.
--   `browser` **[string][17]** browser in which to perform testing.
+-   `browser` **[string][17]** Browser in which to perform testing.
 -   `basicAuth` **[string][17]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
 -   `host` **[string][17]?** WebDriver host to connect.
 -   `port` **[number][20]?** WebDriver port to connect.
@@ -45,6 +45,7 @@ Type: [object][16]
 -   `desiredCapabilities` **[object][16]?** Selenium's [desired capabilities][6].
 -   `manualStart` **[boolean][29]?** do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
 -   `timeouts` **[object][16]?** [WebDriver timeouts][34] defined as hash.
+-   `highlightElement` **[boolean][29]?** highlight the interacting elements
 
 
 
@@ -382,7 +383,7 @@ this.helpers['WebDriver']._locate({name: 'password'}).then //...
 
 ### _locateCheckable
 
-Find a checkbox by providing human readable text:
+Find a checkbox by providing human-readable text:
 
 ```js
 this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').then // ...
@@ -394,7 +395,7 @@ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').
 
 ### _locateClickable
 
-Find a clickable element by providing human readable text:
+Find a clickable element by providing human-readable text:
 
 ```js
 const els = await this.helpers.WebDriver._locateClickable('Next page');
@@ -408,7 +409,7 @@ const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages')
 
 ### _locateFields
 
-Find field elements by providing human readable text:
+Find field elements by providing human-readable text:
 
 ```js
 this.helpers['WebDriver']._locateFields('Your email').then // ...
@@ -464,6 +465,8 @@ Field is located by name, label, CSS or XPath
 
 ```js
 I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
 ```
 
 #### Parameters
@@ -1985,6 +1988,9 @@ I.type('4141555311111111', 100);
 
 // passing in an array
 I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
 ```
 
 #### Parameters

package/docs/mobile.md

@@ -45,22 +45,69 @@ To install Appium use npm:
 npm i -g appium
 ```
 
+To use Appium 2.x:
+```sh
+npm i -g appium@next
+```
+Appium 2x (still beta) reenvisions Appium as a platform where “drivers” and “plugins” can be easily created and shared independently.
+Install an Appium driver and its dependencies
+To install the Appium driver and its dependencies, we'll be using the uiautomator2 (Android), XCUITest (iOS) drivers.
+
+```
+appium driver install xcuitest
+appium driver install uiautomator2
+```
+To make sure that all the drivers are installed successfully, run the following command:
+
+```
+appium driver list
+
+tth~$appium driver list            
+✔ Listing available drivers
+- espresso@2.17.0 [installed (NPM)]
+- uiautomator2@2.12.6 [installed (NPM)]
+- xcuitest@4.19.1 [installed (NPM)]
+- mac2 [not installed]
+- safari [not installed]
+- gecko [not installed]
+- chromium [not installed]
+```
+
 Then you need to prepare application for execution.
 It should be packed into apk (for Android) or .ipa (for iOS) or zip.
 
-Next, is to launch the emulator or connect physical device.
+Next, is to launch the emulator or connect a physical device.
 Once they are prepared, launch Appium:
 
 ```sh
 appium
 ```
 
+To use Appium 2.x:
+```sh
+tth~$npx appium --base-path=/wd/hub
+[Appium] Welcome to Appium v2.0.0-beta.57 (REV 3e675c32ae71dc0b00749d5d29213e2ea5b53c5b)
+[Appium] Non-default server args:
+[Appium] {
+[Appium]   basePath: '/wd/hub'
+[Appium] }
+[Appium] Attempting to load driver espresso...
+[debug] [Appium] Requiring driver at /Users/trung-thanh/Desktop/thanh-nguyen/task2/node_modules/appium-espresso-driver
+[Appium] Attempting to load driver uiautomator2...
+[debug] [Appium] Requiring driver at /Users/trung-thanh/Desktop/thanh-nguyen/task2/node_modules/appium-uiautomator2-driver
+[Appium] Appium REST http interface listener started on 0.0.0.0:4723
+[Appium] Available drivers:
+[Appium]   - espresso@2.17.0 (automationName 'Espresso')
+[Appium]   - uiautomator2@2.12.6 (automationName 'UiAutomator2')
+[Appium] No plugins have been installed. Use the "appium plugin" command to install the one(s) you want to use.
+```
+
 To run mobile test you need either an device emulator (available with Android SDK or iOS), real device connected for mobile testing. Alternatively, you may execute Appium with device emulator inside Docker container.
 
 CodeceptJS should be installed with webdriverio support:
 
 ```bash
-npm install codeceptjs webdriverio --save
+npm install codeceptjs webdriverio@8.6.3 --save
 ```
 
 ## Configuring

package/docs/parallel.md

@@ -32,6 +32,62 @@ By default the tests are assigned one by one to the available workers this may l
 npx codeceptjs run-workers --suites 2
 ```
 
+## Parallel Execution by Workers on Multiple Browsers
+
+To run tests in parallel across multiple browsers, modify your `codecept.conf.js` file to configure multiple browsers on which you want to run your tests and your tests will run across multiple browsers. 
+
+Start with modifying the `codecept.conf.js` file. Add multiple key inside the config which will be used to configure multiple profiles. 
+
+```
+exports.config = {
+  helpers: {
+    WebDriver: {
+      url: 'http://localhost:3000',
+      desiredCapabilties: {}
+    }
+  },
+  multiple: {
+    profile1: {
+      browsers: [
+        {
+          browser: "firefox",
+          desiredCapabilties: {
+            // override capabilties related to firefox
+          }
+        },
+        {
+          browser: "chrome",
+          desiredCapabilties: {
+            // override capabilties related to chrome
+          }
+        }
+      ]
+    }, 
+    profile2: {
+      browsers: [
+        {
+          browser: "safari",
+          desiredCapabilties: {
+            // override capabilties related to safari
+          }
+        }
+      ]
+    }
+  }
+};
+```
+To trigger tests on all the profiles configured, you can use the following command: 
+```
+npx codeceptjs run-workers 3 all -c codecept.conf.js
+```
+This will run your tests across all browsers configured from profile1 & profile2 on 3 workers.
+
+To trigger tests on specific profile, you can use the following command: 
+```
+npx codeceptjs run-workers 2 profile1 -c codecept.conf.js
+```
+This will run your tests across 2 browsers from profile1 on 2 workers.
+
 ## Custom Parallel Execution
 
 To get a full control of parallelization create a custom execution script to match your needs.

package/docs/plugins.md

@@ -479,6 +479,30 @@ I.click('=sign-up'); // matches => [data-qa=sign-up],[data-test=sign-up]
 
 -   `config`  
 
+## debugErrors
+
+Prints errors found in HTML code after each failed test.
+
+It scans HTML and searches for elements with error classes.
+If an element found prints a text from it to console and adds as artifact to the test.
+
+Enable this plugin in config:
+
+```js
+plugins: {
+ debugErrors: {
+  enabled: true,
+}
+```
+
+Additional config options:
+
+-   `errorClasses` - list of classes to search for errors (default: `['error', 'warning', 'alert', 'danger']`)
+
+### Parameters
+
+-   `config`   (optional, default `{}`)
+
 ## eachElement
 
 Provides `eachElement` global function to iterate over found elements to perform actions on them.
@@ -546,17 +570,15 @@ Returns **([Promise][7]<any> | [undefined][8])**
 
 ## fakerTransform
 
-Use the [faker.js][9] package to generate fake data inside examples on your gherkin tests
-
-![Faker.js][10]
+Use the `@faker-js/faker` package to generate fake data inside examples on your gherkin tests
 
 #### Usage
 
-To start please install `faker.js` package
+To start please install `@faker-js/faker` package
 
-    npm install -D faker
+    npm install -D @faker-js/faker
 
-    yarn add -D faker
+    yarn add -D @faker-js/faker
 
 Add this plugin to config file:
 
@@ -584,9 +606,45 @@ Scenario Outline: ...
 
 -   `config`  
 
+## heal
+
+Self-healing tests with OpenAI.
+
+This plugin is experimental and requires OpenAI API key.
+
+To use it you need to set OPENAI_API_KEY env variable and enable plugin inside condig.
+
+```js
+plugins: {
+  heal: {
+   enabled: true,
+  }
+}
+```
+
+More config options are available:
+
+-   `healLimit` - how many steps can be healed in a single test (default: 2)
+-   `healSteps` - which steps can be healed (default: all steps that interact with UI, see list below)
+
+Steps to heal:
+
+-   `click`
+-   `fillField`
+-   `appendField`
+-   `selectOption`
+-   `attachFile`
+-   `checkOption`
+-   `uncheckOption`
+-   `doubleClick`
+
+### Parameters
+
+-   `config`   (optional, default `{}`)
+
 ## pauseOnFail
 
-Automatically launches [interactive pause][11] when a test fails.
+Automatically launches [interactive pause][9] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -769,14 +827,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][12] plugin automatically starts browsers and video recording.
+[Selenoid][10] plugin automatically starts browsers and video recording.
 Works with WebDriver helper.
 
 ### Prerequisite
 
 This plugin **requires Docker** to be installed.
 
-> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][13] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][11] tool from Selenoid
 
 ### Usage
 
@@ -805,7 +863,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][14] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][12] and start Selenoid automatically.
 It will also create `browsers.json` file required by Selenoid.
 
 In automatic mode the latest version of browser will be used for tests. It is recommended to specify exact version of each browser inside `browsers.json` file.
@@ -817,10 +875,10 @@ In automatic mode the latest version of browser will be used for tests. It is re
 While this plugin can create containers for you for better control it is recommended to create and launch containers manually.
 This is especially useful for Continous Integration server as you can configure scaling for Selenoid containers.
 
-> Use [Selenoid Configuration Manager][13] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][11] to create and start containers semi-automatically.
 
 1.  Create `browsers.json` file in the same directory `codecept.conf.js` is located
-    [Refer to Selenoid documentation][15] to know more about browsers.json.
+    [Refer to Selenoid documentation][13] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -845,7 +903,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][16]
+Run the following command to create a container. To know more [refer here][14]
 
 ```bash
 docker create                                    \
@@ -878,7 +936,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 | enableVideo      | Enable video recording and use `video` folder of output (default: false)       |
 | enableLog        | Enable log recording and use `logs` folder of output (default: false)          |
 | deletePassed     | Delete video and logs of passed tests (default : true)                         |
-| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][17] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][15] to know more   |
 
 ### Parameters
 
@@ -886,7 +944,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 
 ## stepByStepReport
 
-![step-by-step-report][18]
+![step-by-step-report][16]
 
 Generates step by step report for a test.
 After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
@@ -1067,7 +1125,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][19].
+A complete list of all available services can be found on [webdriverio website][17].
 
 #### Setup
 
@@ -1079,7 +1137,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][20].
+Install `@wdio/selenium-standalone-service` package, as [described here][18].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1098,7 +1156,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][21].
+Install `@wdio/sauce-service` package, as [described here][19].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1144,28 +1202,24 @@ In the same manner additional services from webdriverio can be installed, enable
 
 [8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
 
-[9]: https://www.npmjs.com/package/faker
-
-[10]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
-
-[11]: /basics/#pause
+[9]: /basics/#pause
 
-[12]: https://aerokube.com/selenoid/
+[10]: https://aerokube.com/selenoid/
 
-[13]: https://aerokube.com/cm/latest/
+[11]: https://aerokube.com/cm/latest/
 
-[14]: https://hub.docker.com/u/selenoid
+[12]: https://hub.docker.com/u/selenoid
 
-[15]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[13]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[16]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[14]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[17]: https://docs.docker.com/engine/reference/commandline/create/
+[15]: https://docs.docker.com/engine/reference/commandline/create/
 
-[18]: https://codecept.io/img/codeceptjs-slideshow.gif
+[16]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[19]: https://webdriver.io
+[17]: https://webdriver.io
 
-[20]: https://webdriver.io/docs/selenium-standalone-service.html
+[18]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[21]: https://webdriver.io/docs/sauce-service.html
+[19]: https://webdriver.io/docs/sauce-service.html

package/docs/secrets.md

@@ -15,6 +15,12 @@ When executed it will be printed like this:
 ```
 I fill field "password" "*****"
 ```
+**Other Examples**
+```js
+I.fillField('password', secret('123456'));
+I.append('password', secret('123456'));
+I.type('password', secret('123456'));
+```
 
 For an object, which can be a payload to POST request, specify which fields should be masked:
 

package/docs/tutorial.md

@@ -1,11 +1,11 @@
 ---
 permalink: /tutorial
-title: CoeceptJS Complete Tutorial
+title: CodeceptJS Complete Tutorial
 ---
 
-**[CodeceptJS](https://codecept.io) is a popular open-source testing framework** for JavaScript. It is designed to simplify writing and maintain end-to-end tests for web applications, using a readable and intuitive syntax. To run tests in browser it uses **[Playwright](https://playwright.dev)** library from Microsoft.
+# Tutorial: Writing Tests for Checkout Page
 
-CodeceptJS was started in 2015 and is widely used by organizations of all sizes, from startups to large enterprises.
+**[CodeceptJS](https://codecept.io) is a popular open-source testing framework** for JavaScript. It is designed to simplify writing and maintain end-to-end tests for web applications, using a readable and intuitive syntax. To run tests in browser it uses **[Playwright](https://playwright.dev)** by default but ca execute tests via WebDriver, Puppeteer or Appium.
 
 ## Let's get CodeceptJS installed!
 
@@ -216,7 +216,7 @@ module.exports = {
 Feels really empty. What should we do about it? Should we write more code? No, we already have it. Let's copy code blocks from a test we have it and place them under a corredponnding function names:
 
 ```js
-connst { I } = inject();
+const { I } = inject();
 
 module.exports = {
 
@@ -266,6 +266,6 @@ By applying more and more cases you can test a website to all behaviors.
 
 ## Summary
 
-This was a deep dive! If you think on just starting test automation, CodeceptJS is the best choice for you as it uses native language to pass commands to browser. 
+If you think on just starting test automation, CodeceptJS is the best choice for you as it uses native language to pass commands to browser. 
 
 If you already skilled in JavaScript, with CodeceptJS you can focus on business level of your test, instead of writing code for browser. This way you can keep your tests stable and maintainable.

package/docs/webapi/appendField.mustache

@@ -3,6 +3,8 @@ Field is located by name, label, CSS or XPath
 
 ```js
 I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
 ```
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
 @param {string} value text value to append.

package/docs/webapi/type.mustache

@@ -11,6 +11,9 @@ I.type('4141555311111111', 100);
 
 // passing in an array
 I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
 ```
 
 @param {string|string[]} key or array of keys to type.