codeceptjs 4.2.0-beta.3 → 4.2.0

package/lib/helper/Playwright.js

@@ -8,6 +8,7 @@ import Locator from '../locator.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript } from './extras/clipboard.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import { empty } from '../assert/empty.js'
@@ -584,7 +585,8 @@ class Playwright extends Helper {
     // Clear popup state to ensure clean state for each test
     popupStore.clear()
 
-    recorder.retry({
+    // Configure retry for this test; will clean up after test completes
+    this._retryConfig = {
       retries: test?.opts?.conditionalRetries || 3,
       when: err => {
         if (!err || typeof err.message !== 'string') {
@@ -593,7 +595,8 @@ class Playwright extends Helper {
         // ignore context errors
         return err.message.includes('context')
       },
-    })
+    }
+    recorder.retry(this._retryConfig)
 
     // Start browser if needed (initial start or browser restart strategy)
     if (!this.isRunning && !this.options.manualStart) await this._startBrowser()
@@ -698,6 +701,12 @@ class Playwright extends Helper {
   }
 
   async _after() {
+    // Clean up our retry config to prevent accumulation
+    if (this._retryConfig) {
+      recorder.retries = recorder.retries.filter(r => r !== this._retryConfig)
+      this._retryConfig = null
+    }
+
     if (!this.isRunning) return
 
     // Clear popup state to prevent leakage between tests
@@ -2659,6 +2668,49 @@ class Playwright extends Helper {
     return this.browserContext.clearCookies()
   }
 
+  /**
+   * {{> seeInClipboard }}
+   */
+  async seeInClipboard(text) {
+    const clipboard = await this.grabFromClipboard()
+    stringIncludes('clipboard').assert(text, clipboard)
+  }
+
+  /**
+   * {{> seeClipboardEquals }}
+   */
+  async seeClipboardEquals(text) {
+    const clipboard = await this.grabFromClipboard()
+    return equals('clipboard').assert(clipboard, text)
+  }
+
+  /**
+   * {{> grabFromClipboard }}
+   */
+  async grabFromClipboard() {
+    await this._grantClipboardAccess()
+    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS)
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
+  }
+
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    return this.page.evaluate(writeClipboardScript, '')
+  }
+
+  async _grantClipboardAccess() {
+    await this.page.bringToFront().catch(() => {})
+    if (this.options.browser !== 'chromium') return
+    await this.page
+      .context()
+      .grantPermissions(['clipboard-read', 'clipboard-write'])
+      .catch(() => {})
+  }
+
   /**
    * Executes a script on the page:
    *
@@ -3667,8 +3719,7 @@ class Playwright extends Helper {
     }
 
     try {
-      // Always create frame locator from page to avoid nested frame paths
-      this.frame = await Promise.race([this.page.frameLocator(locator), new Promise((_, reject) => setTimeout(() => reject(new Error('Frame locator timeout')), 5000))])
+      this.frame = this.frame ? this.frame.frameLocator(locator) : this.page.frameLocator(locator)
     } catch (e) {
       console.warn('Warning during frame locator creation:', e.message)
       throw new Error(`Frame ${JSON.stringify(locator)} could not be accessed`)

package/lib/helper/Puppeteer.js

@@ -9,6 +9,7 @@ import Locator from '../locator.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript } from './extras/clipboard.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import { empty } from '../assert/empty.js'
@@ -354,7 +355,8 @@ class Puppeteer extends Helper {
   async _before(test) {
     this.sessionPages = {}
     this.currentRunningTest = test
-    recorder.retry({
+    // Configure retry for this test; will clean up after test completes
+    this._retryConfig = {
       retries: test?.opts?.conditionalRetries || 3,
       when: err => {
         if (!err || typeof err.message !== 'string') {
@@ -363,13 +365,20 @@ class Puppeteer extends Helper {
         // ignore context errors
         return err.message.includes('context')
       },
-    })
+    }
+    recorder.retry(this._retryConfig)
     if (this.options.restart && !this.options.manualStart) return this._startBrowser()
     if (!this.isRunning && !this.options.manualStart) return this._startBrowser()
     return this.browser
   }
 
   async _after() {
+    // Clean up our retry config to prevent accumulation
+    if (this._retryConfig) {
+      recorder.retries = recorder.retries.filter(r => r !== this._retryConfig)
+      this._retryConfig = null
+    }
+
     if (!this.isRunning) return
 
     // Clear popup state to prevent leakage between tests
@@ -1960,6 +1969,55 @@ class Puppeteer extends Helper {
     return this.page.deleteCookie(cookie[0])
   }
 
+  /**
+   * {{> seeInClipboard }}
+   */
+  async seeInClipboard(text) {
+    const clipboard = await this.grabFromClipboard()
+    stringIncludes('clipboard').assert(text, clipboard)
+  }
+
+  /**
+   * {{> seeClipboardEquals }}
+   */
+  async seeClipboardEquals(text) {
+    const clipboard = await this.grabFromClipboard()
+    return equals('clipboard').assert(clipboard, text)
+  }
+
+  /**
+   * {{> grabFromClipboard }}
+   */
+  async grabFromClipboard() {
+    await this._grantClipboardAccess()
+    const clipboard = await this.page.evaluate(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS)
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
+  }
+
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    return this.page.evaluate(writeClipboardScript, '')
+  }
+
+  async _grantClipboardAccess() {
+    await this.page.bringToFront().catch(() => {})
+    let origin
+    try {
+      origin = new URL(this.page.url()).origin
+    } catch (err) {
+      return
+    }
+    if (!origin.startsWith('http')) return
+    await this.page
+      .browserContext()
+      .overridePermissions(origin, ['clipboard-read', 'clipboard-write', 'clipboard-sanitized-write'])
+      .catch(() => {})
+  }
+
   /**
    * If a function returns a Promise, tt will wait for its resolution.
    *
@@ -3709,4 +3767,3 @@ async function proceedSelect(context, el, option) {
 
   return this._waitForAction()
 }
-

package/lib/helper/WebDriver.js

@@ -11,6 +11,7 @@ import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import store from '../store.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript, clipboardAsyncScript } from './extras/clipboard.js'
 import output from '../output.js'
 const { debug } = output
 import { empty } from '../assert/empty.js'
@@ -2091,6 +2092,48 @@ class WebDriver extends Helper {
     return cookie[0]
   }
 
+  /**
+   * {{> seeInClipboard }}
+   */
+  async seeInClipboard(text) {
+    const clipboard = await this.grabFromClipboard()
+    return stringIncludes('clipboard').assert(text, clipboard)
+  }
+
+  /**
+   * {{> seeClipboardEquals }}
+   */
+  async seeClipboardEquals(text) {
+    const clipboard = await this.grabFromClipboard()
+    return equals('clipboard').assert(clipboard, text)
+  }
+
+  /**
+   * {{> grabFromClipboard }}
+   */
+  async grabFromClipboard() {
+    await this._grantClipboardAccess()
+    const result = (await this.browser.executeAsync(clipboardAsyncScript(readClipboardScript), CLIPBOARD_READ_TIMEOUT_MS)) || {}
+    if (result.error) throw new Error(`Could not read the clipboard: ${result.error}`)
+    this.debugSection('Clipboard', result.value)
+    return result.value
+  }
+
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    const result = (await this.browser.executeAsync(clipboardAsyncScript(writeClipboardScript), '')) || {}
+    if (result.error) throw new Error(`Could not write to the clipboard: ${result.error}`)
+  }
+
+  async _grantClipboardAccess() {
+    if (typeof this.browser.setPermissions !== 'function') return
+    await this.browser.setPermissions({ name: 'clipboard-read' }, 'granted').catch(() => {})
+    await this.browser.setPermissions({ name: 'clipboard-write' }, 'granted').catch(() => {})
+  }
+
   /**
    * {{> waitForCookie }}
    */

package/lib/helper/extras/clipboard.js

@@ -0,0 +1,31 @@
+export const CLIPBOARD_READ_TIMEOUT_MS = 5000
+
+export function readClipboardScript(timeout) {
+  if (!navigator.clipboard || !navigator.clipboard.readText) {
+    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
+  }
+  return Promise.race([navigator.clipboard.readText(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('timed out while reading the clipboard')), timeout))])
+}
+
+export function writeClipboardScript(text) {
+  if (!navigator.clipboard || !navigator.clipboard.writeText) {
+    throw new Error('Clipboard API is not available on this page, it requires a secure context (https or localhost)')
+  }
+  return navigator.clipboard.writeText(text)
+}
+
+export function clipboardExpression(script, arg) {
+  return `(${script.toString()})(${JSON.stringify(arg)})`
+}
+
+export function clipboardAsyncScript(script) {
+  return `
+    var done = arguments[arguments.length - 1]
+    var fail = function (err) { done({ error: (err && err.message) || String(err) }) }
+    try {
+      (${script.toString()})(arguments[0]).then(function (value) { done({ value: value }) }, fail)
+    } catch (err) {
+      fail(err)
+    }
+  `
+}

package/lib/plugin/retryFailedStep.js

@@ -98,7 +98,6 @@ export default function (config) {
 
   const when = err => {
     if (!enableRetry) return
-    if (store.debugMode) return false
     if (!store.autoRetries) return false
     if (err && err.isTerminal) return false
     if (err && err.message && (err.message.includes('ERR_ABORTED') || err.message.includes('frame was detached') || err.message.includes('Target page, context or browser has been closed'))) return false
@@ -152,7 +151,9 @@ export default function (config) {
     test.opts.stepRetryPriority = stepRetryPriority
 
     debug('applying retries = %d for test %s', config.retries, test.title)
-    recorder.retry(config)
+    if (!recorder.retries.find(r => r === config)) {
+      recorder.retry(config)
+    }
   })
 
   event.dispatcher.on(event.test.started, test => {
@@ -171,4 +172,8 @@ export default function (config) {
       test.opts.conditionalRetries = test.opts.conditionalRetries || config.retries
     }
   })
+
+  event.dispatcher.on(event.test.after, () => {
+    recorder.retries = recorder.retries.filter(r => r !== config)
+  })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.2.0-beta.3",
+  "version": "4.2.0",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -207,7 +207,7 @@
     }
   },
   "engines": {
-    "node": ">=16.0",
+    "node": ">=22.12.0",
     "npm": ">=5.6.0"
   },
   "es6": true,

package/typings/promiseBasedTypes.d.ts

@@ -770,6 +770,32 @@ declare namespace CodeceptJS {
          * @returns Appium: support both Android and iOS
          */
         closeApp(): Promise<void>;
+        /**
+         * Clears the system clipboard.
+         *
+         * ```js
+         * I.clearClipboard();
+         * I.seeClipboardEquals('');
+         * ```
+         */
+        clearClipboard(): Promise<any>;
+        /**
+         * Grabs the text content of the system clipboard and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * let url = await I.grabFromClipboard();
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @returns the system clipboard contents.
+         *
+         *
+         * Appium: support both Android and iOS
+         */
+        grabFromClipboard(): Promise<string>;
         /**
          * Appends text to a input field or textarea.
          * Field is located by name, label, CSS or XPath
@@ -2166,6 +2192,56 @@ declare namespace CodeceptJS {
          * @param [name = null] - (optional, `null` by default) cookie name
          */
         clearCookie(name?: string | null): Promise<void>;
+        /**
+         * Checks that the system clipboard contains the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeInClipboard('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`).
+         * @param text - value to check.
+         */
+        seeInClipboard(text: string): Promise<void>;
+        /**
+         * Checks that the system clipboard is equal to the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeClipboardEquals('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`).
+         * @param text - value to check.
+         */
+        seeClipboardEquals(text: string): Promise<void>;
+        /**
+         * Clears the system clipboard.
+         *
+         * ```js
+         * I.clearClipboard();
+         * I.seeClipboardEquals('');
+         * ```
+         */
+        clearClipboard(): Promise<void>;
+        /**
+         * Grabs the text content of the system clipboard.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * const url = await I.grabFromClipboard();
+         * ```
+         * @returns the system clipboard contents.
+         */
+        grabFromClipboard(): Promise<string>;
+        /**
+         * Brings the current target to front and grants it clipboard read/write access, so
+         * `navigator.clipboard` does not reject with a permission or focus error. Failures are ignored:
+         * a browser without `Browser.grantPermissions` surfaces its own error from the read instead.
+         */
+        protected _grantClipboardAccess(): Promise<any>;
         /**
          * Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
          * Filename is relative to the output folder.
@@ -3423,6 +3499,17 @@ declare namespace CodeceptJS {
      * elements works, it only pins the config presets Obscura requires and manages the `obscura serve`
      * process lifecycle, the same way Playwright manages its own browser process.
      *
+     * > Obscura support is experimental in CodeceptJS 4.2. Pin the browser version in CI and keep a
+     * > Playwright/WebDriver job for browser-compatibility coverage.
+     *
+     * ## Compatibility
+     *
+     * | CodeceptJS | Recommended Obscura | Notes |
+     * | --- | --- | --- |
+     * | 4.2.x | 0.2.2 | Version used by the CodeceptJS Obscura CI workflow |
+     * | 4.2.x | 0.2.x | Supported; capabilities are detected at runtime |
+     * | 4.2.x | 0.1.x / `-no-render` | DOM-only mode; no layout, visibility assertions, or screenshots |
+     *
      * ## Modes
      *
      * - **ATTACH** — `endpoint` is set explicitly in the config. The helper only connects to it; it
@@ -3440,8 +3527,20 @@ declare namespace CodeceptJS {
      *
      * ## Install
      *
-     * Download a release binary and put it on your `PATH` (or point `binaryPath`/`OBSCURA_PATH` at
-     * it directly) and the helper launches and tears it down for you automatically:
+     * Download a release archive from [Obscura releases](https://github.com/h4ckf0r0day/obscura/releases).
+     * CodeceptJS 4.2 is tested with Obscura 0.2.2. Rendering archives are available for:
+     *
+     * | platform | archive |
+     * | --- | --- |
+     * | Linux x64 | `obscura-x86_64-linux.tar.gz` |
+     * | Linux ARM64 | `obscura-aarch64-linux.tar.gz` |
+     * | macOS Intel | `obscura-x86_64-macos.tar.gz` |
+     * | macOS Apple Silicon | `obscura-aarch64-macos.tar.gz` |
+     * | Windows x64 | `obscura-x86_64-windows.zip` |
+     *
+     * Extract the archive and put `obscura` (`obscura.exe` on Windows) on your `PATH`, or point
+     * `binaryPath`/`OBSCURA_PATH` at it. The helper then launches and tears it down automatically.
+     * For example, on Linux x64:
      *
      * ```sh
      * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
@@ -5084,6 +5183,55 @@ declare namespace CodeceptJS {
          * @param [cookie = null] - (optional, `null` by default) cookie name
          */
         clearCookie(cookie?: string): Promise<any>;
+        /**
+         * Checks that the system clipboard contains the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeInClipboard('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeInClipboard(text: string): Promise<any>;
+        /**
+         * Checks that the system clipboard is equal to the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeClipboardEquals('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeClipboardEquals(text: string): Promise<any>;
+        /**
+         * Grabs the text content of the system clipboard and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * let url = await I.grabFromClipboard();
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @returns the system clipboard contents.
+         */
+        grabFromClipboard(): Promise<string>;
+        /**
+         * Clears the system clipboard.
+         *
+         * ```js
+         * I.clearClipboard();
+         * I.seeClipboardEquals('');
+         * ```
+         */
+        clearClipboard(): Promise<any>;
         /**
          * Executes a script on the page:
          *
@@ -7165,6 +7313,55 @@ declare namespace CodeceptJS {
          * @param [cookie = null] - (optional, `null` by default) cookie name
          */
         clearCookie(cookie?: string): Promise<any>;
+        /**
+         * Checks that the system clipboard contains the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeInClipboard('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeInClipboard(text: string): Promise<any>;
+        /**
+         * Checks that the system clipboard is equal to the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeClipboardEquals('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeClipboardEquals(text: string): Promise<any>;
+        /**
+         * Grabs the text content of the system clipboard and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * let url = await I.grabFromClipboard();
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @returns the system clipboard contents.
+         */
+        grabFromClipboard(): Promise<string>;
+        /**
+         * Clears the system clipboard.
+         *
+         * ```js
+         * I.clearClipboard();
+         * I.seeClipboardEquals('');
+         * ```
+         */
+        clearClipboard(): Promise<any>;
         /**
          * If a function returns a Promise, tt will wait for its resolution.
          *
@@ -9482,6 +9679,55 @@ declare namespace CodeceptJS {
          * @param [name = null] - cookie name.
          */
         grabCookie(name?: string): Promise<any>;
+        /**
+         * Checks that the system clipboard contains the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeInClipboard('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeInClipboard(text: string): Promise<any>;
+        /**
+         * Checks that the system clipboard is equal to the given text.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * I.seeClipboardEquals('https://codecept.io');
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @param text - value to check.
+         */
+        seeClipboardEquals(text: string): Promise<any>;
+        /**
+         * Grabs the text content of the system clipboard and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * I.click('Copy to clipboard');
+         * let url = await I.grabFromClipboard();
+         * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
+         * @returns the system clipboard contents.
+         */
+        grabFromClipboard(): Promise<string>;
+        /**
+         * Clears the system clipboard.
+         *
+         * ```js
+         * I.clearClipboard();
+         * I.seeClipboardEquals('');
+         * ```
+         */
+        clearClipboard(): Promise<any>;
         /**
          * Waits for the specified cookie in the cookies.
          *