codeceptjs 3.5.12-beta.1 → 3.5.12-beta.2

package/docs/build/Expect.js

@@ -0,0 +1,422 @@
+const chai = require('chai');
+const output = require('../output');
+
+const { expect } = chai;
+
+chai.use(require('chai-string'));
+// @ts-ignore
+chai.use(require('chai-exclude'));
+chai.use(require('chai-match-pattern'));
+
+/**
+ * This helper allows performing assertions based on Chai.
+ *
+ * ### Examples
+ *
+ * Zero-configuration when paired with other helpers like REST, Playwright:
+ *
+ * ```js
+ * // inside codecept.conf.js
+ *{
+ *   helpers: {
+ *     Playwright: {...},
+ *     Expect: {},
+ *   }
+ *}
+ * ```
+ *
+ * ## Methods
+ */
+class ExpectHelper {
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+     */
+  expectEqual(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to equal "${JSON.stringify(expectedValue)}"`);
+    return expect(actualValue, customErrorMsg).to.equal(expectedValue);
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+     */
+  expectNotEqual(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to not equal "${JSON.stringify(expectedValue)}"`);
+    return expect(actualValue, customErrorMsg).not.to.equal(expectedValue);
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+
+     */
+  expectDeepEqual(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to deep equal "${JSON.stringify(expectedValue)}"`);
+    return expect(actualValue, customErrorMsg).to.deep.equal(expectedValue);
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+     */
+  expectNotDeepEqual(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to not deep equal "${JSON.stringify(expectedValue)}"`);
+    return expect(actualValue, customErrorMsg).to.not.deep.equal(expectedValue);
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValueToContain
+     * @param {*} [customErrorMsg]
+     */
+  expectContain(actualValue, expectedValueToContain, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to contain "${JSON.stringify(expectedValueToContain)}"`);
+    return expect(actualValue, customErrorMsg).to.contain(
+      expectedValueToContain,
+    );
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValueToNotContain
+     * @param {*} [customErrorMsg]
+     */
+  expectNotContain(
+    actualValue,
+    expectedValueToNotContain,
+    customErrorMsg = '',
+  ) {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to not contain "${JSON.stringify(expectedValueToNotContain)}"`);
+    return expect(actualValue, customErrorMsg).not.to.contain(
+      expectedValueToNotContain,
+    );
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValueToStartWith
+     * @param {*} [customErrorMsg]
+     */
+  expectStartsWith(actualValue, expectedValueToStartWith, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to start with "${JSON.stringify(expectedValueToStartWith)}"`);
+    return expect(actualValue, customErrorMsg).to.startsWith(
+      expectedValueToStartWith,
+    );
+  }
+
+  /**
+     *
+     * @param {*} actualValue
+     * @param {*} expectedValueToNotStartWith
+     * @param {*} [customErrorMsg]
+     */
+  expectNotStartsWith(
+    actualValue,
+    expectedValueToNotStartWith,
+    customErrorMsg = '',
+  ) {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to not start with "${JSON.stringify(expectedValueToNotStartWith)}"`);
+    return expect(actualValue, customErrorMsg).not.to.startsWith(
+      expectedValueToNotStartWith,
+    );
+  }
+
+  /**
+     * @param {*} actualValue
+     * @param {*} expectedValueToEndWith
+     * @param {*} [customErrorMsg]
+     */
+  expectEndsWith(actualValue, expectedValueToEndWith, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to end with "${JSON.stringify(expectedValueToEndWith)}"`);
+    return expect(actualValue, customErrorMsg).to.endsWith(
+      expectedValueToEndWith,
+    );
+  }
+
+  /**
+     * @param {*} actualValue
+     * @param {*} expectedValueToNotEndWith
+     * @param {*} [customErrorMsg]
+     */
+  expectNotEndsWith(
+    actualValue,
+    expectedValueToNotEndWith,
+    customErrorMsg = '',
+  ) {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to not end with "${JSON.stringify(expectedValueToNotEndWith)}"`);
+    return expect(actualValue, customErrorMsg).not.to.endsWith(
+      expectedValueToNotEndWith,
+    );
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} jsonSchema
+     * @param {*} [customErrorMsg]
+     */
+  expectJsonSchema(targetData, jsonSchema, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to match this JSON schema "${JSON.stringify(jsonSchema)}"`);
+    chai.use(require('chai-json-schema'));
+    return expect(targetData, customErrorMsg).to.be.jsonSchema(jsonSchema);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} jsonSchema
+     * @param {*} [customErrorMsg]
+     * @param {*} ajvOptions Pass AJV options
+     */
+  expectJsonSchemaUsingAJV(
+    targetData,
+    jsonSchema,
+    customErrorMsg = '',
+    ajvOptions = { allErrors: true },
+  ) {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to match this JSON schema using AJV "${JSON.stringify(jsonSchema)}"`);
+    chai.use(require('chai-json-schema-ajv').create(ajvOptions));
+    return expect(targetData, customErrorMsg).to.be.jsonSchema(jsonSchema);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} propertyName
+     * @param {*} [customErrorMsg]
+     */
+  expectHasProperty(targetData, propertyName, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to have property: "${JSON.stringify(propertyName)}"`);
+    return expect(targetData, customErrorMsg).to.have.property(propertyName);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} propertyName
+     * @param {*} [customErrorMsg]
+     */
+  expectHasAProperty(targetData, propertyName, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to have a property: "${JSON.stringify(propertyName)}"`);
+    return expect(targetData, customErrorMsg).to.have.a.property(propertyName);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} type
+     * @param {*} [customErrorMsg]
+     */
+  expectToBeA(targetData, type, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be a "${JSON.stringify(type)}"`);
+    return expect(targetData, customErrorMsg).to.be.a(type);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} type
+     * @param {*} [customErrorMsg]
+     */
+  expectToBeAn(targetData, type, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be an "${JSON.stringify(type)}"`);
+    return expect(targetData, customErrorMsg).to.be.an(type);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} regex
+     * @param {*} [customErrorMsg]
+     */
+  expectMatchRegex(targetData, regex, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to match the regex "${JSON.stringify(regex)}"`);
+    return expect(targetData, customErrorMsg).to.match(regex);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} length
+     * @param {*} [customErrorMsg]
+     */
+  expectLengthOf(targetData, length, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to have length of "${JSON.stringify(length)}"`);
+    return expect(targetData, customErrorMsg).to.have.lengthOf(length);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} [customErrorMsg]
+     */
+  expectEmpty(targetData, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be empty`);
+    return expect(targetData, customErrorMsg).to.be.empty;
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} [customErrorMsg]
+     */
+  expectTrue(targetData, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be true`);
+    return expect(targetData, customErrorMsg).to.be.true;
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} [customErrorMsg]
+     */
+  expectFalse(targetData, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be false`);
+    return expect(targetData, customErrorMsg).to.be.false;
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} aboveThan
+     * @param {*} [customErrorMsg]
+     */
+  expectAbove(targetData, aboveThan, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be above ${JSON.stringify(aboveThan)}`);
+    return expect(targetData, customErrorMsg).to.be.above(aboveThan);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} belowThan
+     * @param {*} [customErrorMsg]
+     */
+  expectBelow(targetData, belowThan, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to be below ${JSON.stringify(belowThan)}`);
+    return expect(targetData, customErrorMsg).to.be.below(belowThan);
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} lengthAboveThan
+     * @param {*} [customErrorMsg]
+     */
+  expectLengthAboveThan(targetData, lengthAboveThan, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to have length of above ${JSON.stringify(lengthAboveThan)}`);
+    return expect(targetData, customErrorMsg).to.have.lengthOf.above(
+      lengthAboveThan,
+    );
+  }
+
+  /**
+     * @param {*} targetData
+     * @param {*} lengthBelowThan
+     * @param {*} [customErrorMsg]
+     */
+  expectLengthBelowThan(targetData, lengthBelowThan, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(targetData)}" to have length of below ${JSON.stringify(lengthBelowThan)}`);
+    return expect(targetData, customErrorMsg).to.have.lengthOf.below(
+      lengthBelowThan,
+    );
+  }
+
+  /**
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+     */
+  expectEqualIgnoreCase(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect and ingore case "${JSON.stringify(actualValue)}" to equal "${JSON.stringify(expectedValue)}"`);
+    return expect(actualValue, customErrorMsg).to.equalIgnoreCase(
+      expectedValue,
+    );
+  }
+
+  /**
+     * expects members of two arrays are deeply equal
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} [customErrorMsg]
+     */
+  expectDeepMembers(actualValue, expectedValue, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect members of "${JSON.stringify(actualValue)}" and "${JSON.stringify(expectedValue)}" arrays are deeply equal`);
+    return expect(actualValue, customErrorMsg).to.have.deep.members(
+      expectedValue,
+    );
+  }
+
+  /**
+     * expects an array to be a superset of another array
+     * @param {*} superset
+     * @param {*} set
+     * @param {*} [customErrorMsg]
+     */
+  expectDeepIncludeMembers(superset, set, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(superset)}" array to be a superset of "${JSON.stringify(set)}" array`);
+    return expect(superset, customErrorMsg).to.deep.include.members(
+      set,
+    );
+  }
+
+  /**
+     * expects members of two JSON objects are deeply equal excluding some properties
+     * @param {*} actualValue
+     * @param {*} expectedValue
+     * @param {*} fieldsToExclude
+     * @param {*} [customErrorMsg]
+     */
+  expectDeepEqualExcluding(
+    actualValue,
+    expectedValue,
+    fieldsToExclude,
+    customErrorMsg = '',
+  ) {
+    // @ts-ignore
+    output.step(`I expect members of "${JSON.stringify(actualValue)}" and "${JSON.stringify(expectedValue)}" JSON objects are deeply equal excluding properties: ${JSON.stringify(fieldsToExclude)}`);
+    return expect(actualValue, customErrorMsg)
+      .excludingEvery(fieldsToExclude)
+      .to.deep.equal(expectedValue);
+  }
+
+  /**
+     * expects a JSON object matches a provided pattern
+     * @param {*} actualValue
+     * @param {*} expectedPattern
+     * @param {*} [customErrorMsg]
+     */
+  expectMatchesPattern(actualValue, expectedPattern, customErrorMsg = '') {
+    // @ts-ignore
+    output.step(`I expect "${JSON.stringify(actualValue)}" to match the ${JSON.stringify(expectedPattern)} pattern`);
+    return expect(actualValue, customErrorMsg).to.matchPattern(expectedPattern);
+  }
+}
+
+module.exports = ExpectHelper;

package/docs/build/FileSystem.js

@@ -0,0 +1,228 @@
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+
+const Helper = require('@codeceptjs/helper');
+const { fileExists } = require('../utils');
+const { fileIncludes } = require('../assert/include');
+const { fileEquals } = require('../assert/equal');
+
+/**
+ * Helper for testing filesystem.
+ * Can be easily used to check file structures:
+ *
+ * ```js
+ * I.amInPath('test');
+ * I.seeFile('codecept.js');
+ * I.seeInThisFile('FileSystem');
+ * I.dontSeeInThisFile("WebDriver");
+ * ```
+ *
+ * ## Configuration
+ *
+ * Enable helper in config file:
+ *
+ * ```js
+ * helpers: {
+ *     FileSystem: {},
+ * }
+ * ```
+ *
+ * ## Methods
+ */
+class FileSystem extends Helper {
+  constructor() {
+    super();
+    this.dir = global.codecept_dir;
+    this.file = '';
+  }
+
+  _before() {
+    this.debugSection('Dir', this.dir);
+  }
+
+  /**
+   * Enters a directory In local filesystem.
+   * Starts from a current directory
+   * @param {string} openPath
+   */
+  amInPath(openPath) {
+    this.dir = path.join(global.codecept_dir, openPath);
+    this.debugSection('Dir', this.dir);
+  }
+
+  /**
+   * Writes text to file
+   * @param {string} name
+   * @param {string} text
+   */
+  writeToFile(name, text) {
+    fs.writeFileSync(path.join(this.dir, name), text);
+  }
+
+  /**
+   * Checks that file exists
+   * @param {string} name
+   */
+  seeFile(name) {
+    this.file = path.join(this.dir, name);
+    this.debugSection('File', this.file);
+    assert.ok(fileExists(this.file), `File ${name} not found in ${this.dir}`);
+  }
+
+  /**
+   * Waits for the file to be present in the current directory.
+   *
+   * ```js
+   * I.handleDownloads('downloads/largeFilesName.txt');
+   * I.click('Download large File');
+   * I.amInPath('output/downloads');
+   * I.waitForFile('largeFilesName.txt', 10); // wait 10 seconds for file
+   * ```
+   * @param {string} name
+   * @param {number} [sec=1] seconds to wait
+   */
+  async waitForFile(name, sec = 1) {
+    if (sec === 0) assert.fail('Use `seeFile` instead of waiting 0 seconds!');
+    const waitTimeout = sec * 1000;
+    this.file = path.join(this.dir, name);
+    this.debugSection('File', this.file);
+    return isFileExists(this.file, waitTimeout).catch(() => {
+      throw new Error(`file (${name}) still not present in directory ${this.dir} after ${waitTimeout / 1000} sec`);
+    });
+  }
+
+  /**
+  * Checks that file with a name including given text exists in the current directory.
+  *
+  *```js
+  * I.handleDownloads();
+  * I.click('Download as PDF');
+  * I.amInPath('output/downloads');
+  * I.seeFileNameMatching('.pdf');
+  * ```
+  * @param {string} text
+  */
+  seeFileNameMatching(text) {
+    assert.ok(
+      this.grabFileNames().some(file => file.includes(text)),
+      `File name which contains ${text} not found in ${this.dir}`,
+    );
+  }
+
+  /**
+   * Checks that file found by `seeFile` includes a text.
+   * @param {string} text
+   * @param {string} [encoding='utf8']
+   */
+  seeInThisFile(text, encoding = 'utf8') {
+    const content = getFileContents(this.file, encoding);
+    fileIncludes(this.file).assert(text, content);
+  }
+
+  /**
+   * Checks that file found by `seeFile` doesn't include text.
+   * @param {string} text
+   * @param {string} [encoding='utf8']
+   */
+  dontSeeInThisFile(text, encoding = 'utf8') {
+    const content = getFileContents(this.file, encoding);
+    fileIncludes(this.file).negate(text, content);
+  }
+
+  /**
+   * Checks that contents of file found by `seeFile` equal to text.
+   * @param {string} text
+   * @param {string} [encoding='utf8']
+   */
+  seeFileContentsEqual(text, encoding = 'utf8') {
+    const content = getFileContents(this.file, encoding);
+    fileEquals(this.file).assert(text, content);
+  }
+
+  /**
+   * Checks that contents of the file found by `seeFile` equal to contents of the file at `pathToReferenceFile`.
+   * @param {string} pathToReferenceFile
+   * @param {string} [encoding='utf8']
+   * @param {string} [encodingReference='utf8']
+   */
+  seeFileContentsEqualReferenceFile(pathToReferenceFile, encoding = 'utf8', encodingReference = '') {
+    const content = getFileContents(this.file, encoding);
+    assert.ok(fileExists(pathToReferenceFile), `Reference file ${pathToReferenceFile} not found.`);
+    encodingReference = encodingReference || encoding;
+    const expectedContent = getFileContents(pathToReferenceFile, encodingReference);
+    fileEquals(this.file).assert(expectedContent, content);
+  }
+
+  /**
+   * Checks that contents of file found by `seeFile` doesn't equal to text.
+   * @param {string} text
+   * @param {string} [encoding='utf8']
+   */
+  dontSeeFileContentsEqual(text, encoding = 'utf8') {
+    const content = getFileContents(this.file, encoding);
+    fileEquals(this.file).negate(text, content);
+  }
+
+  /**
+  * Returns file names in current directory.
+  *
+  * ```js
+  * I.handleDownloads();
+  * I.click('Download Files');
+  * I.amInPath('output/downloads');
+  * const downloadedFileNames = I.grabFileNames();
+  * ```
+  */
+  grabFileNames() {
+    return fs.readdirSync(this.dir)
+      .filter(item => !fs.lstatSync(path.join(this.dir, item)).isDirectory());
+  }
+}
+
+module.exports = FileSystem;
+
+/**
+ * @param {string} file
+ * @param {string} [encoding='utf8']
+ * @private
+ * @returns {string}
+ */
+function getFileContents(file, encoding = 'utf8') {
+  if (!file) assert.fail('No files were opened, please use seeFile action');
+  if (encoding === '') assert.fail('Encoding is an empty string, please set a valid encoding');
+  return fs.readFileSync(file, encoding);
+}
+
+/**
+ * @param {string} file
+ * @param {number} timeout
+ * @private
+ * @returns {Promise<any>}
+ */
+function isFileExists(file, timeout) {
+  return new Promise(((resolve, reject) => {
+    const timer = setTimeout(() => {
+      watcher.close();
+      reject(new Error('File did not exists and was not created during the timeout.'));
+    }, timeout);
+
+    const dir = path.dirname(file);
+    const basename = path.basename(file);
+    const watcher = fs.watch(dir, (eventType, filename) => {
+      if (eventType === 'rename' && filename === basename) {
+        clearTimeout(timer);
+        watcher.close();
+        resolve();
+      }
+    });
+
+    fs.access(file, fs.constants.R_OK, (err) => {
+      if (!err) {
+        clearTimeout(timer);
+        watcher.close();
+        resolve();
+      }
+    });
+  }));
+}