codeceptjs 3.4.1 → 3.5.1

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 the config.
+
+```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,6 +1,6 @@
 ---
 permalink: /tutorial
-title: CoeceptJS Complete Tutorial
+title: CodeceptJS Complete Tutorial
 ---
 
 # Tutorial: Writing Tests for Checkout Page
@@ -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 = {
 

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/blur.mustache

@@ -0,0 +1,17 @@
+Remove focus from a text input, button, etc.
+Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+
+Examples:
+
+```js
+I.blur('.text-area')
+```
+```js
+//element `#product-tile` is focused
+I.see('#add-to-cart-btn');
+I.blur('#product-tile')
+I.dontSee('#add-to-cart-btn');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.

package/docs/webapi/focus.mustache

@@ -0,0 +1,12 @@
+Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+
+Examples:
+
+```js
+I.dontSee('#add-to-cart-btn');
+I.focus('#product-tile')
+I.see('#add-to-cart-bnt');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.

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.

package/lib/ai.js

@@ -0,0 +1,171 @@
+const { Configuration, OpenAIApi } = require('openai');
+const debug = require('debug')('codeceptjs:ai');
+const config = require('./config');
+const output = require('./output');
+const { removeNonInteractiveElements, minifyHtml, splitByChunks } = require('./html');
+
+const defaultConfig = {
+  model: 'gpt-3.5-turbo-16k',
+  temperature: 0.1,
+};
+
+const htmlConfig = {
+  maxLength: 50000,
+  simplify: true,
+  minify: true,
+  html: {},
+};
+
+class AiAssistant {
+  constructor() {
+    this.config = config.get('ai', defaultConfig);
+    this.htmlConfig = Object.assign(htmlConfig, this.config.html);
+    delete this.config.html;
+    this.html = null;
+    this.response = null;
+
+    this.isEnabled = !!process.env.OPENAI_API_KEY;
+
+    if (!this.isEnabled) return;
+
+    const configuration = new Configuration({
+      apiKey: process.env.OPENAI_API_KEY,
+    });
+
+    this.openai = new OpenAIApi(configuration);
+  }
+
+  setHtmlContext(html) {
+    let processedHTML = html;
+
+    if (this.htmlConfig.simplify) {
+      processedHTML = removeNonInteractiveElements(processedHTML, this.htmlConfig);
+    }
+    if (this.htmlConfig.minify) processedHTML = minifyHtml(processedHTML);
+    if (this.htmlConfig.maxLength) processedHTML = splitByChunks(processedHTML, this.htmlConfig.maxLength)[0];
+
+    debug(processedHTML);
+
+    this.html = processedHTML;
+  }
+
+  getResponse() {
+    return this.response || '';
+  }
+
+  mockResponse(response) {
+    this.mockedResponse = response;
+  }
+
+  async createCompletion(messages) {
+    if (!this.openai) return;
+
+    debug(messages);
+
+    if (this.mockedResponse) return this.mockedResponse;
+
+    this.response = null;
+
+    try {
+      const completion = await this.openai.createChatCompletion({
+        ...this.config,
+        messages,
+      });
+
+      this.response = completion?.data?.choices[0]?.message?.content;
+
+      debug(this.response);
+
+      return this.response;
+    } catch (err) {
+      debug(err.response);
+      output.print('');
+      output.error(`OpenAI error: ${err.message}`);
+      output.error(err?.response?.data?.error?.code);
+      output.error(err?.response?.data?.error?.message);
+      return '';
+    }
+  }
+
+  async healFailedStep(step, err, test) {
+    if (!this.isEnabled) return [];
+    if (!this.html) throw new Error('No HTML context provided');
+
+    const messages = [
+      { role: 'user', content: 'As a test automation engineer I am testing web application using CodeceptJS.' },
+      { role: 'user', content: `I want to heal a test that fails. Here is the list of executed steps: ${test.steps.join(', ')}` },
+      { role: 'user', content: `Propose how to adjust ${step.toCode()} step to fix the test.` },
+      { role: 'user', content: 'Use locators in order of preference: semantic locator by text, CSS, XPath. Use codeblocks marked with ```.' },
+      { role: 'user', content: `Here is the error message: ${err.message}` },
+      { role: 'user', content: `Here is HTML code of a page where the failure has happened: \n\n${this.html}` },
+    ];
+
+    const response = await this.createCompletion(messages);
+    if (!response) return [];
+
+    return parseCodeBlocks(response);
+  }
+
+  async writeSteps(input) {
+    if (!this.isEnabled) return;
+    if (!this.html) throw new Error('No HTML context provided');
+
+    const snippets = [];
+
+    const messages = [
+      {
+        role: 'user',
+        content: `I am test engineer writing test in CodeceptJS
+          I have opened web page and I want to use CodeceptJS to ${input} on this page
+          Provide me valid CodeceptJS code to accomplish it
+          Use only locators from this HTML: \n\n${this.html}`,
+      },
+      { role: 'user', content: 'Propose only CodeceptJS steps code. Do not include Scenario or Feature into response' },
+
+      // old prompt
+      // { role: 'user', content: 'I want to click button Submit using CodeceptJS on this HTML page: <html><body><button>Submit</button></body></html>' },
+      // { role: 'assistant', content: '```js\nI.click("Submit");\n```' },
+      // { role: 'user', content: 'I want to click button Submit using CodeceptJS on this HTML page: <html><body><button>Login</button></body></html>' },
+      // { role: 'assistant', content: 'No suggestions' },
+      // { role: 'user', content: `Now I want to ${input} on this HTML page using CodeceptJS code` },
+      // { role: 'user', content: `Provide me with CodeceptJS code to achieve this on THIS page.` },
+    ];
+    const response = await this.createCompletion(messages);
+    if (!response) return;
+    snippets.push(...parseCodeBlocks(response));
+
+    debug(snippets[0]);
+
+    return snippets[0];
+  }
+}
+
+function parseCodeBlocks(response) {
+  // Regular expression pattern to match code snippets
+  const codeSnippetPattern = /```(?:javascript|js|typescript|ts)?\n([\s\S]+?)\n```/g;
+
+  // Array to store extracted code snippets
+  const codeSnippets = [];
+
+  response = response.split('\n').map(line => line.trim()).join('\n');
+
+  // Iterate over matches and extract code snippets
+  let match;
+  while ((match = codeSnippetPattern.exec(response)) !== null) {
+    codeSnippets.push(match[1]);
+  }
+
+  // Remove "Scenario", "Feature", and "require()" lines
+  const modifiedSnippets = codeSnippets.map(snippet => {
+    const lines = snippet.split('\n');
+
+    const filteredLines = lines.filter(line => !line.includes('I.amOnPage') && !line.startsWith('Scenario') && !line.startsWith('Feature') && !line.includes('= require('));
+
+    return filteredLines.join('\n');
+    // remove snippets that move from current url
+  }); // .filter(snippet => !line.includes('I.amOnPage'));
+
+  return modifiedSnippets.filter(snippet => !!snippet);
+}
+
+module.exports = AiAssistant;

package/lib/cli.js

@@ -81,6 +81,11 @@ class Cli extends Base {
       if (!codeceptjsEventDispatchersRegistered) {
         codeceptjsEventDispatchersRegistered = true;
 
+        event.dispatcher.on(event.bddStep.started, (step) => {
+          output.stepShift = 2;
+          output.step(step);
+        });
+
         event.dispatcher.on(event.step.started, (step) => {
           let processingStep = step;
           const metaSteps = [];
@@ -93,7 +98,10 @@ class Cli extends Base {
           for (let i = 0; i < Math.max(currentMetaStep.length, metaSteps.length); i++) {
             if (currentMetaStep[i] !== metaSteps[i]) {
               output.stepShift = 3 + 2 * i;
-              if (metaSteps[i]) output.step(metaSteps[i]);
+              if (!metaSteps[i]) continue;
+              // bdd steps are handled by bddStep.started
+              if (metaSteps[i].isBDD()) continue;
+              output.step(metaSteps[i]);
             }
           }
           currentMetaStep = metaSteps;
@@ -168,7 +176,7 @@ class Cli extends Base {
         }
 
         // display artifacts in debug mode
-        if (test.artifacts && Object.keys(test.artifacts).length) {
+        if (test?.artifacts && Object.keys(test.artifacts).length) {
           log += `\n${output.styles.bold('Artifacts:')}`;
           for (const artifact of Object.keys(test.artifacts)) {
             log += `\n- ${artifact}: ${test.artifacts[artifact]}`;

package/lib/codecept.js

@@ -8,6 +8,7 @@ const Config = require('./config');
 const event = require('./event');
 const runHook = require('./hooks');
 const output = require('./output');
+const { emptyFolder } = require('./utils');
 
 /**
  * CodeceptJS runner
@@ -66,6 +67,8 @@ class Codecept {
     global.codecept_dir = dir;
     global.output_dir = fsPath.resolve(dir, this.config.output);
 
+    if (this.config.emptyOutputFolder) emptyFolder(global.output_dir);
+
     if (!this.config.noGlobals) {
       global.Helper = global.codecept_helper = require('@codeceptjs/helper');
       global.actor = global.codecept_actor = require('./actor');
@@ -158,6 +161,7 @@ class Codecept {
 
     for (pattern of patterns) {
       glob.sync(pattern, options).forEach((file) => {
+        if (file.includes('node_modules')) return;
         if (!fsPath.isAbsolute(file)) {
           file = fsPath.join(global.codecept_dir, file);
         }