codeceptjs 3.2.2 → 3.3.0-beta.3

package/docs/webdriver.md

@@ -203,8 +203,6 @@ Scenario('login test', ({ I }) => {
   I.see('Welcome, John');
 });
 ```
-> ▶ Actions like `amOnPage`, `click`, `fillField` are not limited to WebDriver only. They work similarly for all available helpers. [Go to Basics guide to learn them](/basics#writing-tests).
-
 
 An empty test case can be created with `npx codeceptjs gt` command.
 
@@ -212,6 +210,43 @@ An empty test case can be created with `npx codeceptjs gt` command.
 npx codeceptjs gt
 ```
 
+
+### Actions
+
+Tests consist with a scenario of user's action taken on a page. The most widely used ones are:
+
+* `amOnPage` - to open a webpage (accepts relative or absolute url)
+* `click` - to locate a button or link and click on it
+* `fillField` - to enter a text inside a field
+* `selectOption`, `checkOption` - to interact with a form
+* `wait*` to wait for some parts of page to be fully rendered (important for testing SPA)
+* `grab*` to get values from page sources
+* `see`, `dontSee` - to check for a text on a page
+* `seeElement`, `dontSeeElement` - to check for elements on a page
+
+> ℹ  All actions are listed in [WebDriver helper reference](https://codecept.io/helpers/WebDriver/).*
+
+All actions which interact with elements **support CSS and XPath locators**. Actions like `click` or `fillField` by locate elements by their name or value on a page:
+
+```js
+// search for link or button
+I.click('Login');
+// locate field by its label
+I.fillField('Name', 'Miles');
+// we can use input name
+I.fillField('user[email]','miles@davis.com');
+```
+
+You can also specify the exact locator type with strict locators:
+
+```js
+I.click({css: 'button.red'});
+I.fillField({name: 'user[email]'},'miles@davis.com');
+I.seeElement({xpath: '//body/header'});
+```
+
+### Interactive Pause
+
 It's easy to start writing a test if you use [interactive pause](/basics#debug). Just open a web page and pause execution.
 
 ```js
@@ -250,7 +285,7 @@ An interactive shell output may look like this:
 ```
 After typing in successful commands you can copy them into a test.
 
-Here is a test checking basic [todo application](http://todomvc.com/).
+Here is a test checking basic [todo application](https://todomvc.com/).
 
 ```js
 Feature('TodoMVC');
@@ -268,6 +303,59 @@ Scenario('create todo item', ({ I }) => {
 
 WebDriver helper supports standard [CSS/XPath and text locators](/locators) as well as non-trivial [React locators](/react) and [Shadow DOM](/shadow).
 
+### Grabbers
+
+If you need to get element's value inside a test you can use `grab*` methods. They should be used with `await` operator inside `async` function:
+
+```js
+const assert = require('assert');
+Scenario('get value of current tasks', async ({ I }) => {
+  I.fillField('.todo', 'my first item');
+  I.pressKey('Enter')
+  I.fillField('.todo', 'my second item');
+  I.pressKey('Enter')
+  let numTodos = await I.grabTextFrom('.todo-count strong');
+  assert.equal(2, numTodos);
+});
+```
+
+### Within
+
+In case some actions should be taken inside one element (a container or modal window or iframe) you can use `within` block to narrow the scope.
+Please take a note that you can't use within inside another within in Puppeteer helper:
+
+```js
+await within('.todoapp', () => {
+  I.fillField('.todo', 'my new item');
+  I.pressKey('Enter')
+  I.see('1 item left', '.todo-count');
+  I.click('.todo-list input.toggle');
+});
+I.see('0 items left', '.todo-count');
+```
+
+### Each Element <Badge text="Since 3.3" type="warning"/>
+
+Usually, CodeceptJS performs an action on the first matched element. 
+In case you want to do an action on each element found, use the special function `eachElement` which comes from [eachElement](https://codecept.io/plugins/#eachelement) plugin. 
+
+`eachElement` function matches all elements by locator and performs a callback on each of those element. A callback function receives element of webdriverio. `eachElement` may perform arbitrary actions on a page, so the first argument should by a description of the actions performed. This description will be used for logging purposes.
+
+Usage example
+
+```js
+await eachElement(
+  'click all checkboxes', 
+  'input.custom-checkbox', 
+  async (el, index) => {
+    await el.click();
+  });
+);
+```
+
+> ℹ Learn more about [eachElement plugin](/plugins/#eachelement)
+
+
 ## Waiting
 
 Web applications do not always respond instantly. That's why WebDriver protocol has methods to wait for changes on a page. CodeceptJS provides such commands prefixed with `wait*` so you could explicitly define what effects we wait for.
@@ -295,7 +383,7 @@ exports.config = {
 
 ## SmartWait
 
-It is possible to wait for elements pragmatically. If a test uses element which is not on a page yet, CodeceptJS will wait for few extra seconds before failing. This feature is based on [Implicit Wait](http://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits) of Selenium. CodeceptJS enables implicit wait only when searching for a specific element and disables in all other cases. Thus, the performance of a test is not affected.
+It is possible to wait for elements pragmatically. If a test uses element which is not on a page yet, CodeceptJS will wait for few extra seconds before failing. This feature is based on [Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits) of Selenium. CodeceptJS enables implicit wait only when searching for a specific element and disables in all other cases. Thus, the performance of a test is not affected.
 
 SmartWait can be enabled by setting wait option in WebDriver config.
 Add `smartWait: 5000` to wait for additional 5s.

package/lib/cli.js

@@ -7,6 +7,7 @@ const { MetaStep } = require('./step');
 
 const cursor = Base.cursor;
 let currentMetaStep = [];
+let codeceptjsEventDispatchersRegistered = false;
 
 class Cli extends Base {
   constructor(runner, opts) {
@@ -77,29 +78,33 @@ class Cli extends Base {
         }
       });
 
-      event.dispatcher.on(event.step.started, (step) => {
-        let processingStep = step;
-        const metaSteps = [];
-        while (processingStep.metaStep) {
-          metaSteps.unshift(processingStep.metaStep);
-          processingStep = processingStep.metaStep;
-        }
-        const shift = metaSteps.length;
+      if (!codeceptjsEventDispatchersRegistered) {
+        codeceptjsEventDispatchersRegistered = true;
 
-        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]);
+        event.dispatcher.on(event.step.started, (step) => {
+          let processingStep = step;
+          const metaSteps = [];
+          while (processingStep.metaStep) {
+            metaSteps.unshift(processingStep.metaStep);
+            processingStep = processingStep.metaStep;
           }
-        }
-        currentMetaStep = metaSteps;
-        output.stepShift = 3 + 2 * shift;
-        output.step(step);
-      });
+          const shift = metaSteps.length;
 
-      event.dispatcher.on(event.step.finished, () => {
-        output.stepShift = 0;
-      });
+          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]);
+            }
+          }
+          currentMetaStep = metaSteps;
+          output.stepShift = 3 + 2 * shift;
+          output.step(step);
+        });
+
+        event.dispatcher.on(event.step.finished, () => {
+          output.stepShift = 0;
+        });
+      }
     }
 
     runner.on('suite end', suite => {

package/lib/command/init.js

@@ -22,7 +22,7 @@ const defaultConfig = {
   mocha: {},
 };
 
-const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'TestCafe', 'Protractor', 'Nightmare', 'Appium'];
+const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'REST', 'GraphQL', 'Appium', 'TestCafe', 'Nightmare'];
 const translations = Object.keys(require('../../translations'));
 
 const noTranslation = 'English (no localization)';
@@ -30,12 +30,15 @@ translations.unshift(noTranslation);
 
 let packages;
 
-const configHeader = `const { setHeadlessWhen } = require('@codeceptjs/configure');
+const configHeader = `const { setHeadlessWhen, setCommonPlugins } = require('@codeceptjs/configure');
 
 // turn on headless mode when running with HEADLESS=true environment variable
 // export HEADLESS=true && npx codeceptjs run
 setHeadlessWhen(process.env.HEADLESS);
 
+// enable all common plugins https://github.com/codeceptjs/configure#setcommonplugins
+setCommonPlugins();
+
 `;
 
 const defaultActor = `// in this file you can append custom step methods to 'I' object
@@ -150,19 +153,6 @@ module.exports = function (initPath) {
       config.include.I = stepFile;
       print(`Steps file created at ${stepFile}`);
 
-      config.plugins = {
-        pauseOnFail: {},
-        retryFailedStep: {
-          enabled: true,
-        },
-        tryTo: {
-          enabled: true,
-        },
-        screenshotOnFail: {
-          enabled: true,
-        },
-      };
-
       let configSource = beautify(`exports.config = ${inspect(config, false, 4, false)}`);
 
       if (require.resolve('@codeceptjs/configure') && isLocal && !initPath) {

package/lib/command/workers/runTests.js

@@ -73,6 +73,27 @@ function filterTests() {
 }
 
 function initializeListeners() {
+  function simplifyError(error) {
+    if (error) {
+      const {
+        stack,
+        uncaught,
+        message,
+        actual,
+        expected,
+      } = error;
+
+      return {
+        stack,
+        uncaught,
+        message,
+        actual,
+        expected,
+      };
+    }
+
+    return null;
+  }
   function simplifyTest(test, err = null) {
     test = { ...test };
 
@@ -82,13 +103,10 @@ function initializeListeners() {
     }
 
     if (test.err) {
-      err = {
-        stack: test.err.stack,
-        uncaught: test.err.uncaught,
-        message: test.err.message,
-        actual: test.err.actual,
-        expected: test.err.expected,
-      };
+      err = simplifyError(test.err);
+      test.status = 'failed';
+    } else if (err) {
+      err = simplifyError(err);
       test.status = 'failed';
     }
     const parent = {};

package/lib/config.js

@@ -38,6 +38,14 @@ const defaultConfig = {
 let hooks = [];
 let config = {};
 
+const configFileNames = [
+  'codecept.config.js',
+  'codecept.conf.js',
+  'codecept.json',
+  'codecept.config.ts',
+  'codecept.conf.ts',
+];
+
 /**
  * Current configuration
  */
@@ -59,6 +67,7 @@ class Config {
    * If js file provided: require it and get .config key
    * If json file provided: load and parse JSON
    * If directory provided:
+   * * try to load `codecept.config.js` from it
    * * try to load `codecept.conf.js` from it
    * * try to load `codecept.json` from it
    * If none of above: fail.
@@ -78,23 +87,18 @@ class Config {
       return loadConfigFile(configFile);
     }
 
-    // is path to directory
-    const jsConfig = path.join(configFile, 'codecept.conf.js');
-    if (isFile(jsConfig)) {
-      return loadConfigFile(jsConfig);
-    }
+    for (const name of configFileNames) {
+      // is path to directory
+      const jsConfig = path.join(configFile, name);
 
-    const jsonConfig = path.join(configFile, 'codecept.json');
-    if (isFile(jsonConfig)) {
-      return loadConfigFile(jsonConfig);
+      if (isFile(jsConfig)) {
+        return loadConfigFile(jsConfig);
+      }
     }
 
-    const tsConfig = path.join(configFile, 'codecept.conf.ts');
-    if (isFile(tsConfig)) {
-      return loadConfigFile(tsConfig);
-    }
+    const configPaths = configFileNames.map(name => path.join(configFile, name)).join(' or ');
 
-    throw new Error(`Can not load config from ${jsConfig} or ${jsonConfig} or ${tsConfig}\nCodeceptJS is not initialized in this dir. Execute 'codeceptjs init' to start`);
+    throw new Error(`Can not load config from ${configPaths}\nCodeceptJS is not initialized in this dir. Execute 'codeceptjs init' to start`);
   }
 
   /**

package/lib/helper/ApiDataFactory.js

@@ -257,13 +257,16 @@ class ApiDataFactory extends Helper {
    * // create user with defined email
    * // and receive it when inside async function
    * const user = await I.have('user', { email: 'user@user.com'});
+   * // create a user with options that will not be included in the final request
+   * I.have('user', { }, { age: 33, height: 55 })
    * ```
    *
    * @param {*} factory factory to use
    * @param {*} params predefined parameters
+   * @param {*} options options for programmatically generate the attributes
    */
-  have(factory, params) {
-    const item = this._createItem(factory, params);
+  have(factory, params, options) {
+    const item = this._createItem(factory, params, options);
     this.debug(`Creating ${factory} ${JSON.stringify(item)}`);
     return this._requestCreate(factory, item);
   }
@@ -277,21 +280,25 @@ class ApiDataFactory extends Helper {
    *
    * // create 3 posts by one author
    * I.haveMultiple('post', 3, { author: 'davert' });
+   *
+   * // create 3 posts by one author with options
+   * I.haveMultiple('post', 3, { author: 'davert' }, { publish_date: '01.01.1997' });
    * ```
    *
    * @param {*} factory
    * @param {*} times
    * @param {*} params
+   * @param {*} options
    */
-  haveMultiple(factory, times, params) {
+  haveMultiple(factory, times, params, options) {
     const promises = [];
     for (let i = 0; i < times; i++) {
-      promises.push(this.have(factory, params));
+      promises.push(this.have(factory, params, options));
     }
     return Promise.all(promises);
   }
 
-  _createItem(model, data) {
+  _createItem(model, data, options) {
     if (!this.factories[model]) {
       throw new Error(`Factory ${model} is not defined in config`);
     }
@@ -303,7 +310,7 @@ class ApiDataFactory extends Helper {
         modulePath = path.join(global.codecept_dir, modulePath);
       }
       const builder = require(modulePath);
-      return builder.build(data);
+      return builder.build(data, options);
     } catch (err) {
       throw new Error(`Couldn't load factory file from ${modulePath}, check that