codeceptjs 3.0.7 → 3.1.3

package/CHANGELOG.md

@@ -1,13 +1,107 @@
+## 3.1.3
+
+🛩️ Features:
+
+* BDD Improvement. Added `DataTableArgument` class to work with table data structures. 
+
+```js
+const { DataTableArgument } = require('codeceptjs');
+//...
+Given('I have an employee card', (table) => {
+  const dataTableArgument = new DataTableArgument(table);
+  const hashes = dataTableArgument.hashes(); 
+  // hashes = [{ name: 'Harry', surname: 'Potter', position: 'Seeker' }];
+  const rows = dataTableArgument.rows();
+  // rows = [['Harry', 'Potter', Seeker]];
+  }
+```
+See updated [BDD section](https://codecept.io/bdd/) for more API options.
+
+* Support `cjs` file extensions for config file: `codecept.conf.cjs`. See #3052 by @kalvenschraut
+* API updates: Added `test.file` and `suite.file` properties to `test` and `suite` objects to use in helpers and plugins. 
+
+🐛 Bugfixes:
+
+* [Playwright] Fixed resetting `test.artifacts` for failing tests. See #3033 by @jancorvus. Fixes #3032
+* [Playwright] Apply `basicAuth` credentials to all opened browser contexts. See #3036 by @nikocanvacom. Fixes #3035
+* [WebDriver] Updated `webdriverio` default version to `^6.12.1`. See #3043 by @sridhareaswaran
+* [Playwright] `I.haveRequestHeaders` affects all tabs. See #3049 by @jancorvus
+* BDD: Fixed unhandled empty feature files. Fix #3046 by @abhimanyupandian 
+* Fixed `RangeError: Invalid string length` in `recorder.js` when running huge amount of tests.  
+
+📖 Documentation:
+
+* Added Testrail reporter [Reports Docs](https://codecept.io/reports/#testrail)
+
+
+## 3.1.2
+
+🛩️ Features:
+
+* Added `coverage` plugin to generate code coverage for Playwright & Puppeteer. By @anirudh-modi
+* Added `subtitle` plugin to generate subtitles for videos recorded with Playwright. By @anirudh-modi
+* Configuration: `config.tests` to accept array of file patterns. See #2994 by @monsteramba
+
+```js
+exports.config = {
+  tests: ['./*_test.js','./sampleTest.js'],
+  // ... 
+}
+```
+* Notification is shown for test files without `Feature()`. See #3011 by @PeterNgTr
+
+🐛 Bugfixes:
+
+* [Playwright] Fixed #2986 error is thrown when deleting a missing video. Fix by @hatufacci 
+* Fixed false positive result when invalid function is called in a helper. See #2997 by @abhimanyupandian
+* [Appium] Removed full page mode for `saveScreenshot`. See #3002 by @nlespiaucq
+* [Playwright] Fixed #3003 saving trace for a test with a long name. Fix by @hatufacci 
+
+🎱 Other:
+
+* Deprecated `puppeteerCoverage` plugin in favor of `coverage` plugin.
+
+## 3.1.1
+
+* [Appium] Fixed #2759
+ `grabNumberOfVisibleElements`, `grabAttributeFrom`, `grabAttributeFromAll` to allow id locators.
+
+## 3.1.0
+
+* [Plawyright] Updated to Playwright 1.13
+* [Playwright] **Possible breaking change**: `BrowserContext` is initialized before each test and closed after. This behavior matches recommendation from Playwright team to use different contexts for tests.
+* [Puppeteer] Updated to Puppeteer 10.2.
+* [Protractor] Helper deprecated
+
+🛩️ Features:
+
+* [Playwright] Added recording of [video](https://codecept.io/playwright/#video) and [traces](https://codecept.io/playwright/#trace) by @davertmik
+* [Playwritght] [Mocking requests](https://codecept.io/playwright/#mocking-network-requests) implemented via `route` API of Playwright by @davertmik
+* [Playwright] Added **support for [React locators](https://codecept.io/react/#locators)** in #2912 by @AAAstorga
+
+🐛 Bugfixes:
+
+* [Puppeteer] Fixed #2244 `els[0]._clickablePoint is not a function` by @karunandrii.
+* [Puppeteer] Fixed `fillField` to check for invisible elements. See #2916 by @anne-open-xchange 
+* [Playwright] Reset of dialog event listener before registration of new one. #2946 by @nikocanvacom 
+* Fixed running Gherkin features with `run-multiple` using chunks. See #2900 by @andrenoberto
+* Fixed #2937 broken typings for subfolders on Windows by @jancorvus
+* Fixed issue where cucumberJsonReporter not working with fakerTransform plugin. See #2942 by @ilangv 
+* Fixed #2952 finished job with status code 0 when playwright cannot connect to remote wss url. By @davertmik
+
+
 ## 3.0.7
 
-Documentation fixes:
+📖 Documentation fixes:
+
 * Remove broken link from `Nightmare helper`. See #2860 by @Arhell
 * Fixed broken links in `playwright.md`. See #2848 by @johnhoodjr
 * Fix mocha-multi config example. See #2881 by @rimesc
 * Fix small errors in email documentation file. See #2884 by @mkrtchian
 * Improve documentation for `Sharing Data Between Workers` section. See #2891 by @ngraf
 
-Features:
+🛩️ Features:
+
 * [WebDriver] Shadow DOM Support for `Webdriver`. See #2741 by @gkushang
 * [Release management] Introduce the versioning automatically, it follows the semantics versioning. See #2883 by @PeterNgTr
 * Adding opts into `Scenario.skip` that it would be useful for building reports. See #2867 by @AlexKo4

package/README.md

@@ -1,4 +1,12 @@
-[<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] [![Build Status](https://travis-ci.org/Codeception/CodeceptJS.svg?branch=master)](https://travis-ci.org/Codeception/CodeceptJS) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/1823c38c74e44724b5555e3641f72621)](https://www.codacy.com/app/DavertMik/CodeceptJS?utm_source=github.com&utm_medium=referral&utm_content=Codeception/CodeceptJS&utm_campaign=badger) [![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
+[<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]
+
+Build Status:
+
+[![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)
+[![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)
+[![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)
+[![Appium Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml)
+[![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)
 
 # CodeceptJS
 

package/bin/codecept.js

@@ -2,6 +2,16 @@
 const program = require('commander');
 const Codecept = require('../lib/codecept');
 const { print, error } = require('../lib/output');
+const { printError } = require('../lib/command/utils');
+
+const errorHandler = (fn) => async (...args) => {
+  try {
+    await fn(...args);
+  } catch (e) {
+    printError(e);
+    process.exitCode = 1;
+  }
+};
 
 if (process.versions.node && process.versions.node.split('.') && process.versions.node.split('.')[0] < 8) {
   error('NodeJS >= 8 is required to run.');
@@ -16,11 +26,11 @@ program.version(Codecept.version());
 
 program.command('init [path]')
   .description('Creates dummy config in current dir or [path]')
-  .action(require('../lib/command/init'));
+  .action(errorHandler(require('../lib/command/init')));
 
 program.command('migrate [path]')
   .description('Migrate json config to js config in current dir or [path]')
-  .action(require('../lib/command/configMigrate'));
+  .action(errorHandler(require('../lib/command/configMigrate')));
 
 program.command('shell [path]')
   .alias('sh')
@@ -28,30 +38,30 @@ program.command('shell [path]')
   .option('--verbose', 'output internal logging information')
   .option('--profile [value]', 'configuration profile to be used')
   .option('-c, --config [file]', 'configuration file to be used')
-  .action(require('../lib/command/interactive'));
+  .action(errorHandler(require('../lib/command/interactive')));
 
 program.command('list [path]')
   .alias('l')
   .description('List all actions for I.')
-  .action(require('../lib/command/list'));
+  .action(errorHandler(require('../lib/command/list')));
 
 program.command('def [path]')
   .description('Generates TypeScript definitions for all I actions.')
   .option('-c, --config [file]', 'configuration file to be used')
   .option('-o, --output [folder]', 'target folder to paste definitions')
-  .action(require('../lib/command/definitions'));
+  .action(errorHandler(require('../lib/command/definitions')));
 
 program.command('gherkin:init [path]')
   .alias('bdd:init')
   .description('Prepare CodeceptJS to run feature files.')
   .option('-c, --config [file]', 'configuration file to be used')
-  .action(require('../lib/command/gherkin/init'));
+  .action(errorHandler(require('../lib/command/gherkin/init')));
 
 program.command('gherkin:steps [path]')
   .alias('bdd:steps')
   .description('Prints all defined gherkin steps.')
   .option('-c, --config [file]', 'configuration file to be used')
-  .action(require('../lib/command/gherkin/steps'));
+  .action(errorHandler(require('../lib/command/gherkin/steps')));
 
 program.command('gherkin:snippets [path]')
   .alias('bdd:snippets')
@@ -60,28 +70,28 @@ program.command('gherkin:snippets [path]')
   .option('-c, --config [file]', 'configuration file to be used')
   .option('--feature [file]', 'feature files(s) to scan')
   .option('--path [file]', 'file in which to place the new snippets')
-  .action(require('../lib/command/gherkin/snippets'));
+  .action(errorHandler(require('../lib/command/gherkin/snippets')));
 
 program.command('generate:test [path]')
   .alias('gt')
   .description('Generates an empty test')
-  .action(require('../lib/command/generate').test);
+  .action(errorHandler(require('../lib/command/generate').test));
 
 program.command('generate:pageobject [path]')
   .alias('gpo')
   .description('Generates an empty page object')
-  .action(require('../lib/command/generate').pageObject);
+  .action(errorHandler(require('../lib/command/generate').pageObject));
 
 program.command('generate:object [path]')
   .alias('go')
   .option('--type, -t [kind]', 'type of object to be created')
   .description('Generates an empty support object (page/step/fragment)')
-  .action(require('../lib/command/generate').pageObject);
+  .action(errorHandler(require('../lib/command/generate').pageObject));
 
 program.command('generate:helper [path]')
   .alias('gh')
   .description('Generates a new helper')
-  .action(require('../lib/command/generate').helper);
+  .action(errorHandler(require('../lib/command/generate').helper));
 
 program.command('run [test]')
   .description('Executes tests')
@@ -117,8 +127,8 @@ program.command('run [test]')
   .option('--recursive', 'include sub directories')
   .option('--trace', 'trace function calls')
   .option('--child <string>', 'option for child processes')
+  .action(errorHandler(require('../lib/command/run')));
 
-  .action(require('../lib/command/run'));
 program.command('run-workers <workers>')
   .description('Executes tests in workers')
   .option('-c, --config [file]', 'configuration file to be used')
@@ -134,7 +144,7 @@ program.command('run-workers <workers>')
   .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
   .option('-O, --reporter-options <k=v,k2=v2,...>', 'reporter-specific options')
   .option('-R, --reporter <name>', 'specify the reporter to use')
-  .action(require('../lib/command/run-workers'));
+  .action(errorHandler(require('../lib/command/run-workers')));
 
 program.command('run-multiple [suites...]')
   .description('Executes tests multiple')
@@ -158,12 +168,12 @@ program.command('run-multiple [suites...]')
   // mocha options
   .option('--colors', 'force enabling of colors')
 
-  .action(require('../lib/command/run-multiple'));
+  .action(errorHandler(require('../lib/command/run-multiple')));
 
 program.command('info [path]')
   .description('Print debugging information concerning the local environment')
   .option('-c, --config', 'your config file path')
-  .action(require('../lib/command/info'));
+  .action(errorHandler(require('../lib/command/info')));
 
 program.command('dry-run [test]')
   .description('Prints step-by-step scenario for a test without actually running it')
@@ -179,7 +189,7 @@ program.command('dry-run [test]')
   .option('--steps', 'show step-by-step execution')
   .option('--verbose', 'output internal logging information')
   .option('--debug', 'output additional information')
-  .action(require('../lib/command/dryRun'));
+  .action(errorHandler(require('../lib/command/dryRun')));
 
 program.on('command:*', (cmd) => {
   console.log(`\nUnknown command ${cmd}\n`);

package/docs/bdd.md

@@ -264,8 +264,10 @@ You can also use the `parse()` method to obtain an object that allow you to get
 - `raw()` - returns the table as a 2-D array
 - `rows()` - returns the table as a 2-D array, without the first row
 - `hashes()` - returns an array of objects where each row is converted to an object (column header is the key)
+- `rowsHash()` - returns an object where each row corresponds to an entry(first column is the key, second column is the value)
+- `transpose()` - transpose the data, returns nothing. To work with the transposed table use the methods above.
 
-If we use hashes() with the previous exemple :
+If we use hashes() with the previous example :
 
 ```js
 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
   }
 });
 ```
+Examples of tables using: 
 
+```gherkin
+  Given I have a short employees card
+    | Harry | Potter  |
+    | Chuck | Norris  |
+```
+```js
+const { DataTableArgument } = require('codeceptjs');
+//...
+Given('I have a short employees card', (table) => {
+  const dataTableArgument = new DataTableArgument(table);
+  const raw = dataTableArgument.raw(); 
+  // row = [['Harry', 'Potter'], ['Chuck', 'Norris']]
+  dataTableArgument.transpose();
+  const transposedRaw = dataTableArgument.raw();
+  // transposedRaw = [['Harry', 'Chuck'], ['Potter', 'Norris']];
+  }
+);
+```
+```gherkin
+  Given I have an employee card
+    | name  | surname | position |
+    | Harry | Potter  | Seeker   |
+```
+```js
+const { DataTableArgument } = require('codeceptjs');
+//...
+Given('I have an employee card', (table) => {
+  const dataTableArgument = new DataTableArgument(table);
+  const hashes = dataTableArgument.hashes(); 
+  // hashes = [{ name: 'Harry', surname: 'Potter', position: 'Seeker' }];
+  const rows = dataTableArgument.rows();
+  // rows = [['Harry', 'Potter', Seeker]];
+  }
+);
+```
+```gherkin
+  Given I have a formatted employee card
+    | name     | Harry  |
+    | surname  | Potter |
+    | position | Seeker |
+```
+```js
+const { DataTableArgument } = require('codeceptjs');
+//...
+Given('I have a formatted employee card', (table) => {
+  const dataTableArgument = new DataTableArgument(table);
+  const rawHash = dataTableArgument.rowsHash();
+  // rawHash = { name: 'Harry', surname: 'Potter', position: 'Seeker' };
+  }
+);
+```
 ### Examples
 
 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.

package/docs/build/Appium.js

@@ -481,10 +481,11 @@ class Appium extends Webdriver {
    * ```js
    * I.removeApp('appName', 'com.example.android.apis');
    * ```
-   * @param {string} appId
-   * @param {string}  bundleId String  ID of bundle
    *
    * Appium: support only Android
+   *
+   * @param {string} appId
+   * @param {string} [bundleId] ID of bundle
    */
   async removeApp(appId, bundleId) {
     onlyForApps.call(this, 'Android');
@@ -820,9 +821,10 @@ class Appium extends Webdriver {
    * I.hideDeviceKeyboard('pressKey', 'Done');
    * ```
    *
-   * @param {'tapOutside' | 'pressKey'} strategy  desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
-   *
    * Appium: support Android and iOS
+   *
+   * @param {'tapOutside' | 'pressKey'} [strategy] Desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
+   * @param {string} [key] Optional key
    */
   async hideDeviceKeyboard(strategy, key) {
     onlyForApps.call(this);
@@ -1162,6 +1164,8 @@ class Appium extends Webdriver {
    * ```
    *
    * Appium: support Android and iOS
+   *
+   * @param {Array} actions Array of touch actions
    */
   async touchPerform(actions) {
     onlyForApps.call(this);
@@ -1462,6 +1466,60 @@ class Appium extends Webdriver {
     return super.grabTextFrom(parseLocator.call(this, locator));
   }
 
+  /**
+   * Grab number of visible elements by locator.
+   * Resumes test execution, so **should be used inside async function with `await`** operator.
+   * 
+   * ```js
+   * let numOfElements = await I.grabNumberOfVisibleElements('p');
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @returns {Promise<number>} number of visible elements
+   */
+  async grabNumberOfVisibleElements(locator) {
+    if (this.isWeb) return super.grabNumberOfVisibleElements(locator);
+    return super.grabNumberOfVisibleElements(parseLocator.call(this, locator));
+  }
+
+  /**
+   * Can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+   *
+   * Retrieves an attribute from an element located by CSS or XPath and returns it to test.
+   * Resumes test execution, so **should be used inside async with `await`** operator.
+   * If more than one element is found - attribute of first element is returned.
+   * 
+   * ```js
+   * let hint = await I.grabAttributeFrom('#tooltip', 'title');
+   * ```
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string} attr attribute name.
+   * @returns {Promise<string>} attribute value
+   * 
+   */
+  async grabAttributeFrom(locator, attr) {
+    if (this.isWeb) return super.grabAttributeFrom(locator, attr);
+    return super.grabAttributeFrom(parseLocator.call(this, locator), attr);
+  }
+
+  /**
+   * Can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+   * Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
+   * Resumes test execution, so **should be used inside async with `await`** operator.
+   * 
+   * ```js
+   * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
+   * ```
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string} attr attribute name.
+   * @returns {Promise<string[]>} attribute value
+   * 
+   */
+  async grabAttributeFromAll(locator, attr) {
+    if (this.isWeb) return super.grabAttributeFromAll(locator, attr);
+    return super.grabAttributeFromAll(parseLocator.call(this, locator), attr);
+  }
+
   /**
    * Retrieves an array of value from a form located by CSS or XPath and returns it to test.
    * Resumes test execution, so **should be used inside async function with `await`** operator.
@@ -1497,6 +1555,20 @@ class Appium extends Webdriver {
     return super.grabValueFrom(parseLocator.call(this, locator));
   }
 
+  /**
+   * Saves a screenshot to ouput folder (set in codecept.json or codecept.conf.js).
+   * Filename is relative to output folder.
+   *
+   * ```js
+   * I.saveScreenshot('debug.png');
+   * ```
+   *
+   * @param {string} fileName file name to save.
+   */
+  async saveScreenshot(fileName) {
+    return super.saveScreenshot(fileName, false);
+  }
+
   /**
    * Scroll element into viewport.
    *