codeceptjs 3.2.3 → 3.3.0-beta.1

package/docs/build/Appium.js

@@ -955,7 +955,7 @@ class Appium extends Webdriver {
    *
    * [See complete reference](http://webdriver.io/api/mobile/swipe.html)
    *
-   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {string | object} locator
    * @param {number} xoffset
    * @param {number} yoffset
    * @param {number} [speed=1000] (optional), 1000 by default
@@ -976,11 +976,11 @@ class Appium extends Webdriver {
    * Perform a swipe on the screen.
    *
    * ```js
-   * I.performswipe(100,200);
+   * I.performSwipe({ x: 300, y: 100 }, { x: 200, y: 100 });
    * ```
    *
-   * @param {number} from
-   * @param {number} to
+   * @param {object} from
+   * @param {object} to
    *
    * Appium: support Android and iOS
    */
@@ -1010,7 +1010,7 @@ class Appium extends Webdriver {
    * I.swipeDown(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {string | object} locator
    * @param {number} [yoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1039,7 +1039,7 @@ class Appium extends Webdriver {
    * I.swipeLeft(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {string | object} locator
    * @param {number} [xoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1066,7 +1066,7 @@ class Appium extends Webdriver {
    * I.swipeRight(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {string | object} locator
    * @param {number} [xoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1093,7 +1093,7 @@ class Appium extends Webdriver {
    * I.swipeUp(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {string | object} locator
    * @param {number} [yoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1335,7 +1335,7 @@ class Appium extends Webdriver {
    * ```js
    * I.appendField('#myTextField', 'appended');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator
    * @param {string} value text value to append.
    *
    */
@@ -1355,8 +1355,8 @@ class Appium extends Webdriver {
    * I.checkOption('I Agree to Terms and Conditions');
    * I.checkOption('agree', '//form');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+   * @param {string | object} field checkbox located by label | name | CSS | XPath | strict locator.
+   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
    *
    */
   async checkOption(field) {
@@ -1387,8 +1387,8 @@ class Appium extends Webdriver {
    * I.click({css: 'nav a.login'});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @param {string | object} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+   * @param {?string | object} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
    * 
    *
    */
@@ -1406,7 +1406,7 @@ class Appium extends Webdriver {
    * I.dontSeeCheckboxIsChecked('agree'); // located by name
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * 
    *
    */
@@ -1422,7 +1422,7 @@ class Appium extends Webdriver {
    * I.dontSeeElement('.modal'); // modal is not shown
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
+   * @param {string | object} locator located by CSS|XPath|Strict locator.
    */
   async dontSeeElement(locator) {
     if (this.isWeb) return super.dontSeeElement(locator);
@@ -1438,7 +1438,7 @@ class Appium extends Webdriver {
    * I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
    *
    */
@@ -1457,7 +1457,7 @@ class Appium extends Webdriver {
    * ```
    * 
    * @param {string} text which is not present.
-   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
    * 
    */
   async dontSee(text, context = null) {
@@ -1479,8 +1479,8 @@ class Appium extends Webdriver {
    * // or by strict locator
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {CodeceptJS.StringOrSecret} value text value to fill.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} value text value to fill.
    * 
    *
    */
@@ -1498,7 +1498,7 @@ class Appium extends Webdriver {
    * let pins = await I.grabTextFromAll('#pin li');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    *
@@ -1517,7 +1517,7 @@ class Appium extends Webdriver {
    * ```
    * If multiple elements found returns first element.
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    *
@@ -1535,7 +1535,7 @@ class Appium extends Webdriver {
    * let numOfElements = await I.grabNumberOfVisibleElements('p');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @returns {Promise<number>} number of visible elements
    */
   async grabNumberOfVisibleElements(locator) {
@@ -1553,7 +1553,7 @@ class Appium extends Webdriver {
    * ```js
    * let hint = await I.grabAttributeFrom('#tooltip', 'title');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string>} attribute value
    * 
@@ -1571,7 +1571,7 @@ class Appium extends Webdriver {
    * ```js
    * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string[]>} attribute value
    * 
@@ -1588,7 +1588,7 @@ class Appium extends Webdriver {
    * ```js
    * let inputs = await I.grabValueFromAll('//form/input');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    *
@@ -1606,7 +1606,7 @@ class Appium extends Webdriver {
    * ```js
    * let email = await I.grabValueFrom('input[name=email]');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    *
@@ -1640,7 +1640,7 @@ class Appium extends Webdriver {
    * I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "center" });
    * ```
    * 
-   * @param {LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @param {ScrollIntoViewOptions} scrollIntoViewOptions see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView.
    * 
    *
@@ -1659,7 +1659,7 @@ class Appium extends Webdriver {
    * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * 
    *
    */
@@ -1675,7 +1675,7 @@ class Appium extends Webdriver {
    * ```js
    * I.seeElement('#modal');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    *
    */
   async seeElement(locator) {
@@ -1693,7 +1693,7 @@ class Appium extends Webdriver {
    * I.seeInField('form input[type=hidden]','hidden_value');
    * I.seeInField('#searchform input','Search');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
    * 
    *
@@ -1713,7 +1713,7 @@ class Appium extends Webdriver {
    * I.see('Register', {css: 'form.register'}); // use strict locator
    * ```
    * @param {string} text expected on page.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
    *
    */
   async see(text, context) {
@@ -1740,7 +1740,7 @@ class Appium extends Webdriver {
    * ```js
    * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
    * ```
-   * @param {LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} select field located by label|name|CSS|XPath|strict locator.
    * @param {string|Array<*>} option visible text or value of option.
    * 
    *
@@ -1760,7 +1760,7 @@ class Appium extends Webdriver {
    * I.waitForElement('.btn.continue', 5); // wait for 5 secs
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec] (optional, `1` by default) time in seconds to wait
    *
    */
@@ -1777,7 +1777,7 @@ class Appium extends Webdriver {
    * I.waitForVisible('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    * 
    *
@@ -1795,7 +1795,7 @@ class Appium extends Webdriver {
    * I.waitForInvisible('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
    */
@@ -1816,7 +1816,7 @@ class Appium extends Webdriver {
    * 
    * @param {string }text to wait for.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator.
+   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator.
    *
    */
   async waitForText(text, sec = null, context = null) {

package/docs/build/GraphQL.js

@@ -59,6 +59,12 @@ class GraphQL extends Helper {
     }
   }
 
+  static _config() {
+    return [
+      { name: 'endpoint', message: 'Endpoint of API you are going to test', default: 'http://localhost:3000/graphql' },
+    ];
+  }
+
   /**
    * Executes query via axios call
    *
@@ -92,6 +98,11 @@ class GraphQL extends Helper {
       );
       response = err.response;
     }
+
+    if (this.config.onResponse) {
+      await this.config.onResponse(response);
+    }
+
     this.debugSection('Response', JSON.stringify(response.data));
     return response;
   }

package/docs/build/JSONResponse.js

@@ -0,0 +1,297 @@
+const chai = require('chai');
+const joi = require('joi');
+const chaiDeepMatch = require('chai-deep-match');
+const Helper = require('../helper');
+
+chai.use(chaiDeepMatch);
+
+const { expect } = chai;
+
+/**
+ * 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 extends Helper {
+  constructor(config = {}) {
+    super(config);
+    this.options = {
+      requestHelper: 'REST',
+    };
+    this.options = { ...this.options, ...config };
+  }
+
+  _beforeSuite() {
+    this.response = null;
+    if (!this.helpers[this.options.requestHelper]) {
+      throw new Error(`Error setting JSONResponse, helper ${this.options.requestHelper} is not enabled in config, helpers: ${Object.keys(this.helpers)}`);
+    }
+    // connect to REST helper
+    this.helpers[this.options.requestHelper].config.onResponse = (response) => {
+      this.response = response;
+    };
+  }
+
+  _before() {
+    this.response = null;
+  }
+
+  static _checkRequirements() {
+    try {
+      require('joi');
+      require('chai');
+    } catch (e) {
+      return ['joi'];
+    }
+  }
+
+  /**
+   * Checks that response code is equal to the provided one
+   *
+   * ```js
+   * I.seeResponseCodeIs(200);
+   * ```
+   *
+   * @param {number} code
+   */
+  seeResponseCodeIs(code) {
+    this._checkResponseReady();
+    expect(this.response.status).to.eql(code, 'Response code is not the same as expected');
+  }
+
+  /**
+   * Checks that response code is not equal to the provided one
+   *
+   * ```js
+   * I.dontSeeResponseCodeIs(500);
+   * ```
+   *
+   * @param {number} code
+   */
+  dontSeeResponseCodeIs(code) {
+    this._checkResponseReady();
+    expect(this.response.status).not.to.eql(code);
+  }
+
+  /**
+   * Checks that the response code is 4xx
+   */
+  seeResponseCodeIsClientError() {
+    this._checkResponseReady();
+    expect(this.response.status).to.be.gte(400);
+    expect(this.response.status).to.be.lt(500);
+  }
+
+  /**
+   * Checks that the response code is 3xx
+   */
+  seeResponseCodeIsRedirection() {
+    this._checkResponseReady();
+    expect(this.response.status).to.be.gte(300);
+    expect(this.response.status).to.be.lt(400);
+  }
+
+  /**
+   * Checks that the response code is 5xx
+   */
+  seeResponseCodeIsServerError() {
+    this._checkResponseReady();
+    expect(this.response.status).to.be.gte(500);
+    expect(this.response.status).to.be.lt(600);
+  }
+
+  /**
+   * Checks that the response code is 2xx
+   * Use it instead of seeResponseCodeIs(200) if server can return 204 instead.
+   *
+   * ```js
+   * I.seeResponseCodeIsSuccessful();
+   * ```
+   */
+  seeResponseCodeIsSuccessful() {
+    this._checkResponseReady();
+    expect(this.response.status).to.be.gte(200);
+    expect(this.response.status).to.be.lt(300);
+  }
+
+  /**
+   * 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' } });
+   * ```
+   *
+   * @param {object} json
+   */
+  seeResponseContainsJson(json = {}) {
+    this._checkResponseReady();
+    expect(this.response.data).to.deep.match(json);
+  }
+
+  /**
+   * Checks for deep inclusion of a provided json in a response data.
+   *
+   * ```js
+   * // response.data == { data: { user: 1 } }
+   *
+   * I.dontSeeResponseContainsJson({ user: 2 });
+   * ```
+   *
+   * @param {object} json
+   */
+  dontSeeResponseContainsJson(json = {}) {
+    this._checkResponseReady();
+    expect(this.response.data).not.to.deep.match(json);
+  }
+
+  /**
+   * 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']);
+   * ```
+   *
+   * @param {array} keys
+   */
+  seeResponseContainsKeys(keys = []) {
+    this._checkResponseReady();
+    expect(this.response.data).to.include.keys(keys);
+  }
+
+  /**
+   * 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']);
+   * });
+   * ```
+   *
+   * @param {function} fn
+   */
+  seeResponseValidByCallback(fn) {
+    this._checkResponseReady();
+    fn({ ...this.response, expect });
+    const body = fn.toString();
+    fn.toString = () => `${body.split('\n')[1]}...`;
+  }
+
+  /**
+   * Checks that response data equals to expected:
+   *
+   * ```js
+   * // response.data is { error: 'Not allowed' }
+   *
+   * I.seeResponseEquals({ error: 'Not allowed' })
+   * ```
+   * @param {object} resp
+   */
+  seeResponseEquals(resp) {
+    this._checkResponseReady();
+    expect(this.response.data).to.deep.equal(resp);
+  }
+
+  /**
+   * 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();
+   * });
+   * ```
+   *
+   * @param {any} fnOrSchema
+   */
+  seeResponseMatchesJsonSchema(fnOrSchema) {
+    this._checkResponseReady();
+    let schema = fnOrSchema;
+    if (typeof fnOrSchema === 'function') {
+      schema = fnOrSchema(joi);
+      const body = fnOrSchema.toString();
+      fnOrSchema.toString = () => `${body.split('\n')[1]}...`;
+    }
+    if (!schema) throw new Error('Empty Joi schema provided, see https://joi.dev/ for details');
+    if (!joi.isSchema(schema)) throw new Error('Invalid Joi schema provided, see https://joi.dev/ for details');
+    schema.toString = () => schema.describe();
+    joi.assert(this.response.data, schema);
+  }
+
+  _checkResponseReady() {
+    if (!this.response) throw new Error('Response is not available');
+  }
+}
+
+module.exports = JSONResponse;