codeceptjs 3.2.3 → 3.3.0-beta.1

package/lib/plugin/allure.js

@@ -64,6 +64,18 @@ const defaultConfig = {
  * * `addAttachment(name, buffer, type)` - add an attachment to current test / suite
  * * `addLabel(name, value)` - adds a label to current test
  * * `addParameter(kind, name, value)` - adds a parameter to current test
+ * * `createStep(name, stepFunc)` - create a step, stepFunc could consist an attachment
+ * Example of usage:
+ * ```js
+ *     allure.createStep('New created step', () => {
+ *       allure.addAttachment(
+ *         'Request params',
+ *         '{"clientId":123, "name":"Tom", "age":29}',
+ *         'application/json'
+ *       );
+ *     });
+ * ```
+ * ![Created Step Image](https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png)
  * * `severity(value)` - adds severity label
  * * `epic(value)` - adds epic label
  * * `feature(value)` - adds feature label

package/lib/plugin/eachElement.js

@@ -0,0 +1,127 @@
+const output = require('../output');
+const store = require('../store');
+const recorder = require('../recorder');
+const container = require('../container');
+const event = require('../event');
+const Step = require('../step');
+const { isAsyncFunction } = require('../utils');
+
+const defaultConfig = {
+  registerGlobal: true,
+};
+
+/**
+ * Provides `eachElement` global function to iterate over found elements to perform actions on them.
+ *
+ * `eachElement` takes following args:
+ * * `purpose` - the goal of an action. A comment text that will be displayed in output.
+ * * `locator` - a CSS/XPath locator to match elements
+ * * `fn(element, index)` - **asynchronous** function which will be executed for each matched element.
+ *
+ * Example of usage:
+ *
+ * ```js
+ * // this example works with Playwright and Puppeteer helper
+ * await eachElement('click all checkboxes', 'form input[type=checkbox]', async (el) => {
+ *   await el.click();
+ * });
+ * ```
+ * Click odd elements:
+ *
+ * ```js
+ * // this example works with Playwright and Puppeteer helper
+ * await eachElement('click odd buttons', '.button-select', async (el, index) => {
+ *   if (index % 2) await el.click();
+ * });
+ * ```
+ *
+ * Check all elements for visibility:
+ *
+ * ```js
+ * // this example works with Playwright and Puppeteer helper
+ * const assert = require('assert');
+ * await eachElement('check all items are visible', '.item', async (el) => {
+ *   assert(await el.isVisible());
+ * });
+ * ```
+ * This method works with WebDriver, Playwright, Puppeteer, Appium helpers.
+ *
+ * Function parameter `el` represents a matched element.
+ * Depending on a helper API of `el` can be different. Refer to API of corresponding browser testing engine for a complete API list:
+ *
+ * * [Playwright ElementHandle](https://playwright.dev/docs/api/class-elementhandle)
+ * * [Puppeteer](https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle)
+ * * [webdriverio element](https://webdriver.io/docs/api)
+ *
+ * #### Configuration
+ *
+ * * `registerGlobal` - to register `eachElement` function globally, true by default
+ *
+ * If `registerGlobal` is false you can use eachElement from the plugin:
+ *
+ * ```js
+ * const eachElement = codeceptjs.container.plugins('eachElement');
+ * ```
+ *
+ * @param {string}  purpose
+ * @param {CodeceptJS.LocatorOrString}  locator
+ * @param {Function}  fn
+ * @return {Promise<*> | undefined}
+ */
+function eachElement(purpose, locator, fn) {
+  if (store.dryRun) return;
+  const helpers = Object.values(container.helpers());
+
+  const helper = helpers.filter(h => !!h._locate)[0];
+
+  if (!helper) {
+    throw new Error('No helper enabled with _locate method with returns a list of elements.');
+  }
+
+  if (!isAsyncFunction(fn)) {
+    throw new Error('Async function should be passed into each element');
+  }
+
+  const step = new Step(helper, `${purpose || 'each element'} within "${locator}"`);
+  step.helperMethod = '_locate';
+  // eachElement('select all users', 'locator', async (el) => {
+  event.dispatcher.emit(event.step.before, step);
+
+  return recorder.add('register each element wrapper', async () => {
+    event.emit(event.step.started, step);
+    const els = await helper._locate(locator);
+    output.debug(`Found ${els.length} elements for each elements to iterate`);
+
+    const errs = [];
+    let i = 0;
+    for (const el of els) {
+      try {
+        await fn(el, i);
+      } catch (err) {
+        output.error(`eachElement: failed operation on element #${i} ${el}`);
+        errs.push(err);
+      }
+      i++;
+    }
+
+    if (errs.length) {
+      event.dispatcher.emit(event.step.after, step);
+      event.emit(event.step.failed, step, errs[0]);
+      event.emit(event.step.finished, step);
+      throw errs[0];
+    }
+
+    event.dispatcher.emit(event.step.after, step);
+    event.emit(event.step.passed, step, null);
+    event.emit(event.step.finished, step);
+  });
+}
+
+module.exports = function (config) {
+  config = Object.assign(defaultConfig, config);
+
+  if (config.registerGlobal) {
+    global.eachElement = eachElement;
+  }
+  return eachElement;
+};

package/lib/utils.js

@@ -431,3 +431,23 @@ module.exports.modifierKeys = modifierKeys;
 module.exports.isModifierKey = function (key) {
   return modifierKeys.includes(key);
 };
+
+module.exports.requireWithFallback = function (...packages) {
+  const exists = function (pkg) {
+    try {
+      require.resolve(pkg);
+    } catch (e) {
+      return false;
+    }
+
+    return true;
+  };
+
+  for (const pkg of packages) {
+    if (exists(pkg)) {
+      return require(pkg);
+    }
+  }
+
+  throw new Error(`Cannot find modules ${packages.join(',')}`);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.2.3",
+  "version": "3.3.0-beta.1",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -59,6 +59,7 @@
     "allure-js-commons": "^1.3.2",
     "arrify": "^2.0.1",
     "axios": "^0.21.1",
+    "chai-deep-match": "^1.2.1",
     "chalk": "^4.1.0",
     "commander": "^2.20.3",
     "cross-spawn": "^7.0.3",
@@ -72,6 +73,7 @@
     "gherkin": "^5.1.0",
     "glob": "^6.0.1",
     "inquirer": "^6.5.2",
+    "joi": "^17.6.0",
     "js-beautify": "^1.11.0",
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
@@ -97,7 +99,7 @@
     "@wdio/selenium-standalone-service": "^5.16.10",
     "@wdio/utils": "^5.23.0",
     "apollo-server-express": "^2.19.0",
-    "chai": "^3.4.1",
+    "chai": "^3.5.0",
     "chai-as-promised": "^5.2.0",
     "chai-subset": "^1.6.0",
     "contributor-faces": "^1.0.3",
@@ -110,7 +112,7 @@
     "eslint-plugin-mocha": "^6.3.0",
     "expect": "^26.6.2",
     "express": "^4.17.1",
-    "faker": "^5.5.1",
+    "faker": "5.5.3",
     "form-data": "^3.0.0",
     "graphql": "^14.6.0",
     "husky": "^4.3.5",
@@ -120,7 +122,7 @@
     "mocha-parallel-tests": "^2.3.0",
     "nightmare": "^3.0.2",
     "nodemon": "^1.19.4",
-    "playwright": "^1.9.1",
+    "playwright": "^1.18.1",
     "puppeteer": "^10.0.0",
     "qrcode-terminal": "^0.12.0",
     "rosie": "^1.6.0",

package/translations/pt-BR.js

@@ -1,5 +1,13 @@
 module.exports = {
   I: 'Eu',
+  contexts: {
+    Feature: 'Funcionalidade',
+    Scenario: 'Cenário',
+    Before: 'Antes',
+    After: 'Depois',
+    BeforeSuite: 'AntesDaSuite',
+    AfterSuite: 'DepoisDaSuite',
+  },
   actions: {
     amOutsideAngularApp: 'naoEstouEmAplicacaoAngular',
     amInsideAngularApp: 'estouNaAplicacaoAngular',

package/typings/index.d.ts

@@ -2,6 +2,8 @@
 /// <reference path="./types.d.ts" />
 /// <reference types="webdriverio" />
 /// <reference path="./Mocha.d.ts" />
+/// <reference types="joi" />
+/// <reference types="playwright" />
 
 declare namespace CodeceptJS {
   type WithTranslation<T> = T &

package/typings/types.d.ts

@@ -186,11 +186,14 @@ declare namespace CodeceptJS {
          * // 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: any, params: any): void;
+        have(factory: any, params: any, options: any): void;
         /**
          * Generates bunch of records and saves multiple API requests to store them.
          *
@@ -200,9 +203,12 @@ declare namespace CodeceptJS {
          *
          * // 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' });
          * ```
          */
-        haveMultiple(factory: any, times: any, params: any): void;
+        haveMultiple(factory: any, times: any, params: any, options: any): void;
         /**
          * Executes request to create a record in API.
          * Can be replaced from a in custom helper.
@@ -560,11 +566,11 @@ declare namespace CodeceptJS {
          * Perform a swipe on the screen.
          *
          * ```js
-         * I.performswipe(100,200);
+         * I.performSwipe({ x: 300, y: 100 }, { x: 200, y: 100 });
          * ```
          * @param to - Appium: support Android and iOS
          */
-        performSwipe(from: number, to: number): void;
+        performSwipe(from: any, to: any): void;
         /**
          * Perform a swipe down on an element.
          *
@@ -1433,6 +1439,179 @@ declare namespace CodeceptJS {
          */
         _requestDelete(operation: string, data: any): void;
     }
+    /**
+     * This helper allows performing assertions on JSON responses paired with following helpers:
+     *
+     * * REST
+     * * GraphQL
+     * * Playwright
+     *
+     * It can check status codes, response data, response structure.
+     *
+     *
+     * ## Configuration
+     *
+     * * `requestHelper` - a helper which will perform requests. `REST` by default, also `Playwright` or `GraphQL` can be used. Custom helpers must have `onResponse` hook in their config, which will be executed when request is performed.
+     *
+     * ### Examples
+     *
+     * Zero-configuration when paired with REST:
+     *
+     * ```js
+     * // inside codecept.conf.js
+     * {
+     *   helpers: {
+     *     REST: {
+     *       endpoint: 'http://site.com/api',
+     *     },
+     *     JSONResponse: {}
+     *   }
+     * }
+     * ```
+     * Explicitly setting request helper if you use `makeApiRequest` of Playwright to perform requests and not paired REST:
+     *
+     * ```js
+     * // inside codecept.conf.js
+     * // ...
+     *   helpers: {
+     *     Playwright: {
+     *       url: 'https://localhost',
+     *       browser: 'chromium',
+     *     },
+     *     JSONResponse: {
+     *       requestHelper: 'Playwright',
+     *     }
+     *   }
+     * ```
+     * ## Access From Helpers
+     *
+     * If you plan to add custom assertions it is recommended to create a helper that will retrieve response object from JSONResponse:
+     *
+     *
+     * ```js
+     * // inside custom helper
+     * const response = this.helpers.JSONResponse.response;
+     * ```
+     *
+     * ## Methods
+     */
+    class JSONResponse {
+        /**
+         * Checks that response code is equal to the provided one
+         *
+         * ```js
+         * I.seeResponseCodeIs(200);
+         * ```
+         */
+        seeResponseCodeIs(code: number): void;
+        /**
+         * Checks that response code is not equal to the provided one
+         *
+         * ```js
+         * I.dontSeeResponseCodeIs(500);
+         * ```
+         */
+        dontSeeResponseCodeIs(code: number): void;
+        /**
+         * Checks that the response code is 4xx
+         */
+        seeResponseCodeIsClientError(): void;
+        /**
+         * Checks that the response code is 3xx
+         */
+        seeResponseCodeIsRedirection(): void;
+        /**
+         * Checks that the response code is 5xx
+         */
+        seeResponseCodeIsServerError(): void;
+        /**
+         * Checks that the response code is 2xx
+         * Use it instead of seeResponseCodeIs(200) if server can return 204 instead.
+         *
+         * ```js
+         * I.seeResponseCodeIsSuccessful();
+         * ```
+         */
+        seeResponseCodeIsSuccessful(): void;
+        /**
+         * Checks for deep inclusion of a provided json in a response data.
+         *
+         * ```js
+         * // response.data == { user: { name: 'jon', email: 'jon@doe.com' } }
+         *
+         * I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
+         * ```
+         */
+        seeResponseContainsJson(json: any): void;
+        /**
+         * Checks for deep inclusion of a provided json in a response data.
+         *
+         * ```js
+         * // response.data == { data: { user: 1 } }
+         *
+         * I.dontSeeResponseContainsJson({ user: 2 });
+         * ```
+         */
+        dontSeeResponseContainsJson(json: any): void;
+        /**
+         * Checks for deep inclusion of a provided json in a response data.
+         *
+         * ```js
+         * // response.data == { user: { name: 'jon', email: 'jon@doe.com' } }
+         *
+         * I.seeResponseContainsKeys(['user']);
+         * ```
+         */
+        seeResponseContainsKeys(keys: any[]): void;
+        /**
+         * Executes a callback function passing in `response` object and chai assertions with `expect`
+         * Use it to perform custom checks of response data
+         *
+         * ```js
+         * I.seeResponseValidByCallback({ data, status, expect } => {
+         *   expect(status).to.eql(200);
+         *   expect(data).keys.to.include(['user', 'company']);
+         * });
+         * ```
+         */
+        seeResponseValidByCallback(fn: (...params: any[]) => any): void;
+        /**
+         * Checks that response data equals to expected:
+         *
+         * ```js
+         * // response.data is { error: 'Not allowed' }
+         *
+         * I.seeResponseEquals({ error: 'Not allowed' })
+         * ```
+         */
+        seeResponseEquals(resp: any): void;
+        /**
+         * Validates JSON structure of response using [joi library](https://joi.dev).
+         * See [joi API](https://joi.dev/api/) for complete reference on usage.
+         *
+         * Use pre-initialized joi instance by passing function callback:
+         *
+         * ```js
+         * // response.data is { name: 'jon', id: 1 }
+         *
+         * I.seeResponseMatchesJsonSchema(joi => {
+         *   return joi.object({
+         *     name: joi.string();
+         *     id: joi.number();
+         *   })
+         * });
+         *
+         * // or pass a valid schema
+         * const joi = require('joi);
+         *
+         * I.seeResponseMatchesJsonSchema(joi.object({
+         *   name: joi.string();
+         *   id: joi.number();
+         * });
+         * ```
+         */
+        seeResponseMatchesJsonSchema(fnOrSchema: any): void;
+    }
     /**
      * Nightmare helper wraps [Nightmare](https://github.com/segmentio/nightmare) library to provide
      * fastest headless testing using Electron engine. Unlike Selenium-based drivers this uses
@@ -2385,12 +2564,18 @@ declare namespace CodeceptJS {
      *
      * This helper works with a browser out of the box with no additional tools required to install.
      *
-     * Requires `playwright` package version ^1 to be installed:
+     * Requires `playwright` or `playwright-core` package version ^1 to be installed:
      *
      * ```
-     * npm i playwright@^1 --save
+     * npm i playwright@^1.18 --save
+     * ```
+     * or
+     * ```
+     * npm i playwright-core@^1.18 --save
      * ```
      *
+     * Using playwright-core package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one.
+     *
      * ## Configuration
      *
      * This helper should be configured in codecept.json or codecept.conf.js
@@ -2574,15 +2759,15 @@ declare namespace CodeceptJS {
          * First argument is a description of an action.
          * Second argument is async function that gets this helper as parameter.
          *
-         * { [`page`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md), [`context`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md) [`browser`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md) } objects from Playwright API are available.
+         * { [`page`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md), [`browserContext`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md) [`browser`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md) } objects from Playwright API are available.
          *
          * ```js
-         * I.usePlaywrightTo('emulate offline mode', async ({ context }) => {
-         *   await context.setOffline(true);
+         * I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => {
+         *   await browserContext.setOffline(true);
          * });
          * ```
          * @param description - used to show in logs.
-         * @param fn - async functuion that executed with Playwright helper as argument
+         * @param fn - async function that executed with Playwright helper as argument
          */
         usePlaywrightTo(description: string, fn: (...params: any[]) => any): void;
         /**
@@ -3713,6 +3898,23 @@ declare namespace CodeceptJS {
          * @param [fullPage = false] - (optional, `false` by default) flag to enable fullscreen screenshot mode.
          */
         saveScreenshot(fileName: string, fullPage?: boolean): void;
+        /**
+         * Performs [api request](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get) using
+         * the cookies from the current browser session.
+         *
+         * ```js
+         * const users = await I.makeApiRequest('GET', '/api/users', { params: { page: 1 }});
+         * users[0]
+         * I.makeApiRequest('PATCH', )
+         * ```
+         *
+         * > This is Playwright's built-in alternative to using REST helper's sendGet, sendPost, etc methods.
+         * @param method - HTTP method
+         * @param url - endpoint
+         * @param options - request options depending on method used
+         * @returns response
+         */
+        makeApiRequest(method: string, url: string, options: any): Promise<object>;
         /**
          * Pauses execution for a number of seconds.
          *
@@ -5274,7 +5476,15 @@ declare namespace CodeceptJS {
      * Browser control is executed via DevTools Protocol (instead of Selenium).
      * This helper works with a browser out of the box with no additional tools required to install.
      *
-     * Requires `puppeteer` package to be installed.
+     * Requires `puppeteer` or `puppeteer-core` package to be installed.
+     * ```
+     * npm i puppeteer --save
+     * ```
+     * or
+     * ```
+     * npm i puppeteer-core --save
+     * ```
+     * Using `puppeteer-core` package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one.
      *
      * > Experimental Firefox support [can be activated](https://codecept.io/helpers/Puppeteer-firefox).
      *
@@ -6919,6 +7129,21 @@ declare namespace CodeceptJS {
      * ## Methods
      */
     class REST {
+        /**
+         * Sets request headers for all requests of this test
+         * @param headers - headers list
+         */
+        haveRequestHeaders(headers: any): void;
+        /**
+         * Adds a header for Bearer authentication
+         *
+         * ```js
+         * // we use secret function to hide token from logs
+         * I.amBearerAuthenticated(secret('heregoestoken'))
+         * ```
+         * @param accessToken - Bearer access token
+         */
+        amBearerAuthenticated(accessToken: string): void;
         /**
          * Executes axios request
          * @returns response
@@ -9819,6 +10044,7 @@ declare namespace CodeceptJS {
          * 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.