codeceptjs 4.2.0-beta.3 → 4.2.0

package/README.md

@@ -10,6 +10,7 @@
 | 🌐 Web    | Playwright | [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)               |
 | 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                  |
 | 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                  |
+| 🌐 Web    | Obscura    | [![Obscura Helper Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/obscura.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/obscura.yml)               |
 | 📱 Mobile | Appium     | [![Appium Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml) |
 
 # CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
@@ -42,6 +43,7 @@ CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently,
 - [**Playwright**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Playwright.md) - is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.
 - [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.
 - [**WebDriver**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) - uses [webdriverio](http://webdriver.io/) to run tests via WebDriver or Devtools protocol.
+- [**Obscura**](https://codecept.io/helpers/Obscura) - drives the lightweight Obscura browser through Chrome DevTools Protocol. See [Alternative Browser Engines](https://codecept.io/alternative-browsers).
 - [**Appium**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Appium.md) - for **mobile testing** with Appium
 - [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.
 
@@ -102,7 +104,7 @@ Later you can even automagically update Type Definitions to include your own cus
 
 Note:
 
-- CodeceptJS requires Node.js version `12+` or later.
+- CodeceptJS 4.2 requires Node.js `22.12.0` or later.
 
 ## Usage
 

package/docs/alternative-browsers.md

@@ -5,6 +5,10 @@ title: Alternative Browser Engines
 
 # Alternative Browser Engines
 
+::: warning Experimental
+The `CDPBrowser`, `Obscura`, and `Kitesurf` helpers are experimental in CodeceptJS 4.2. Pin browser versions in CI and retain Playwright or WebDriver coverage for compatibility-critical tests.
+:::
+
 Playwright and Puppeteer drive full Chromium — the most accurate way to test what users see.
 But a new class of lightweight, agent-era browsers has appeared, and CodeceptJS can drive them
 through the `CDPBrowser` helper family:
@@ -12,8 +16,7 @@ through the `CDPBrowser` helper family:
 - **[Obscura](https://github.com/h4ckf0r0day/obscura)** — an open-source Rust browser with a real
   V8 engine. From v0.2.0, the default release build also renders — real layout, computed styles,
   and screenshots — with `-no-render` builds still available for pure-speed, nothing-painted
-  scraping mode. A single 70 MB binary, ~30 MB RAM per instance, page loads in tens of
-  milliseconds.
+  scraping mode. Release archives are available for Linux, macOS, and Windows.
 - **[Kitesurf](https://blog.cloudflare.com/kitesurf/)** — Cloudflare's browser that runs in V8
   isolates on Cloudflare Workers, with a real layout and rendering pipeline. Cloud-only,
   free in beta, planned to be open-sourced.
@@ -24,10 +27,9 @@ on navigation races.
 
 ## When are they better than Playwright?
 
-**Smoke suites where seconds matter.** An Obscura scenario (navigate, fill a form, submit,
-assert) completes in 150–500 ms. There is no browser binary to download in CI — a 70 MB
-static binary starts instantly. If your PR gate runs 50 smoke scenarios, Obscura turns
-minutes into seconds.
+**Smoke suites where startup and execution time matter.** Obscura is distributed as a standalone
+binary and is designed for lightweight browser automation. Benchmark it against your own pages and
+CI environment before choosing it for a PR gate.
 
 **Massive parallel scale.** Kitesurf sessions are Cloudflare Workers — they spawn in about a
 second, cost nothing while idle, and there is no practical ceiling on how many you run at once.
@@ -57,9 +59,8 @@ app's real JavaScript in real V8; it only skips painting. For API-adjacent flows
 **Constrained environments.** ARM CI runners, thin containers, air-gapped machines:
 a static binary with no system dependencies goes where Chromium will not.
 
-**Scraping-grade network realism.** Obscura's stealth mode presents a consistent Chrome TLS
-fingerprint — useful when your tests must pass through bot-protection layers that block
-headless Chromium.
+**Optional stealth builds.** Obscura publishes separate `-stealth` archives. Treat their behaviour
+as an Obscura capability rather than a browser-compatibility guarantee from CodeceptJS.
 
 ## When to stay with Playwright
 
@@ -77,6 +78,10 @@ headless Chromium.
 
 ## Configuration
 
+CodeceptJS 4.2 is tested in CI with Obscura 0.2.2. Obscura 0.2.x is recommended; 0.1.x and
+`-no-render` builds operate without layout, visibility assertions, or screenshots. See
+[Installation](/installation#obscura-experimental) for platform-specific archive names.
+
     helpers: {
       Obscura: {
         url: 'http://localhost:3000',
@@ -144,7 +149,7 @@ process — there is nothing to start by hand in the common case:
 | Screenshots | yes | yes (v0.2.0+ default builds); no on `-no-render`/v0.1.x | yes |
 | Visibility assertions | yes | yes (v0.2.0+ default builds); no, DOM-presence only, on `-no-render`/v0.1.x | yes |
 | Screencast / video (`screencast` plugin) | yes — WebM via `page.screencast`, with caption burn-in | yes — APNG via CDP `Page.startScreencast`, assembled in-process (v0.2.0+ default builds; verified PNG frames on the live server); no caption burn-in | untested |
-| Startup cost | seconds + ~300 MB install | instant, 70 MB binary | ~1 s, zero local |
+| Startup model | local browser process | standalone local binary | remote cloud session |
 | Parallel scale | machine-bound | machine-bound (light) | near-unlimited (cloud) |
 | Where it runs | local/grid | local | Cloudflare only |
 | License / cost | open source | Apache-2.0 | proprietary, free beta |

package/docs/continuous-integration.md

@@ -9,7 +9,7 @@ CodeceptJS runs in any CI that can install Node.js. This page covers the setup,
 
 ## Setup
 
-- **Node.js** — install it on the runner (`actions/setup-node`, the `node:20` image, `NodeTool@0` on Azure). Examples below use Node 20.
+- **Node.js 22.12 or newer** — install it on the runner (`actions/setup-node`, the `node:22` image, `NodeTool@0` on Azure). Examples below use Node 22.
 - **Headless** — `codecept.conf.js` must contain `setHeadlessWhen(process.env.HEADLESS || process.env.CI)`. `codeceptjs init` adds it; since CI sets `CI=true`, the suite runs headless automatically.
 
   ```js
@@ -61,7 +61,7 @@ Use [`@testomatio/reporter`](https://github.com/testomatio/reporter). It ships p
 
 ## CI examples
 
-Each example uses Playwright by default; a WebDriver variant follows where it differs. WebdriverIO 9 downloads its own browser and driver, so the WebDriver variants run on a plain `node:20` image with no Selenium service and no browser-install step. For Playwright, a `node:20` base image plus `npx playwright install --with-deps` keeps these configs free of version pins.
+Each example uses Playwright by default; a WebDriver variant follows where it differs. WebdriverIO 9 downloads its own browser and driver, so the WebDriver variants run on a plain `node:22` image with no Selenium service and no browser-install step. For Playwright, a `node:22` base image plus `npx playwright install --with-deps` keeps these configs free of version pins.
 
 ### GitHub Actions — Playwright
 
@@ -85,7 +85,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
       - run: npm ci
       - run: npx playwright install --with-deps chromium
@@ -115,7 +115,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm ci
       - run: npx codeceptjs check
       - run: npx codeceptjs run-workers 2 --by pool
@@ -142,7 +142,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm ci
       - run: npx playwright install --with-deps chromium
       - run: npx codeceptjs check
@@ -173,7 +173,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm ci
       - run: npx playwright install --with-deps
       - run: npx codeceptjs check
@@ -194,7 +194,7 @@ stages: [test]
 
 playwright:
   stage: test
-  image: node:20
+  image: node:22
   variables:
     FORCE_COLOR: "1"
   parallel: 4
@@ -211,7 +211,7 @@ playwright:
 
 webdriver:
   stage: test
-  image: node:20  # WebdriverIO 9 downloads its own browser and driver
+  image: node:22  # WebdriverIO 9 downloads its own browser and driver
   script:
     - npm ci
     - npx codeceptjs check
@@ -228,7 +228,7 @@ webdriver:
 `bitbucket-pipelines.yml`:
 
 ```yaml
-image: node:20
+image: node:22
 
 definitions:
   caches:
@@ -260,7 +260,7 @@ pipelines:
 For WebDriver, no Selenium service or browser image is needed — WebdriverIO 9 downloads its own browser and driver:
 
 ```yaml
-image: node:20
+image: node:22
 
 pipelines:
   default:
@@ -280,7 +280,7 @@ pipelines:
 pipeline {
   agent {
     docker {
-      image 'node:20'
+      image 'node:22'
       args '-u root'
     }
   }
@@ -311,7 +311,7 @@ pipeline {
 }
 ```
 
-For WebDriver, keep the same `node:20` agent — WebdriverIO 9 downloads its own browser and driver, so no Selenium container is needed:
+For WebDriver, keep the same `node:22` agent — WebdriverIO 9 downloads its own browser and driver, so no Selenium container is needed:
 
 ```groovy
 stage('Test') {
@@ -332,7 +332,7 @@ version: 2.1
 jobs:
   test:
     docker:
-      - image: cimg/node:20.18-browsers
+      - image: cimg/node:22.14-browsers
     parallelism: 4
     steps:
       - checkout
@@ -350,7 +350,7 @@ jobs:
   webdriver:
     docker:
       # WebdriverIO 9 downloads its own browser and driver
-      - image: cimg/node:20.18
+      - image: cimg/node:22.14
     steps:
       - checkout
       - run: npm ci

package/docs/helpers/Obscura.md

@@ -22,6 +22,17 @@ This helper is a thin `CDPBrowser` subclass: it changes nothing about how locati
 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
@@ -39,8 +50,20 @@ process lifecycle, the same way Playwright manages its own browser process.
 
 ## 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][2].
+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
@@ -84,19 +107,19 @@ Set them explicitly in your own config to skip probing or to force a mode.
 This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
 accepts (see its config table), plus:
 
-Type: [object][6]
+Type: [object][7]
 
 ### Properties
 
-*   `endpoint` **[string][4]?** explicit CDP endpoint. Setting this switches the helper to ATTACH
+*   `endpoint` **[string][5]?** explicit CDP endpoint. Setting this switches the helper to ATTACH
     mode: it only connects, and never spawns or kills a process, no matter what else is configured.
     Leave it unset for SELF-MANAGED mode (see below).
-*   `binaryPath` **[string][4]?** path to the `obscura` executable, used in SELF-MANAGED mode
+*   `binaryPath` **[string][5]?** path to the `obscura` executable, used in SELF-MANAGED mode
     (`endpoint` unset). Checked before `OBSCURA_PATH` and `PATH`.
-*   `port` **[number][3]?** port `obscura serve` listens on, in SELF-MANAGED mode. When unset, a
+*   `port` **[number][4]?** port `obscura serve` listens on, in SELF-MANAGED mode. When unset, a
     free port is picked automatically, which is what makes `run-workers` collision-free — every
     worker gets its own instance on its own port with zero config.
-*   `serverStartTimeout` **[number][3]?** milliseconds to wait for a spawned `obscura serve`
+*   `serverStartTimeout` **[number][4]?** milliseconds to wait for a spawned `obscura serve`
     to answer `/json/version` before `_connect` gives up.
 
 
@@ -150,7 +173,7 @@ Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading ba
 port. Used as the SELF-LAUNCH default when `options.port` isn't explicitly set, so multiple
 `run-workers` workers never collide on the same port.
 
-Returns **[Promise][2]<[number][3]>** a free port.
+Returns **[Promise][3]<[number][4]>** a free port.
 
 ### _finishTest
 
@@ -170,9 +193,9 @@ Probes a `/json/version`-style URL with a short timeout, used for the COURTESY-A
 
 #### Parameters
 
-*   `url` **[string][4]**&#x20;
+*   `url` **[string][5]**&#x20;
 
-Returns **[Promise][2]<[boolean][5]>** true if the URL answered.
+Returns **[Promise][3]<[boolean][6]>** true if the URL answered.
 
 ### _resolveBinary
 
@@ -181,7 +204,7 @@ Resolves the `obscura` binary to spawn, in priority order: `options.binaryPath`,
 directories itself instead of shelling out to `which`, which does not exist on Windows: on
 Windows every `PATHEXT` suffix is tried, so an `obscura.exe` on `PATH` is found too.
 
-Returns **([string][4] | null)** an absolute or relative path to the binary, or null if none resolved.
+Returns **([string][5] | null)** an absolute or relative path to the binary, or null if none resolved.
 
 ### _resolveSelfManaged
 
@@ -200,12 +223,14 @@ is paid once per run and counts directly toward real-world startup latency.
 
 [1]: https://github.com/h4ckf0r0day/obscura
 
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[2]: https://github.com/h4ckf0r0day/obscura/releases
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

package/docs/installation.md

@@ -7,6 +7,12 @@ title: Installation
 
 For the quickest start (CodeceptJS + Playwright) follow the [Quickstart](/quickstart). This page covers every browser, mobile, and API helper and what each one needs installed.
 
+CodeceptJS 4.2 requires **Node.js 22.12 or newer**. Check your installed version before continuing:
+
+```sh
+node --version
+```
+
 ## Set up a project
 
 ```sh
@@ -64,6 +70,35 @@ WebdriverIO 9 downloads and starts the matching driver automatically — no Sele
 
 To run against a cloud grid (Sauce Labs, BrowserStack, LambdaTest, and so on) instead, set the grid's `host`, `port`, `user`, and `key` (or `protocol` / `path`) in the helper config. For running this on CI, see [Continuous Integration](/continuous-integration).
 
+## Obscura (experimental)
+
+Obscura is a lightweight browser driven through Chrome DevTools Protocol. CodeceptJS 4.2 is tested with Obscura 0.2.2. Obscura 0.2.x is the recommended version; older 0.1.x and `-no-render` builds have no layout, visibility assertions, or screenshots.
+
+Download the archive for your platform from the [Obscura releases](https://github.com/h4ckf0r0day/obscura/releases):
+
+| Platform | Rendering 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 either put `obscura` (`obscura.exe` on Windows) on `PATH`, set `OBSCURA_PATH`, or configure `binaryPath`. The helper then starts and stops `obscura serve` automatically:
+
+```js
+export const config = {
+  helpers: {
+    Obscura: {
+      url: 'http://localhost:3000',
+      // binaryPath: '/absolute/path/to/obscura', // optional
+    },
+  },
+}
+```
+
+See [Alternative Browser Engines](/alternative-browsers) for connection modes and limitations, and the [Obscura helper reference](/helpers/Obscura) for every option.
+
 ## Appium (mobile)
 
 Native iOS and Android testing. Appium speaks the WebDriver protocol, so CodeceptJS drives it through `webdriverio`:

package/docs/mcp.md

@@ -441,7 +441,7 @@ Storage capture is **enabled** for `run_code`, `snapshot`, `run_step_by_step` fa
 
 ### Server doesn't start
 
-- Node 18+ recommended.
+- Node 22.12+ is required by CodeceptJS 4.2.
 - Verify the path / `npx` resolution in your client config.
 
 ### Config not found

package/docs/migration-4.md

@@ -35,7 +35,7 @@ The rest of this guide documents every change the skill makes — read it if you
 
 ## 1. Update Node and Package
 
-CodeceptJS 4.x supports Node 16+, but Node 20 or newer is recommended.
+CodeceptJS 4.2 requires Node 22.12 or newer. This matches the minimum supported version of its current runtime dependencies. Upgrade Node before installing CodeceptJS 4.2.
 
 ```bash
 npm install codeceptjs@4
@@ -766,4 +766,4 @@ You don't need these to upgrade, but they unlock new workflows:
 4. TypeScript users: run with `tsx` installed and confirm error stack traces point at `.ts` files.
 5. If you removed `autoLogin`: confirm sessions restore under the `auth` plugin.
 6. If you used `tryTo` / `retryTo` / `eachElement` plugins: grep your tests for the old globals and switch to subpath imports.
-7. CI: bump the Node version to 20+ if you were on 18 or below.
+7. CI: bump the Node version to 22.12+.

package/docs/parallel.md

@@ -100,7 +100,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm ci
       - run: npx codeceptjs run --shard ${{ matrix.shard }}
 ```

package/lib/helper/Appium.js

@@ -1534,6 +1534,29 @@ class Appium extends Webdriver {
     return this.browser.closeApp()
   }
 
+  /**
+   * {{> clearClipboard }}
+   *
+   * Appium: support both Android and iOS
+   */
+  async clearClipboard() {
+    if (typeof this.browser.setClipboard !== 'function') return super.clearClipboard()
+    return this.browser.setClipboard('', 'plaintext')
+  }
+
+  /**
+   * {{> grabFromClipboard }}
+   *
+   * Appium: support both Android and iOS
+   */
+  async grabFromClipboard() {
+    if (typeof this.browser.getClipboard !== 'function') return super.grabFromClipboard()
+    const encoded = await this.browser.getClipboard('plaintext')
+    const clipboard = Buffer.from(encoded || '', 'base64').toString('utf8')
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
+  }
+
   /**
    * {{> appendField }}
    *

package/lib/helper/CDPBrowser.js

@@ -18,6 +18,7 @@ import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import WebElement from '../element/WebElement.js'
 import CDPElementHandle from './extras/CDPElementHandle.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript, clipboardExpression } from './extras/clipboard.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, flushNetworkTraffics } from './network/actions.js'
 import { assembleApng, isPng } from './extras/apngAssembler.js'
 
@@ -1940,6 +1941,89 @@ class CDPBrowser extends Helper {
     }
   }
 
+  /**
+   * 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 {string} text value to check.
+   * @returns {Promise<void>}
+   */
+  async seeInClipboard(text) {
+    const clipboard = await this.grabFromClipboard()
+    return stringIncludes('clipboard').assert(text, clipboard)
+  }
+
+  /**
+   * 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 {string} text value to check.
+   * @returns {Promise<void>}
+   */
+  async seeClipboardEquals(text) {
+    const clipboard = await this.grabFromClipboard()
+    return equals('clipboard').assert(clipboard, text)
+  }
+
+  /**
+   * Clears the system clipboard.
+   *
+   * ```js
+   * I.clearClipboard();
+   * I.seeClipboardEquals('');
+   * ```
+   *
+   * @returns {Promise<void>}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    await this._evaluate(clipboardExpression(writeClipboardScript, ''))
+  }
+
+  /**
+   * 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 {Promise<string>} the system clipboard contents.
+   */
+  async grabFromClipboard() {
+    await this._grantClipboardAccess()
+    const clipboard = await this._evaluate(clipboardExpression(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS))
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
+  }
+
+  /**
+   * 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
+   */
+  async _grantClipboardAccess() {
+    await this.cdp.send('Page.bringToFront', {}, this.sessionId).catch(() => null)
+    const origin = await this._evaluate('window.location.origin').catch(() => null)
+    if (!origin || !origin.startsWith('http')) return
+    await this.cdp.send('Browser.grantPermissions', { origin, permissions: ['clipboardReadWrite', 'clipboardSanitizedWrite'] }).catch(() => null)
+  }
+
   /**
    * Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
    * Filename is relative to the output folder.

package/lib/helper/Obscura.js

@@ -39,6 +39,17 @@ const config = {}
  * 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
@@ -56,8 +67,20 @@ const config = {}
  *
  * ## 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