codeceptjs 3.5.7-beta.1 → 3.5.8

package/README.md

@@ -7,10 +7,14 @@
 
 Build Status:
 
+Appium Helper:
+[![Appium V2 Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_Android.yml)
+[![Appium V2 Tests - iOS](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_iOS.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_iOS.yml)
+
+Web Helper:
 [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)
 [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)
 [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)
-[![Appium Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml)
 [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)
 
 # CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)

package/docs/advanced.md

@@ -150,7 +150,7 @@ For **Visual Studio Code**, add the following configuration in launch.json:
   "request": "launch",
   "name": "codeceptjs",
   "args": ["run", "--grep", "@your_test_tag"],
-  "program": "${workspaceFolder}/node_modules/.bin/codeceptjs"
+  "program": "${workspaceFolder}/node_modules/codeceptjs/bin/codecept.js"
 }
 ```
 

package/docs/build/Appium.js

@@ -183,6 +183,11 @@ class Appium extends Webdriver {
     this.axios = axios.create();
 
     webdriverio = require('webdriverio');
+    if (!config.appiumV2) {
+      console.log('The Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. Please migrating to Appium 2.x by adding appiumV2: true to your config.');
+      console.log('More info: https://bit.ly/appium-v2-migration');
+      console.log('This Appium 1.x support will be removed in next major release.');
+    }
   }
 
   _validateConfig(config) {
@@ -916,11 +921,12 @@ class Appium extends Webdriver {
    * I.setNetworkConnection(4) // airplane mode off, wifi off, data on
    * I.setNetworkConnection(6) // airplane mode off, wifi on, data on
    * ```
-   * See corresponding [webdriverio reference](http://webdriver.io/api/mobile/setNetworkConnection.html).
-   *
-   * @return {Promise<{}>}
+   * See corresponding [webdriverio reference](https://webdriver.io/docs/api/chromium/#setnetworkconnection).
    *
    * Appium: support only Android
+   *
+   * @param {number} value The network connection mode bitmask
+   * @return {Promise<number>}
    */
   async setNetworkConnection(value) {
     onlyForApps.call(this, supportedPlatform.android);

package/docs/build/Playwright.js

@@ -116,6 +116,10 @@ const config = {};
  * npm i playwright-core@^1.18 --save
  * ```
  *
+ * Breaking Changes: if you use Playwright v1.38 and later, it will no longer download browsers automatically.
+ *
+ * Run `npx playwright install` to download browsers after `npm install`.
+ *
  * 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.
  *
  *
@@ -1061,6 +1065,38 @@ class Playwright extends Helper {
     await el.blur(options);
     return this._waitForAction();
   }
+  /**
+   * Return the checked status of given element.
+   *
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {object} [options] See https://playwright.dev/docs/api/class-locator#locator-is-checked
+   * @return {Promise<boolean>}
+   *
+   */
+
+  async grabCheckedElementStatus(locator, options = {}) {
+    const supportedTypes = ['checkbox', 'radio'];
+    const el = await this._locateElement(locator);
+    const type = await el.getAttribute('type');
+
+    if (supportedTypes.includes(type)) {
+      return el.isChecked(options);
+    }
+    throw new Error(`Element is not a ${supportedTypes.join(' or ')} input`);
+  }
+  /**
+   * Return the disabled status of given element.
+   *
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {object} [options] See https://playwright.dev/docs/api/class-locator#locator-is-disabled
+   * @return {Promise<boolean>}
+   *
+   */
+
+  async grabDisabledElementStatus(locator, options = {}) {
+    const el = await this._locateElement(locator);
+    return el.isDisabled(options);
+  }
 
   /**
    * Drag an item to a destination element.
@@ -3486,6 +3522,7 @@ class Playwright extends Helper {
       let count = 0;
       do {
         waiter = await _contextObject.locator(`:has-text('${text}')`).first().isVisible();
+        if (waiter) break;
         await this.wait(1);
         count += 1000;
       } while (count <= waitTimeout);

package/docs/build/Puppeteer.js

@@ -4,6 +4,7 @@ const fsExtra = require('fs-extra');
 const path = require('path');
 
 const Helper = require('@codeceptjs/helper');
+const { v4: uuidv4 } = require('uuid');
 const Locator = require('../locator');
 const recorder = require('../recorder');
 const store = require('../store');
@@ -19,6 +20,7 @@ const {
   fileExists,
   chunkArray,
   toCamelCase,
+  clearString,
   convertCssPropertiesToCamelCase,
   screenshotOutputFolder,
   getNormalizedKeyAttributeValue,
@@ -57,6 +59,8 @@ const consoleLogStore = new Console();
  * @prop {boolean} [disableScreenshots=false]  - don't save screenshot on failure.
  * @prop {boolean} [fullPageScreenshots=false] - make full page screenshots on failure.
  * @prop {boolean} [uniqueScreenshotNames=false]  - option to prevent screenshot override if you have scenarios with the same name in different suites.
+ * @prop {boolean} [trace=false] - record [tracing information](https://pptr.dev/api/puppeteer.tracing) with screenshots.
+ * @prop {boolean} [keepTraceForPassedTests=false] - save trace for passed tests.
  * @prop {boolean} [keepBrowserState=false] - keep browser state between tests when `restart` is set to false.
  * @prop {boolean} [keepCookies=false] - keep cookies between tests when `restart` is set to false.
  * @prop {number} [waitForAction=100] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
@@ -92,6 +96,14 @@ const config = {};
  *
  * <!-- configuration -->
  *
+ * #### Trace Recording Customization
+ *
+ * Trace recording provides complete information on test execution and includes screenshots, and network requests logged during run.
+ * Traces will be saved to `output/trace`
+ *
+ * * `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder
+ * * `keepTraceForPassedTests`: - save trace for passed tests
+ *
  * #### Example #1: Wait for 0 network connections.
  *
  * ```js
@@ -281,8 +293,9 @@ class Puppeteer extends Helper {
     }
   }
 
-  async _before() {
+  async _before(test) {
     this.sessionPages = {};
+    this.currentRunningTest = test;
     recorder.retry({
       retries: 3,
       when: err => {
@@ -666,6 +679,14 @@ class Puppeteer extends Helper {
       }
     }
 
+    if (this.options.trace) {
+      const fileName = `${`${global.output_dir}${path.sep}trace${path.sep}${uuidv4()}_${clearString(this.currentRunningTest.title)}`.slice(0, 245)}.json`;
+      const dir = path.dirname(fileName);
+      if (!fileExists(dir)) fs.mkdirSync(dir);
+      await this.page.tracing.start({ screenshots: true, path: fileName });
+      this.currentRunningTest.artifacts.trace = fileName;
+    }
+
     await this.page.goto(url, { waitUntil: this.options.waitForNavigation });
 
     const performanceTiming = JSON.parse(await this.page.evaluate(() => JSON.stringify(window.performance.timing)));
@@ -2787,8 +2808,30 @@ class Puppeteer extends Helper {
     }
   }
 
-  async _failed() {
+  async _failed(test) {
+    await this._withinEnd();
+
+    if (this.options.trace) {
+      await this.page.tracing.stop();
+      const _traceName = this.currentRunningTest.artifacts.trace.replace('.json', '.failed.json');
+      fs.renameSync(this.currentRunningTest.artifacts.trace, _traceName);
+      test.artifacts.trace = _traceName;
+    }
+  }
+
+  async _passed(test) {
     await this._withinEnd();
+
+    if (this.options.trace) {
+      await this.page.tracing.stop();
+      if (this.options.keepTraceForPassedTests) {
+        const _traceName = this.currentRunningTest.artifacts.trace.replace('.json', '.passed.json');
+        fs.renameSync(this.currentRunningTest.artifacts.trace, _traceName);
+        test.artifacts.trace = _traceName;
+      } else {
+        fs.unlinkSync(this.currentRunningTest.artifacts.trace);
+      }
+    }
   }
 
   /**

package/docs/changelog.md

@@ -7,6 +7,189 @@ layout: Section
 
 # Releases
 
+## 3.5.8
+
+Thanks all to those who contributed to make this release!
+
+🐛 *Bug Fixes*
+fix(appium): type of setNetworkConnection() ([#3994](https://github.com/codeceptjs/CodeceptJS/issues/3994)) - by **[mirao](https://github.com/mirao)**
+fix: improve the way to show deprecated appium v1 message ([#3992](https://github.com/codeceptjs/CodeceptJS/issues/3992)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+fix: missing exit condition of some wait functions - by **[kobenguyent](https://github.com/kobenguyent)**
+
+## 3.5.7
+
+Thanks all to those who contributed to make this release!
+
+🐛 *Bug Fixes*
+* Bump playwright to 1.39.0 - run `npx playwright install` to install the browsers as starting from 1.39.0 browsers are not installed automatically ([#3924](https://github.com/codeceptjs/CodeceptJS/issues/3924)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix(playwright): some wait functions draw error due to switchTo iframe ([#3918](https://github.com/codeceptjs/CodeceptJS/issues/3918)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix(appium): AppiumTestDistribution/appium-device-farm requires 'platformName' ([#3950](https://github.com/codeceptjs/CodeceptJS/issues/3950)) - by **[rock-tran](https://github.com/rock-tran)**
+* fix: autologin with empty fetch ([#3947](https://github.com/codeceptjs/CodeceptJS/issues/3947)) - by **[andonary](https://github.com/andonary)**
+* fix(cli): customLocator draws error in dry-mode ([#3940](https://github.com/codeceptjs/CodeceptJS/issues/3940)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix: ensure docs include **[returns](https://github.com/returns)** Promise<void> where appropriate ([#3954](https://github.com/codeceptjs/CodeceptJS/issues/3954)) - by **[fwouts](https://github.com/fwouts)**
+* fix: long text in data table cuts off ([#3936](https://github.com/codeceptjs/CodeceptJS/issues/3936)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+#language: de
+Funktionalität: Faker examples
+
+   Szenariogrundriss: Atualizar senha do usuário
+        Angenommen que estou logado via REST com o usuário "<customer>"
+          | protocol             | https:               |
+          | hostname             | https://cucumber.io/docs/gherkin/languages/            |
+          
+
+Faker examples --
+  Atualizar senha do usuário {"product":"{{vehicle.vehicle}}","customer":"Dr. {{name.findName}}","price":"{{commerce.price}}","cashier":"cashier 2"}
+   On Angenommen: que estou logado via rest com o usuário "dr. {{name.find name}}" 
+    protocol        | https:         
+    hostname        | https://cucumber.io/docs/gherkin/languages/
+    
+Dr. {{name.findName}}
+  ✔ OK in 13ms
+
+```
+* fix(playwright): move to waitFor ([#3933](https://github.com/codeceptjs/CodeceptJS/issues/3933)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix: relax grabCookie type ([#3919](https://github.com/codeceptjs/CodeceptJS/issues/3919)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix: proceedSee error when being called inside within ([#3939](https://github.com/codeceptjs/CodeceptJS/issues/3939)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* fix: rename haveRequestHeaders of ppt and pw helpers ([#3937](https://github.com/codeceptjs/CodeceptJS/issues/3937)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+Renamed haveRequestHeaders of Puppeteer, Playwright helper so that it would not confuse the REST helper.
+Puppeteer: setPuppeteerRequestHeaders
+Playwright: setPlaywrightRequestHeaders
+```
+* improvement: handle the way to load apifactory nicely ([#3941](https://github.com/codeceptjs/CodeceptJS/issues/3941)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+With this fix, we could now use the following syntax:
+
+export = new Factory()
+   .attr('name', () => faker.name.findName())
+   .attr('job', () => 'leader');
+   
+export default new Factory()
+   .attr('name', () => faker.name.findName())
+   .attr('job', () => 'leader');
+   
+modules.export = new Factory()
+   .attr('name', () => faker.name.findName())
+   .attr('job', () => 'leader');
+```
+
+📖 *Documentation*
+* docs(appium): update to v2 ([#3932](https://github.com/codeceptjs/CodeceptJS/issues/3932)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* docs: improve BDD Gherkin docs ([#3938](https://github.com/codeceptjs/CodeceptJS/issues/3938)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+* Other docs improvements
+
+🛩️ *Features*
+* feat(puppeteer): support trace recording - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+[Trace Recording Customization]
+Trace recording provides complete information on test execution and includes screenshots, and network requests logged during run. Traces will be saved to output/trace
+
+trace: enables trace recording for failed tests; trace are saved into output/trace folder
+keepTraceForPassedTests: - save trace for passed tests
+```
+* feat: expect helper ([#3923](https://github.com/codeceptjs/CodeceptJS/issues/3923)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+ * 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: {...},
+ *     ExpectHelper: {},
+ *   }
+ 
+  Expect Helper
+    #expectEqual
+    #expectNotEqual
+    #expectContain
+    #expectNotContain
+    #expectStartsWith
+    #expectNotStartsWith
+    #expectEndsWith
+    #expectNotEndsWith
+    #expectJsonSchema
+    #expectHasProperty
+    #expectHasAProperty
+    #expectToBeA
+    #expectToBeAn
+    #expectMatchRegex
+    #expectLengthOf
+    #expectTrue
+    #expectEmpty
+    #expectFalse
+    #expectAbove
+    #expectBelow
+    #expectLengthAboveThan
+    #expectLengthBelowThan
+    #expectLengthBelowThan
+    #expectDeepMembers
+    #expectDeepIncludeMembers
+    #expectDeepEqualExcluding
+    #expectLengthBelowThan
+```
+* feat: run-workers with multiple browsers output folders - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+- ![Screenshot 2023-11-04 at 10 49 56](https://github.com/codeceptjs/CodeceptJS/assets/7845001/8eaecc54-de14-4597-b148-1e087bec3c76)
+- ![Screenshot 2023-11-03 at 15 56 38](https://github.com/codeceptjs/CodeceptJS/assets/7845001/715aed17-3535-48df-80dd-84f7024f08e3)
+* feat: introduce new Playwright methods - by **[hatufacci](https://github.com/hatufacci)**
+```
+- grabCheckedElementStatus
+- grabDisabledElementStatus
+```
+* feat: gherkin supports i18n ([#3934](https://github.com/codeceptjs/CodeceptJS/issues/3934)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+#language: de
+Funktionalität: Checkout-Prozess
+  Um Produkte zu kaufen
+  Als Kunde
+  Möchte ich in der Lage sein, mehrere Produkte zu kaufen
+
+  **[i18n](https://github.com/i18n)**
+  Szenariogrundriss: Bestellrabatt
+    Angenommen ich habe ein Produkt mit einem Preis von <price>$ in meinem Warenkorb
+    Und der Rabatt für Bestellungen über $20 beträgt 10 %
+    Wenn ich zur Kasse gehe
+    Dann sollte ich den Gesamtpreis von "<total>" $ sehen
+
+    Beispiele:
+      | price | total |
+      | 10    | 10.0  |
+```
+* feat(autoLogin): improve the check method ([#3935](https://github.com/codeceptjs/CodeceptJS/issues/3935)) - by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+```
+Instead of asserting on page elements for the current user in check, you can use the session you saved in fetch
+
+autoLogin: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'login',
+  users: {
+    admin: {
+      login: async (I) => {  // If you use async function in the autoLogin plugin
+         const phrase = await I.grabTextFrom('#phrase')
+         I.fillField('username', 'admin'),
+         I.fillField('password', 'password')
+         I.fillField('phrase', phrase)
+      },
+      check: (I, session) => {
+         // Throwing an error in `check` will make CodeceptJS perform the login step for the user
+         if (session.profile.email !== the.email.you.expect@some-mail.com) {
+              throw new Error ('Wrong user signed in');
+        }
+      },
+    }
+  }
+}
+Scenario('login', async ( {I, login} ) => {
+  await login('admin') // you should use `await`
+})
+```
+
 ## 3.5.6
 
 Thanks all to those who contributed to make this release!