codeceptjs 3.4.1 → 3.5.1

package/CHANGELOG.md

@@ -1,3 +1,88 @@
+## 3.5.1
+
+🛩️ Features
+
+* [Puppeteer][WebDriver][TestCafe] Added methods by @KobeNguyenT in #3737 
+  * `blur`
+  * `focus`
+* Improved BDD output to print steps without `I.` commands` by @davertmik #3739
+* Improved `codecept init` setup for Electron tests by @KobeNguyenT. See #3733
+
+🐛 Bug Fixes
+
+* Fixed serializing of custom errors making tests stuck. Fix #3739 by @davertmik.
+
+📖 Documentation
+
+* Fixed Playwright docs by @Horsty80
+* Fixed ai docs by @ngraf 
+* Various fixes by @KobeNguyenT
+
+## 3.5.0
+
+🛩️ Features
+
+- **🪄 [AI Powered Test Automation](/ai)** - use OpenAI as a copilot for test automation. #3713 By @davertmik
+![](https://user-images.githubusercontent.com/220264/250418764-c382709a-3ccb-4eb5-b6bc-538f3b3b3d35.png)
+  * [AI guide](/ai) added
+  * added support for OpenAI in `pause()`
+  * added [`heal` plugin](/plugins#heal) for self-healing tests
+  * added [`OpenAI`](/helpers/openai) helper
+
+
+- [Playwright][Puppeteer][WebDriver] Highlight the interacting elements in debug mode or with `highlightElement` option set (#3672) - by @KobeNguyenT
+
+![](https://user-images.githubusercontent.com/220264/250415226-a7620418-56a4-4837-b790-b15e91e5d1f0.png)
+
+- [Playwright] Support for APIs in Playwright (#3665) - by Egor Bodnar
+  * `clearField` replaced to use new Playwright API
+  * `blur` added
+  * `focus` added
+
+- **[Added support for multiple browsers](/parallel#Parallel-Execution-by-Workers-on-Multiple-Browsers)** in `run-workers` (#3606) by @karanshah-browserstack :
+
+Multiple browsers configured as profiles:
+
+```js
+exports.config = {
+  helpers: {
+    WebDriver: {
+      url: 'http://localhost:3000',
+    }
+  },
+  multiple: {
+    profile1: {
+      browsers: [
+        {
+          browser: "firefox",
+        },
+        {
+          browser: "chrome",
+        }
+      ]
+    }, 
+```
+And executed via `run-workers` with `all` argument
+
+```
+npx codeceptjs run-workers 2 all
+```
+
+- [Appium] Add Appium v2 support (#3622) - by @KobeNguyenT
+- Improve `gpo` command to create page objects as modules or as classes (#3625) - by @KobeNguyenT
+- Added `emptyOutputFolder` config to clean up output before running tests (#3604) - by @KobeNguyenT
+- Add `secret()` function support to `append()` and `type()` (#3615) - by @anils92
+- [Playwright] Add `bypassCSP` option to helper's config (#3641) - by @KobeNguyenT
+- Print number of tests for each suite in dryRun (#3620) - by @KobeNguyenT
+
+🐛 Bug Fixes
+
+- Support `--grep` in dry-run command (#3673) - by @KobeNguyenT
+- Fix typings improvements in playwright (#3650) - by @KobeNguyenT
+- Fixed global retry #3667 by @KobeNguyenT
+- Fixed creating JavaScript test using "codeceptjs gt" (#3611) - by Jaromir Obr
+
+
 ## 3.4.1
 
 * Updated mocha to v 10.2. Fixes #3591

package/README.md

@@ -2,8 +2,8 @@
 
 
 
-[<img src="https://img.shields.io/badge/slack-@codeceptjs-purple.svg?logo=slack">](https://join.slack.com/t/codeceptjs/shared_invite/enQtMzA5OTM4NDM2MzA4LWE4MThhN2NmYTgxNTU5MTc4YzAyYWMwY2JkMmZlYWI5MWQ2MDM5MmRmYzZmYmNiNmY5NTAzM2EwMGIwOTNhOGQ) [<img src="https://img.shields.io/badge/discourse-codeceptjs-purple">](https://codecept.discourse.group) [![NPM version][npm-image]][npm-url]
-[![StandWithUkraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) 
+[<img src="https://img.shields.io/badge/slack-@codeceptjs-purple.svg?logo=slack">](https://join.slack.com/t/codeceptjs/shared_invite/enQtMzA5OTM4NDM2MzA4LWE4MThhN2NmYTgxNTU5MTc4YzAyYWMwY2JkMmZlYWI5MWQ2MDM5MmRmYzZmYmNiNmY5NTAzM2EwMGIwOTNhOGQ) [<img src="https://img.shields.io/badge/discourse-codeceptjs-purple">](https://codecept.discourse.group) [![NPM version][npm-image]][npm-url] [<img src="https://img.shields.io/badge/dockerhub-images-blue.svg?logo=codeceptjs">](https://hub.docker.com/r/codeceptjs/codeceptjs)
+[![AI features](https://img.shields.io/badge/AI-features?logo=openai&logoColor=white)](https://github.com/codeceptjs/CodeceptJS/edit/3.x/docs/ai.md) [![StandWithUkraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) 
 
 Build Status:
 
@@ -38,7 +38,7 @@ CodeceptJS tests are:
 * 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.
 * Backend **API agnostic**. We don't know which WebDriver implementation is running this test. We can easily switch from WebDriverIO to Protractor or PhantomJS.
 
-CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently CodeceptJS has these helpers:
+CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently, CodeceptJS has these helpers:
 
 * [**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.
 * [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.
@@ -56,8 +56,10 @@ CodeceptJS is a successor of [Codeception](http://codeception.com), a popular fu
 With CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be.
 You don't need to worry about asynchronous nature of NodeJS or about various APIs of Selenium, Puppeteer, Protractor, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
 
-## Features
 
+## Features
+ 
+* 🪄 **AI-powered** with GPT features to assist and heal failing tests
 * Based on [Mocha](https://mochajs.org/) testing framework.
 * Designed for scenario driven acceptance testing in BDD-style
 * Uses ES6 natively without transpiler.
@@ -294,7 +296,7 @@ Thanks all to those who are and will have contributing to this awesome project!
 
 [//]: contributor-faces
 <a href="https://github.com/DavertMik"><img src="https://avatars.githubusercontent.com/u/220264?v=4" title="DavertMik" width="80" height="80"></a>
-<a href="https://github.com/PeterNgTr"><img src="https://avatars.githubusercontent.com/u/7845001?v=4" title="PeterNgTr" width="80" height="80"></a>
+<a href="https://github.com/kobenguyent"><img src="https://avatars.githubusercontent.com/u/7845001?v=4" title="kobenguyent" width="80" height="80"></a>
 <a href="https://github.com/Vorobeyko"><img src="https://avatars.githubusercontent.com/u/11293201?v=4" title="Vorobeyko" width="80" height="80"></a>
 <a href="https://github.com/reubenmiller"><img src="https://avatars.githubusercontent.com/u/3029781?v=4" title="reubenmiller" width="80" height="80"></a>
 <a href="https://github.com/Arhell"><img src="https://avatars.githubusercontent.com/u/26163841?v=4" title="Arhell" width="80" height="80"></a>
@@ -307,22 +309,22 @@ Thanks all to those who are and will have contributing to this awesome project!
 <a href="https://github.com/nikocanvacom"><img src="https://avatars.githubusercontent.com/u/83254493?v=4" title="nikocanvacom" width="80" height="80"></a>
 <a href="https://github.com/elukoyanov"><img src="https://avatars.githubusercontent.com/u/11647141?v=4" title="elukoyanov" width="80" height="80"></a>
 <a href="https://github.com/gkushang"><img src="https://avatars.githubusercontent.com/u/3663389?v=4" title="gkushang" width="80" height="80"></a>
+<a href="https://github.com/actions-user"><img src="https://avatars.githubusercontent.com/u/65916846?v=4" title="actions-user" width="80" height="80"></a>
 <a href="https://github.com/tsuemura"><img src="https://avatars.githubusercontent.com/u/17092259?v=4" title="tsuemura" width="80" height="80"></a>
+<a href="https://github.com/EgorBodnar"><img src="https://avatars.githubusercontent.com/u/63167966?v=4" title="EgorBodnar" width="80" height="80"></a>
 <a href="https://github.com/VikalpP"><img src="https://avatars.githubusercontent.com/u/11846339?v=4" title="VikalpP" width="80" height="80"></a>
+<a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4" title="dependabot[bot]" width="80" height="80"></a>
 <a href="https://github.com/BorisOsipov"><img src="https://avatars.githubusercontent.com/u/6514276?v=4" title="BorisOsipov" width="80" height="80"></a>
 <a href="https://github.com/elaichenkov"><img src="https://avatars.githubusercontent.com/u/29764053?v=4" title="elaichenkov" width="80" height="80"></a>
 <a href="https://github.com/nitschSB"><img src="https://avatars.githubusercontent.com/u/39341455?v=4" title="nitschSB" width="80" height="80"></a>
 <a href="https://github.com/hubidu"><img src="https://avatars.githubusercontent.com/u/13134082?v=4" title="hubidu" width="80" height="80"></a>
 <a href="https://github.com/jploskonka"><img src="https://avatars.githubusercontent.com/u/669483?v=4" title="jploskonka" width="80" height="80"></a>
+<a href="https://github.com/ngraf"><img src="https://avatars.githubusercontent.com/u/7094389?v=4" title="ngraf" width="80" height="80"></a>
 <a href="https://github.com/maojunxyz"><img src="https://avatars.githubusercontent.com/u/28778042?v=4" title="maojunxyz" width="80" height="80"></a>
 <a href="https://github.com/abhimanyupandian"><img src="https://avatars.githubusercontent.com/u/36107381?v=4" title="abhimanyupandian" width="80" height="80"></a>
 <a href="https://github.com/martomo"><img src="https://avatars.githubusercontent.com/u/1850135?v=4" title="martomo" width="80" height="80"></a>
 <a href="https://github.com/denis-sokolov"><img src="https://avatars.githubusercontent.com/u/113721?v=4" title="denis-sokolov" width="80" height="80"></a>
 <a href="https://github.com/lennym"><img src="https://avatars.githubusercontent.com/u/117398?v=4" title="lennym" width="80" height="80"></a>
-<a href="https://github.com/petehouston"><img src="https://avatars.githubusercontent.com/u/9006720?v=4" title="petehouston" width="80" height="80"></a>
-<a href="https://github.com/Holorium"><img src="https://avatars.githubusercontent.com/u/10815542?v=4" title="Holorium" width="80" height="80"></a>
-<a href="https://github.com/jancorvus"><img src="https://avatars.githubusercontent.com/u/67001310?v=4" title="jancorvus" width="80" height="80"></a>
-<a href="https://github.com/ngraf"><img src="https://avatars.githubusercontent.com/u/7094389?v=4" title="ngraf" width="80" height="80"></a>
 
 [//]: contributor-faces
 

package/bin/codecept.js

@@ -130,7 +130,7 @@ program.command('run [test]')
   .option('--child <string>', 'option for child processes')
   .action(errorHandler(require('../lib/command/run')));
 
-program.command('run-workers <workers>')
+program.command('run-workers <workers> [selectedRuns...]')
   .description('Executes tests in workers')
   .option('-c, --config [file]', 'configuration file to be used')
   .option('-g, --grep <pattern>', 'only run tests matching <pattern>')

package/docs/ai.md

@@ -0,0 +1,248 @@
+---
+permalink: /ai
+title: Testing with AI 🪄 
+---
+
+# 🪄 Testing with AI
+
+**CodeceptJS is the first open-source test automation framework with AI** features to improve the testing experience. CodeceptJS uses OpenAI GPT to auto-heal failing tests, assist in writing tests, and more...
+
+Think of it as your testing co-pilot built into the testing framework
+
+> 🪄 **AI features for testing are experimental**. AI works only for web based testing with Playwright, WebDriver, etc. Those features will be improved based on user's experience.
+
+
+## How AI Improves Automated Testing
+
+ChatGPT can write automated tests for you. What you need is just ask it "How to write CodeceptJS test" and it will generate the code that can be executed but not the actual code you need. ChatGPT misses the context, of your application. 
+
+CodeceptJS uses OpenAI API to send the prompt and share the HTML context of a page. So, it can ask: how to write a test for **this** page. GPT model knows how to write CodeceptJS code, how to build good-looking semantic locators and how to analyze HTML to match them. Even more, GPT suggestions can be tested in real-time in a browser, making a feedback loop.
+
+CodeceptJS AI can do the following:
+
+* 🏋️‍♀️ **assist writing tests** in `pause()` or interactive shell mode
+* 🚑 **self-heal failing tests** (can be used on CI)
+* 💬 send arbitrary prompts to GPT from any tested page attaching its HTML contents
+
+![](/img/fill_form.gif)
+
+### How it works
+
+As we can't send a browser window with ChatGPT we are not be able to fully share the context. As only text information is accepted, we can send HTML of the currently tested page. GPT doesn't know what elements are hidden, or what elements are visible. It can operate only on the HTML provided.
+
+GPT models have limits on information passed, and HTML pages can be huge. And some information may be irrelevant for testing. For instance, if you test a reading application, you won't probably need text contents of a book inside your HTML, as they won't be used in locators. That's why CodeceptJS send HTML with **all non-interactive HTML elements removed**. So, only links, buttons, fields, and all elements that are set as a link, button, etc will be used by GPT for analysis. In case you have clickable `<div>` but with no `role="button"` it will be ignored. Also, we minify HTML before sending.
+
+Even though, the HTML is still quite big and may exceed the token limit. So we recommend using **gpt-3.5-turbo-16k** model, as it accepts 16K tokens (approx. 50K of HTML text), which should be enough for most web pages. It is possible to strictly limit the size of HTML to not exceed GPT tokens limit.
+
+> ❗AI features require sending HTML contents to OpenAI. If you use it in enterprise, ensure that your company requirements match [OpenAI complience](https://openai.com/security). If you work on public web applications this should be ok, as HTML code is genrally available to all web application users.
+
+
+### Getting Started
+
+[Install CodeceptJS 3.5](/installation):
+
+```
+npx create-codeceptjs .
+```
+[Obtain API token](https://platform.openai.com/account/api-keys) from OpenAI. Please check out [their pricing](https://openai.com/pricing) first, as unlike ChatGPT using OpenAI API requires a paid account.
+
+Add `OPENAI_API_KEY` environment variable with a key when running codeceptjs:
+
+```
+OPENAI_API_KEY=sk-******** npx codeceptjs run
+```
+
+This will enable AI features in CodeceptJS.
+
+> When running on CI set `OPENAI_API_KEY` as a secured environment variable
+
+### Writing Tests with AI Copilot
+
+If AI features are enabled when using [interactive pause](/basics/#debug) with `pause()` command inside tests:
+
+For instance, let's create a test to try ai features via `gt` command:
+
+```
+npx codeceptjs gt
+```
+
+Name a test and write the code. We will use `Scenario.only` instead of Scenario to execute only this exact test.
+
+```js
+Feature('ai');
+
+Scenario.only('test ai features', ({ I }) => {
+  I.amOnPage('https://getbootstrap.com/docs/5.1/examples/checkout/')
+  pause();
+});
+```
+
+Now run the test in debug mode:
+
+```
+OPENAI_API_KEY=sk-******** npx codeceptjs run --debug
+```
+
+When pause mode started you can ask GPT to fill in the fields on this page. Use natural language to describe your request, and provide enough details that AI could operate with it. It is important to include at least a space char in your input, otherwise, CodeceptJS will consider the input to be JavaScript code.
+
+
+```
+ I.fill checkout form with valid values without submitting it
+```
+
+![](/img/fill_form_1.png)
+
+GPT will generate code and data and CodeceptJS will try to execute its code. If it succeeds, the code will be saved to history and you will be able to copy it to your test.
+
+![](/img/fill_form2.png)
+
+This AI copilot works best with long static forms. In the case of complex and dynamic single-page applications, it may not perform as well, as the form may not be present on HTML page yet. For instance, interacting with calendars or inputs with real-time validations (like credit cards) can not yet be performed by AI.
+
+Please keep in mind that GPT can't react to page changes and operates with static text only. This is why it is not ready yet to write the test completely. However, if you are new to CodeceptJS and automated testing AI copilot may help you write tests more efficiently. 
+
+> 👶 Enable AI copilot for junior test automation engineers. It may help them to get started with CodeceptJS and to write good semantic locators.
+
+### Self-Healing Tests
+
+In large test suites, the cost of maintaining tests goes exponentially. That's why any effort that can improve the stability of tests pays itself. In CodeceptJS 3.5 we introduced a new [heal plugin](/plugins#heal) that will use AI to automatically fix a failing test.
+
+Heal plugin can solve exactly one problem: if a locator of an element has changed, and an action can't be performed, **it matches a new locator, tries a command again, and continues executing a test**. For instance, if the "Sign in" button was renamed to "Login" or changed its class, it will detect a new locator of the button and will retry execution.
+
+Heal actions **work only on actions like `click`, `fillField`**, etc, and won't work on assertions, waiters, grabbers, etc. Assertions can't be guessed by AI, the same way as grabbers, as this may lead to unpredictable results.
+
+If Heal plugin successfully fixes the step, it will print a suggested change at the end of execution. Take it as actionable advice and use it to update the codebase. Heal plugin is supposed to be used on CI, and works automatically without human assistance.
+
+To start, enable `heal` plugin in `codecept.conf.js` or `codecept.conf.ts`:
+
+```js
+plugins: {
+  heal: {
+    enabled: true
+  }
+}
+```
+
+and run tests in AI mode with `OPENAI_API_KEY` provided:
+
+```
+OPENAI_API_KEY=sk-******** npx codeceptjs run
+```
+
+![](/img/heal.png)
+
+
+### Arbitrary GPT Prompts
+
+What if you want to take ChatGPT on the journey of test automation and ask it questions while browsing pages?
+
+This is possible with the new `OpenAI` helper. Enable it in your config and it will automatically attach to Playwright, WebDriver, or another web helper you use. It includes the following methods:
+
+* `askGptOnPage` - sends GPT prompt attaching the HTML of the page. Large pages will be split into chunks, according to `chunkSize` config. You will receive responses for all chunks.
+* `askGptOnPageFragment` - sends GPT prompt attaching the HTML of the specific element. This method is recommended over `askGptOnPage` as you can reduce the amount of data to be processed.
+* `askGptGeneralPrompt` - sends GPT prompt without HTML.
+
+OpenAI helper won't remove non-interactive elements, so it is recommended to manually control the size of the sent HTML.
+
+Here are some good use cases for this helper:
+
+* get page summaries
+* inside pause mode navigate through your application and ask to document pages
+* etc...
+
+```js
+// use it inside test or inside interactive pause
+// pretend you are technical writer asking for documentation
+const pageDoc = await I.askGptOnPageFragment('Act as technical writer, describe what is this page for', '#container');
+```
+
+As of now, those use cases do not apply to test automation but maybe you can apply them to your testing setup. 
+
+## Configuration
+
+AI features can be configured inside `codecept.conf` file under `ai` section:
+
+```js
+ai: {
+  model: 'gpt-3.5-turbo-16k',
+  temperature: 0.1,
+  html: // {}
+}
+```
+
+Available options are:
+
+* `model` - [OpenAI model](https://platform.openai.com/docs/models), `gpt-3.5-turbo-16k` is recommended. You may switch to another GPT model, however, consider the speed of processing and size of the input. Models with less than 16K tokens won't be able to process complete HTML even reduced to interactive elements.
+* `temperature` - [temperature](https://platform.openai.com/docs/api-reference/chat/create#chat/create-temperature) is a measure of randomness. Use the lowest value possible for test automation purposes.
+* `html` - configures how HTML is processed before sending it to GPT. This section is highly important to tune to adapt to your application. For instance, the default strategy may remove some important elements, or contrary keep some elements that have no practical usage in test automation.
+
+Here is the default config:
+
+```js
+ai: {
+  html: {
+    maxLength: 50000,
+    simplify: true,
+    minify: true,
+    interactiveElements: ['a', 'input', 'button', 'select', 'textarea', 'option'],
+    textElements: ['label', 'h1', 'h2'],
+    allowedAttrs: ['id', 'for', 'class', 'name', 'type', 'value', 'tabindex', 'aria-labelledby', 'aria-label', 'label', 'placeholder', 'title', 'alt', 'src', 'role'],
+    allowedRoles: ['button', 'checkbox', 'search', 'textbox', 'tab'],
+  }
+}
+```
+
+* `maxLength`: the size of HTML to cut to not reach the token limit. 50K is the current default but you may try to increase it or even set it to null.
+* `simplify`: should we process HTML before sending to GPT. This will remove all non-interactive elements from HTML.
+* `minify`: shold HTML be additionally minified. This removed empty attributes, shortens notations, etc.
+* `interactiveElements`: explicit list of all elements that are considered interactive.
+* `textElements`: elements that contain text which can be used for test automation.
+* `allowedAttrs`: explicit list of attributes that may be used to construct locators. If you use special `data-` attributes to enable locators, add them to the list.
+* `allowedRoles`: list of roles that make standard elements interactive.
+
+It is recommended to try HTML processing on one of your web pages before launching AI features of CodeceptJS.
+
+
+To do that open the common page of your application and using DevTools copy the outerHTML of `<html>` element. Don't use `Page Source` for that, as it may not include dynamically added HTML elements. Save this HTML into a file and create a NodeJS script:
+
+```js
+const { removeNonInteractiveElements } = require('codeceptjs/lib/html');
+const fs = require('fs');
+
+const htmlOpts = {
+  interactiveElements: ['a', 'input', 'button', 'select', 'textarea', 'label', 'option'],
+  allowedAttrs: ['id', 'for', 'class', 'name', 'type', 'value', 'aria-labelledby', 'aria-label', 'label', 'placeholder', 'title', 'alt', 'src', 'role'],
+  textElements: ['label', 'h1', 'h2'],
+  allowedRoles: ['button', 'checkbox', 'search', 'textbox', 'tab'],
+};
+
+html = fs.readFileSync('saved.html', 'utf8');
+const result = removeNonInteractiveElements(html, htmlOpts);
+
+console.log(result);
+```
+
+Tune the options until you are satisfied with the results and use this as `html` config for `ai` section inside `codecept.conf` file.
+It is also recommended to check the source of [removeNonInteractiveElements](https://github.com/codeceptjs/CodeceptJS/blob/3.x/lib/html.js) and if needed propose improvements to it.
+
+For instance, if you use `data-qa` attributes to specify locators and you want to include them in HTML, use the following config:
+
+```js
+{
+  // inside codecept.conf.js
+  ai: {
+    html: {
+      allowedAttrs: [
+        'data-qa', 'id', 'for', 'class', 'name', 'type', 'value', 'aria-labelledby', 'aria-label', 'label', 'placeholder', 'title', 'alt', 'src', 'role'
+      ]
+    }
+  }
+}
+```
+
+## Debugging
+
+To debug AI features run tests with `DEBUG="codeceptjs:ai"` flag. This will print all prompts and responses from OpenAI
+
+```
+DEBUG="codeceptjs:ai" OPENAI_API_KEY=sk-******** npx codeceptjs run
+```

package/docs/build/Appium.js

@@ -17,6 +17,10 @@ const supportedPlatform = {
   iOS: 'iOS',
 };
 
+const vendorPrefix = {
+  appium: 'appium',
+};
+
 /**
  *  Appium helper extends [Webriver](http://codecept.io/helpers/WebDriver/) helper.
  *  It supports all browser methods and also includes special methods for mobile apps testing.
@@ -39,6 +43,7 @@ const supportedPlatform = {
  *
  * This helper should be configured in codecept.conf.ts or codecept.conf.js
  *
+ * * `appiumV2`: set this to true if you want to run tests with Appiumv2. See more how to setup [here](https://codecept.io/mobile/#setting-up)
  * * `app`: Application path. Local path or remote URL to an .ipa or .apk file, or a .zip containing one of these. Alias to desiredCapabilities.appPackage
  * * `host`: (default: 'localhost') Appium host
  * * `port`: (default: '4723') Appium port
@@ -116,7 +121,7 @@ const supportedPlatform = {
  *
  * ## Access From Helpers
  *
- * Receive a Appium client from a custom helper by accessing `browser` property:
+ * Receive Appium client from a custom helper by accessing `browser` property:
  *
  * ```js
  * let browser = this.helpers['Appium'].browser
@@ -135,6 +140,9 @@ class Appium extends Webdriver {
     super(config);
 
     this.isRunning = false;
+    if (config.appiumV2 === true) {
+      this.appiumV2 = true;
+    }
     this.axios = axios.create();
 
     webdriverio = require('webdriverio');
@@ -181,14 +189,22 @@ class Appium extends Webdriver {
 
     config.baseUrl = config.url || config.baseUrl;
     if (config.desiredCapabilities && Object.keys(config.desiredCapabilities).length) {
-      config.capabilities = config.desiredCapabilities;
+      config.capabilities = this.appiumV2 === true ? this._convertAppiumV2Caps(config.desiredCapabilities) : config.desiredCapabilities;
+    }
+
+    if (this.appiumV2) {
+      config.capabilities[`${vendorPrefix.appium}:deviceName`] = config[`${vendorPrefix.appium}:device`] || config.capabilities[`${vendorPrefix.appium}:deviceName`];
+      config.capabilities[`${vendorPrefix.appium}:browserName`] = config[`${vendorPrefix.appium}:browser`] || config.capabilities[`${vendorPrefix.appium}:browserName`];
+      config.capabilities[`${vendorPrefix.appium}:app`] = config[`${vendorPrefix.appium}:app`] || config.capabilities[`${vendorPrefix.appium}:app`];
+      config.capabilities[`${vendorPrefix.appium}:tunnelIdentifier`] = config[`${vendorPrefix.appium}:tunnelIdentifier`] || config.capabilities[`${vendorPrefix.appium}:tunnelIdentifier`]; // Adding the code to connect to sauce labs via sauce tunnel
+    } else {
+      config.capabilities.deviceName = config.device || config.capabilities.deviceName;
+      config.capabilities.browserName = config.browser || config.capabilities.browserName;
+      config.capabilities.app = config.app || config.capabilities.app;
+      config.capabilities.tunnelIdentifier = config.tunnelIdentifier || config.capabilities.tunnelIdentifier; // Adding the code to connect to sauce labs via sauce tunnel
     }
 
-    config.capabilities.deviceName = config.device || config.capabilities.deviceName;
-    config.capabilities.browserName = config.browser || config.capabilities.browserName;
-    config.capabilities.app = config.app || config.capabilities.app;
     config.capabilities.platformName = config.platform || config.capabilities.platformName;
-    config.capabilities.tunnelIdentifier = config.tunnelIdentifier || config.capabilities.tunnelIdentifier; // Adding the code to connect to sauce labs via sauce tunnel
     config.waitForTimeoutInSeconds = config.waitForTimeout / 1000; // convert to seconds
 
     // [CodeceptJS compatible] transform host to hostname
@@ -203,6 +219,10 @@ class Appium extends Webdriver {
     }
 
     this.platform = null;
+    if (config.capabilities[`${vendorPrefix.appium}:platformName`]) {
+      this.platform = config.capabilities[`${vendorPrefix.appium}:platformName`].toLowerCase();
+    }
+
     if (config.capabilities.platformName) {
       this.platform = config.capabilities.platformName.toLowerCase();
     }
@@ -210,6 +230,18 @@ class Appium extends Webdriver {
     return config;
   }
 
+  _convertAppiumV2Caps(capabilities) {
+    const _convertedCaps = {};
+    for (const [key, value] of Object.entries(capabilities)) {
+      if (!key.startsWith(vendorPrefix.appium)) {
+        _convertedCaps[`${vendorPrefix.appium}:${key}`] = value;
+      } else {
+        _convertedCaps[`${key}`] = value;
+      }
+    }
+    return _convertedCaps;
+  }
+
   static _config() {
     return [{
       name: 'app',
@@ -229,6 +261,11 @@ class Appium extends Webdriver {
   }
 
   async _startBrowser() {
+    if (this.appiumV2 === true) {
+      this.options.capabilities = this._convertAppiumV2Caps(this.options.capabilities);
+      this.options.desiredCapabilities = this._convertAppiumV2Caps(this.options.desiredCapabilities);
+    }
+
     try {
       if (this.options.multiremote) {
         this.browser = await webdriverio.multiremote(this.options.multiremote);
@@ -445,6 +482,7 @@ class Appium extends Webdriver {
    */
   async checkIfAppIsInstalled(bundleId) {
     onlyForApps.call(this, supportedPlatform.android);
+
     return this.browser.isAppInstalled(bundleId);
   }
 
@@ -481,7 +519,7 @@ class Appium extends Webdriver {
   async seeAppIsNotInstalled(bundleId) {
     onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isAppInstalled(bundleId);
-    return truth(`app ${bundleId}`, 'to be installed').negate(res);
+    return truth(`app ${bundleId}`, 'not to be installed').negate(res);
   }
 
   /**
@@ -1352,6 +1390,8 @@ class Appium extends Webdriver {
    * 
    * ```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/build/JSONResponse.js

@@ -300,16 +300,16 @@ class JSONResponse extends Helper {
    *
    * I.seeResponseMatchesJsonSchema(joi => {
    *   return joi.object({
-   *     name: joi.string();
-   *     id: joi.number();
+   *     name: joi.string(),
+   *     id: joi.number()
    *   })
    * });
    *
    * // or pass a valid schema
-   * const joi = require('joi);
+   * const joi = require('joi');
    *
    * I.seeResponseMatchesJsonSchema(joi.object({
-   *   name: joi.string();
+   *   name: joi.string(),
    *   id: joi.number();
    * });
    * ```

package/docs/build/Nightmare.js

@@ -1037,6 +1037,8 @@ class Nightmare extends Helper {
    * 
    * ```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.
@@ -1046,7 +1048,7 @@ class Nightmare extends Helper {
   async appendField(field, value) {
     const el = await findField.call(this, field);
     assertElementExists(el, field, 'Field');
-    return this.browser.enterText(el, value, false)
+    return this.browser.enterText(el, value.toString(), false)
       .wait(this.options.waitForAction);
   }