codeceptjs 2.6.7 → 2.6.11

package/docs/wiki/Upgrading-to-CodeceptJS-3.md

@@ -0,0 +1,153 @@
+🚀 CodeceptJS 3 is in beta now. Install it:
+
+```
+npm i codeceptjs@3.0.0-beta.3
+```
+
+* [COMPLETE CHANGELOG](https://github.com/Codeception/CodeceptJS/blob/codeceptjs-v3.0/CHANGELOG.md#300-beta)
+* [Documentation](https://github.com/Codeception/CodeceptJS/tree/codeceptjs-v3.0/docs)
+
+After installing a new version, run `codecept3-upgrade` which is described below:
+
+---
+
+CodeceptJS 3.0 is a new version of CodeceptJS with some breaking changes included. 
+You should update your project following this guide to ensure that everything works correctly. 
+
+### 1️⃣ Syntax Change
+
+CodeceptJS 3.0 introduced a new syntax for declaring tests, instead of:
+
+```js
+Scenario('title', (I, loginPage) => {})
+```
+we use a new way of passing arguments into a test, via destruction:
+
+```js
+Scenario('title', ({ I, loginPage }) => {})
+```
+
+This works similarly to `inject()` command. This change was done to unify accessing [dependency injection container](https://codecept.io/pageobjects/#dependency-injection), and to provide better TypeScript support. 
+
+> If you use BDD-style project with Gherkin, no changes needed for this step. 
+
+To upgrade your project, you don't need to change manually all your tests. 
+
+💪 **Use [codecept3-upgrade tool](https://www.npmjs.com/package/codecept3-upgrade) to perform the migration**. Use it carefully, as it updates your current code.
+
+To upgrade your codebase, commit all your changes, and switch to a new branch.
+Run upgrade script (even without installing) for a directory where you have your tests:
+
+```
+npx codecept3-upgrade tests
+```
+Review the changes in Git Diff and try to execute tests using CodeceptJS 3.0
+
+
+### 2️⃣ Grabbers signature change
+
+There were confusion and inconsistency across grab* methods. What they will return if multiple elements are found? A single element or an array? This was the problem as the format was dependent on a page content. 
+
+In 3.0 we decided to make all current grab* methods to return a single value only. While we add new methods grab**FromAll that return an array.
+
+For instance, `grabTextFrom` will always return a single text value, while `grabTextFromAll` will return an array of values:
+
+```js
+await I.grabTextFrom('.username'); => 'john'
+await I.grabTextFromAll('.username'); => ['john', 'claudia', 'bill']
+```
+
+Please update parts in your project where you rely on grab* methods to return an array.
+
+
+| Single Value | Multiple Values |
+| -- | -- |
+| ✋`grabTextFrom` | 🙌 `grabTextFromAll`  |
+| ✋`grabValueFrom` | 🙌 `grabValueFromAll`  |
+| ✋ `grabAttributeFrom` | 🙌`grabAttributeFromAll`  |
+| ✋ `grabHTMLFrom` | 🙌 `grabHTMLFromAll`  |
+| ✋ `grabCssPropertyFrom` | 🙌 `grabCssPropertyFromAll` |
+
+> Single-value `grab*From` will throw error when no data was matched, while `grab*FromAll` will return array.
+
+### 3️⃣ Bootstrap / Teardown Changed
+
+`async/await` paradigm changed the way we write asynchronous code in NodeJS. 
+However, bootstrap functions were created to use old-style methods of passing `done` callback inside.
+
+In 3.0 we decided to completely change the way async bootstrap is performed and replace all it with async/await functions:
+
+```js
+// before
+bootstrap: (done) => {
+  server.start().then(done);
+},
+
+// after
+bootstrap: async () => {
+  await server.start();
+}
+```
+Passing a string as bootstrap function (to require a function from external file) is also not supported:
+
+```js
+// before
+bootstrap: './server_start.js',
+
+// after
+bootstrap: require('./server_start.js'),
+```
+
+The same rules are applied to teardown, bootstrapAll, teardownAll.
+
+### 4️⃣ Locator Detection Heuristic Change
+
+In 3.0 we added a new rule to auto-detect CSS locator. If a locator starts with `[` parser will use it as a CSS locator, without trying to match value by text.
+
+* Previous behavior: I.click('[user]') - will try to search for a link with `[user]` text, if no found - take `[user]` as CSS locator
+* Current behavior: I.click('[user]') - will check only for CSS locator `[user]`
+
+### 5️⃣ Improved Parallel Execution with Workers
+
+CodeceptJS has two parallel execution modes:
+
+* classical `run-multiple` which spawns independent CodeceptJS processes on system level.
+* threaded `run-workers` which uses NodeJS workers instead of subprocesses.
+
+Workers are faster, they can communicate with parent thread. Unfortunately, `run-workers` was not as efficient as `run-multiple` because there was no way of declaring sophisticated configs for parallel execution. For instance, running tests in 4 threads in 2 browsers could not be set.
+
+We updated workers API to make them as flexible as possible. You don't even need to put complex logic into config! You can create your own parallel runner and customize it to match your expectations:
+
+```js
+// don't initialize workers in constructor
+const workers = new Workers(null, workerConfig);
+// split tests by suites in 2 groups
+const testGroups = workers.createGroupsOfSuites(2);
+
+const browsers = ['firefox', 'chrome'];
+
+const configs = browsers.map(browser => {
+  return helpers: {
+    WebDriver: { browser }
+  }
+});
+
+for (const config of configs) {
+  for (group of groupOfTests) {
+    const worker = workers.spawn();
+    worker.addTests(group);
+    worker.addConfig(config);
+  }
+}
+
+workers.run();
+```
+[Learn more about how you can create a parallel runner](https://github.com/Codeception/CodeceptJS/blob/codeceptjs-v3.0/docs/parallel.md#custom-parallel-execution).
+
+`run-multiple` will still work but it is considered deprecated and won't be supported.
+
+### WebDriverIO helper removed
+
+WebDriverIO helper supported webdriverio v4 library, which is not maintained anymore. It should be easy to switch to WebDriver helper which supports webdriverio v6.
+
+ 

package/docs/wiki/Videos.md

@@ -1,10 +1,10 @@
 [![](http://i3.ytimg.com/vi/BRMWstiOTks/maxresdefault.jpg)](https://www.youtube.com/watch?v=BRMWstiOTks)
 
-* ## [An Introduction, Getting started and working with CodeceptJS & Puppeteer (EAWeekend)](https://www.youtube.com/watch?v=BRMWstiOTks)
+## [An Introduction, Getting started and working with CodeceptJS & Puppeteer (EAWeekend)](https://www.youtube.com/watch?v=BRMWstiOTks)
 
-* ## [CodeceptJS Official YouTube Channel](https://www.youtube.com/channel/UCEs4030bmtonyDhTHEXa_2g)
+## [CodeceptJS Official YouTube Channel](https://www.youtube.com/channel/UCEs4030bmtonyDhTHEXa_2g)
 
-* ## [Introductory Videos](https://www.youtube.com/watch?v=FPFG1rBNJ64&list=PLcFXthgti9Lt4SjSvL1ALDg6dOeTC0TvT)
+## [Introductory Videos](https://www.youtube.com/watch?v=FPFG1rBNJ64&list=PLcFXthgti9Lt4SjSvL1ALDg6dOeTC0TvT)
 
 Free educational videos provided by our community member **[@ontytoom](http://github.com/ontytoom)**.
 

package/lib/actor.js

@@ -1,6 +1,6 @@
 const Step = require('./step');
 const container = require('./container');
-const methodsOfObject = require('./utils').methodsOfObject;
+const { methodsOfObject } = require('./utils');
 const recorder = require('./recorder');
 const event = require('./event');
 const output = require('./output');

package/lib/assert/empty.js

@@ -1,6 +1,6 @@
 const Assertion = require('../assert');
 const AssertionFailedError = require('./error');
-const template = require('../utils').template;
+const { template } = require('../utils');
 const output = require('../output');
 
 class EmptinessAssertion extends Assertion {

package/lib/assert/equal.js

@@ -1,6 +1,6 @@
 const Assertion = require('../assert');
 const AssertionFailedError = require('./error');
-const template = require('../utils').template;
+const { template } = require('../utils');
 const output = require('../output');
 
 class EqualityAssertion extends Assertion {

package/lib/assert/include.js

@@ -1,6 +1,6 @@
 const Assertion = require('../assert');
 const AssertionFailedError = require('./error');
-const template = require('../utils').template;
+const { template } = require('../utils');
 const output = require('../output');
 
 const MAX_LINES = 10;

package/lib/assert/truth.js

@@ -1,6 +1,6 @@
 const Assertion = require('../assert');
 const AssertionFailedError = require('./error');
-const template = require('../utils').template;
+const { template } = require('../utils');
 const output = require('../output');
 
 class TruthAssertion extends Assertion {

package/lib/codecept.js

@@ -1,8 +1,7 @@
-const existsSync = require('fs').existsSync;
-const readFileSync = require('fs').readFileSync;
+const { existsSync, readFileSync } = require('fs');
 const glob = require('glob');
 const fsPath = require('path');
-const resolve = require('path').resolve;
+const { resolve } = require('path');
 
 const container = require('./container');
 const Config = require('./config');

package/lib/command/configMigrate.js

@@ -5,11 +5,9 @@ const mkdirp = require('mkdirp');
 const path = require('path');
 const util = require('util');
 
-const print = require('../output').print;
-const success = require('../output').success;
-const error = require('../output').error;
-const fileExists = require('../utils').fileExists;
-const getTestRoot = require('./utils').getTestRoot;
+const { print, success, error } = require('../output');
+const { fileExists } = require('../utils');
+const { getTestRoot } = require('./utils');
 
 module.exports = function (initPath) {
   const testsPath = getTestRoot(initPath);

package/lib/command/definitions.js

@@ -1,8 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const Codecept = require('../codecept');
 const container = require('../container');
 const output = require('../output');

package/lib/command/dryRun.js

@@ -1,5 +1,4 @@
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const Config = require('../config');
 const Codecept = require('../codecept');
 const output = require('../output');

package/lib/command/gherkin/init.js

@@ -4,7 +4,7 @@ const path = require('path');
 const mkdirp = require('mkdirp');
 
 const output = require('../../output');
-const { fileExists, ucfirst, lcfirst } = require('../../utils');
+const { fileExists } = require('../../utils');
 const {
   getConfig, getTestRoot, updateConfig, safeFileWrite,
 } = require('../utils');

package/lib/command/gherkin/snippets.js

@@ -4,8 +4,8 @@ const { Parser } = require('gherkin');
 const glob = require('glob');
 const fsPath = require('path');
 
-const getConfig = require('../utils').getConfig;
-const getTestRoot = require('../utils').getTestRoot;
+const { getConfig } = require('../utils');
+const { getTestRoot } = require('../utils');
 const Codecept = require('../../codecept');
 const output = require('../../output');
 const { matchStep } = require('../../interfaces/bdd');
@@ -97,7 +97,7 @@ module.exports = function (genPath, options) {
 
   let stepFile = options.path || config.gherkin.steps[0];
   if (!fs.existsSync(stepFile)) {
-    output.error('Please enter a valid step file path ', stepFile);
+    output.error(`Please enter a valid step file path ${stepFile}`);
     process.exit(1);
   }
 

package/lib/command/gherkin/steps.js

@@ -1,7 +1,6 @@
-const getConfig = require('../utils').getConfig;
-const getTestRoot = require('../utils').getTestRoot;
+const { getConfig } = require('../utils');
+const { getTestRoot } = require('../utils');
 const Codecept = require('../../codecept');
-const container = require('../../container');
 const output = require('../../output');
 const { getSteps } = require('../../interfaces/bdd');
 

package/lib/command/info.js

@@ -1,7 +1,6 @@
 const envinfo = require('envinfo');
 
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const Codecept = require('../codecept');
 const output = require('../output');
 

package/lib/command/init.js

@@ -21,7 +21,7 @@ const defaultConfig = {
   mocha: {},
 };
 
-const helpers = ['WebDriver', 'Puppeteer', 'TestCafe', 'Protractor', 'Nightmare', 'Appium', 'Playwright'];
+const helpers = require('../plugin/standardActingHelpers').slice();
 const translations = Object.keys(require('../../translations'));
 
 const noTranslation = 'English (no localization)';
@@ -32,7 +32,7 @@ let packages;
 const configHeader = `const { setHeadlessWhen } = require('@codeceptjs/configure');
 
 // turn on headless mode when running with HEADLESS=true environment variable
-// HEADLESS=true npx codecept run
+// export HEADLESS=true && npx codeceptjs run
 setHeadlessWhen(process.env.HEADLESS);
 
 `;

package/lib/command/interactive.js

@@ -1,5 +1,4 @@
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const recorder = require('../recorder');
 const Codecept = require('../codecept');
 const event = require('../event');

package/lib/command/list.js

@@ -1,9 +1,8 @@
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const Codecept = require('../codecept');
 const container = require('../container');
-const getParamsToString = require('../parser').getParamsToString;
-const methodsOfObject = require('../utils').methodsOfObject;
+const { getParamsToString } = require('../parser');
+const { methodsOfObject } = require('../utils');
 const output = require('../output');
 
 module.exports = function (path) {

package/lib/command/run-multiple.js

@@ -1,12 +1,11 @@
-const fork = require('child_process').fork;
+const { fork } = require('child_process');
 const path = require('path');
 const crypto = require('crypto');
 
 const runHook = require('../hooks');
 const event = require('../event');
 const collection = require('./run-multiple/collection');
-const clearString = require('../utils').clearString;
-const replaceValueDeep = require('../utils').replaceValueDeep;
+const { clearString, replaceValueDeep } = require('../utils');
 const {
   getConfig, getTestRoot, fail,
 } = require('./utils');

package/lib/command/run-rerun.js

@@ -1,7 +1,5 @@
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
-const printError = require('./utils').printError;
-const createOutputDir = require('./utils').createOutputDir;
+const { getConfig, getTestRoot } = require('./utils');
+const { printError, createOutputDir } = require('./utils');
 const Config = require('../config');
 const Codecept = require('../rerun');
 

package/lib/command/run.js

@@ -1,8 +1,7 @@
 const mkdirp = require('mkdirp');
 const path = require('path');
 
-const getConfig = require('./utils').getConfig;
-const getTestRoot = require('./utils').getTestRoot;
+const { getConfig, getTestRoot } = require('./utils');
 const printError = require('./utils').printError;
 const createOutputDir = require('./utils').createOutputDir;
 const Config = require('../config');

package/lib/container.js

@@ -1,7 +1,7 @@
 const glob = require('glob');
 const path = require('path');
 
-const fileExists = require('./utils').fileExists;
+const { fileExists } = require('./utils');
 const Translation = require('./translation');
 const MochaFactory = require('./mochaFactory');
 const recorder = require('./recorder');
@@ -163,7 +163,7 @@ function createHelpers(config) {
       }
       helpers[helperName] = new HelperClass(config[helperName]);
     } catch (err) {
-      throw new Error(`Could not load helper ${helperName} from module '${moduleName}':\n${err.message}`);
+      throw new Error(`Could not load helper ${helperName} from module '${moduleName}':\n${err.message}\n${err.stack}`);
     }
   }
 

package/lib/data/context.js

@@ -1,4 +1,4 @@
-const isGenerator = require('../utils').isGenerator;
+const { isGenerator } = require('../utils');
 const DataTable = require('./table');
 const DataScenarioConfig = require('./dataScenarioConfig');
 

package/lib/event.js

@@ -1,7 +1,7 @@
 const events = require('events');
 
 const dispatcher = new events.EventEmitter();
-const log = require('./output').log;
+const { log } = require('./output');
 
 /**
  * @namespace

package/lib/helper/Appium.js

@@ -1,13 +1,12 @@
 let webdriverio;
 let wdioV4;
-let SCREEN_SIZE;
 
 const fs = require('fs');
 const requireg = require('requireg');
 
 const Webdriver = require('./WebDriver');
 const AssertionFailedError = require('../assert/error');
-const truth = require('../assert/truth').truth;
+const { truth } = require('../assert/truth');
 const recorder = require('../recorder');
 const Locator = require('../locator');
 const ConnectionRefused = require('./errors/ConnectionRefused');

package/lib/helper/FileSystem.js

@@ -3,9 +3,9 @@ const path = require('path');
 const fs = require('fs');
 
 const Helper = require('../helper');
-const fileExists = require('../utils').fileExists;
-const fileIncludes = require('../assert/include').fileIncludes;
-const fileEquals = require('../assert/equal').fileEquals;
+const { fileExists } = require('../utils');
+const { fileIncludes } = require('../assert/include');
+const { fileEquals } = require('../assert/equal');
 
 /**
  * Helper for testing filesystem.

package/lib/helper/Mochawesome.js

@@ -5,7 +5,7 @@ let currentSuite;
 const requireg = require('requireg');
 
 const Helper = require('../helper');
-const clearString = require('../utils').clearString;
+const { clearString } = require('../utils');
 
 class Mochawesome extends Helper {
   constructor(config) {

package/lib/helper/Nightmare.js

@@ -3,11 +3,11 @@ const requireg = require('requireg');
 const urlResolve = require('url').resolve;
 
 const Helper = require('../helper');
-const stringIncludes = require('../assert/include').includes;
-const urlEquals = require('../assert/equal').urlEquals;
-const equals = require('../assert/equal').equals;
-const empty = require('../assert/empty').empty;
-const truth = require('../assert/truth').truth;
+const { includes: stringIncludes } = require('../assert/include');
+const { urlEquals } = require('../assert/equal');
+const { equals } = require('../assert/equal');
+const { empty } = require('../assert/empty');
+const { truth } = require('../assert/truth');
 const Locator = require('../locator');
 const ElementNotFound = require('./errors/ElementNotFound');
 const {
@@ -1066,6 +1066,55 @@ class Nightmare extends Helper {
     return this.browser.refresh();
   }
 
+  /**
+   * {{> saveElementScreenshot }}
+   *
+   */
+  async saveElementScreenshot(locator, fileName) {
+    const outputFile = screenshotOutputFolder(fileName);
+
+    const rect = await this.grabElementBoundingRect(locator);
+
+    const button_clip = {
+      x: Math.floor(rect.x),
+      y: Math.floor(rect.y),
+      width: Math.floor(rect.width),
+      height: Math.floor(rect.height),
+    };
+
+    this.debug(`Screenshot of ${locator} element has been saved to ${outputFile}`);
+    // take the screenshot
+    await this.browser.screenshot(outputFile, button_clip);
+  }
+
+  /**
+   * {{> grabElementBoundingRect }}
+   */
+  async grabElementBoundingRect(locator, prop) {
+    locator = new Locator(locator, 'css');
+
+    const rect = await this.browser.evaluate(async (by, locator) => {
+      // store the button in a variable
+
+      const build_cluster_btn = await window.codeceptjs.findElement(by, locator);
+
+      // use the getClientRects() function on the button to determine
+      // the size and location
+      const rect = build_cluster_btn.getBoundingClientRect();
+
+      // convert the rectangle to a clip object and return it
+      return {
+        x: rect.left,
+        y: rect.top,
+        width: rect.width,
+        height: rect.height,
+      };
+    }, locator.type, locator.value);
+
+    if (prop) return rect[prop];
+    return rect;
+  }
+
   /**
    * {{> saveScreenshot }}
    */