codeceptjs 4.2.0-beta.2 → 4.2.0-beta.4

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,15 +22,26 @@ 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
     never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
 *   **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
     the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-    spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-    free port picked automatically), waits for it to answer, connects, and kills it in
-    `_finishTest`.
+    spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+    the config, or a free port picked automatically), waits for it to answer, connects, and kills
+    it in `_finishTest`.
 *   **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
     answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
     before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -39,16 +50,29 @@ 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.0/obscura-x86_64-linux.tar.gz | tar xz
+curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
 ```
 
-`--allow-private-network` is always passed by this helper (it's required to reach apps running
-on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-private-network requests by default).
+`--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+`127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+default.
 
 ## Config presets
 
@@ -67,7 +91,7 @@ Set them explicitly in your own config to skip probing or to force a mode.
 ## Limitations
 
 *   `input` is always `synthetic`, even on rendering builds — see `input` above.
-*   No frames, popups, or file uploads.
+*   No frames or popups.
 *   On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
     (`seeElement`/`dontSeeElement` always throw) — only DOM presence
     (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -83,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.
 
 
@@ -149,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
 
@@ -169,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
 
@@ -180,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
 
@@ -199,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/helpers/Playwright.md

@@ -78,7 +78,7 @@ Type: [object][6]
 *   `ignoreHTTPSErrors` **[boolean][27]?** Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
 *   `bypassCSP` **[boolean][27]?** bypass Content Security Policy or CSP
 *   `highlightElement` **[boolean][27]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
-*   `visibleLocator` **[boolean][27]?** append [`visible()`][49] to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
+*   `visibleLocator` **[boolean][27]?** append [`visible()`][49] to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
 *   `recordHar` **[object][6]?** record HAR and will be saved to `output/har`. See more of [HAR options][3].
 *   `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][50].
 *   `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or 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/command/info.js

@@ -21,9 +21,16 @@ function parsePlaywrightBrowsers(output) {
   return versions.join(', ')
 }
 
+// Bun has its own package runner and a Bun-only install has no `npx` on PATH at all, so the
+// runner has to follow the runtime that is actually executing rather than what PATH happens to hold.
+function getPackageRunner() {
+  if (process.versions.bun) return 'bunx'
+  return 'npx'
+}
+
 async function getPlaywrightBrowsers() {
   try {
-    const info = execSync('npx playwright install --dry-run').toString().trim()
+    const info = execSync(`${getPackageRunner()} playwright install --dry-run`).toString().trim()
     return parsePlaywrightBrowsers(info)
   } catch (err) {
     return 'Playwright not installed'
@@ -85,7 +92,7 @@ export default async function (path) {
   output.print('***************************************')
 }
 
-export { parsePlaywrightBrowsers, getRuntimeInfo }
+export { parsePlaywrightBrowsers, getRuntimeInfo, getPackageRunner }
 
 export const getMachineInfo = async () => {
   const info = {

package/lib/helper/CDPBrowser.js

@@ -1631,6 +1631,9 @@ class CDPBrowser extends Helper {
     const value = Array.isArray(option) ? option.map(String) : String(option)
     const res = await this._run(this._candidates(select, 'field'), 'select', { value }, context)
     if (!res.found) throw new ElementNotFound(select, 'Selectable field')
+    if (res.result === '__RADIOGROUP_MULTI__') {
+      throw new Error(`selectOption: a radio group holds one value, but ${value.length} options were passed: ${value.join(', ')}`)
+    }
     if (res.result === false) throw new Error(`Option "${Array.isArray(option) ? option.join(',') : option}" not found in ${new Locator(select).toString()}`)
   }
 
@@ -1810,7 +1813,6 @@ class CDPBrowser extends Helper {
    */
   async waitInUrl(urlPart, sec = null) {
     const timeout = sec || this.options.waitForTimeout
-    const expectedUrl = resolveUrl(urlPart, this.options.url)
     let lastUrl = ''
     try {
       return await this._poll(
@@ -1822,7 +1824,7 @@ class CDPBrowser extends Helper {
         'placeholder',
       )
     } catch (e) {
-      throw new Error(`expected url to include ${expectedUrl}, but found ${lastUrl}`)
+      throw new Error(`expected url to include ${urlPart}, but found ${lastUrl}`)
     }
   }
 

package/lib/helper/Obscura.js

@@ -39,15 +39,26 @@ 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
  *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
  * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
  *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
- *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
- *   free port picked automatically), waits for it to answer, connects, and kills it in
- *   `_finishTest`.
+ *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+ *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+ *   it in `_finishTest`.
  * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
  *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
  *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -56,16 +67,29 @@ 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.0/obscura-x86_64-linux.tar.gz | tar xz
+ * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
  * ```
  *
- * `--allow-private-network` is always passed by this helper (it's required to reach apps running
- * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
- * private-network requests by default).
+ * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+ * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+ * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+ * default.
  *
  * ## Config presets
  *
@@ -84,7 +108,7 @@ const config = {}
  * ## Limitations
  *
  * - `input` is always `synthetic`, even on rendering builds — see `input` above.
- * - No frames, popups, or file uploads.
+ * - No frames or popups.
  * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
  *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
  *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -179,7 +203,7 @@ class Obscura extends CDPBrowser {
       const port = this.options.port || (await this._findFreePort())
       this.options.port = port
       this.serverError = null
-      this.serverProcess = spawn(binaryPath, ['serve', '--port', String(port), '--allow-private-network'], { stdio: 'ignore' })
+      this.serverProcess = spawn(binaryPath, ['serve', '--port', String(port), '--allow-private-network', '--allow-file-access'], { stdio: 'ignore' })
       this.serverProcess.on('error', err => {
         this.serverError = err
       })

package/lib/helper/Playwright.js

@@ -50,7 +50,7 @@ let defaultSelectorEnginesInitialized = false
 const popupStore = new Popup()
 const consoleLogStore = new Console()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
-const domPresenceSteps = ['seeElementInDOM', 'dontSeeElementInDOM', 'seeNumberOfElements']
+const visibilityAgnosticSteps = ['seeElementInDOM', 'dontSeeElementInDOM', 'seeNumberOfElements', 'scrollTo']
 const checkableRoles = ['checkbox', 'radio', 'switch']
 
 import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
@@ -103,7 +103,7 @@ const pathSeparator = path.sep
  * @prop {boolean} [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
  * @prop {boolean} [bypassCSP] - bypass Content Security Policy or CSP
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
- * @prop {boolean} [visibleLocator=false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
+ * @prop {boolean} [visibleLocator=false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
  * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
  * @prop {string} [testIdAttribute=data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
  * @prop {string|object} [storageState] - Playwright storage state (path to JSON file or object)
@@ -559,7 +559,8 @@ class Playwright extends Helper {
   }
 
   _beforeStep(step) {
-    store.visibleLocator = step.opts?.visibleLocator ?? (this.options.visibleLocator && !domPresenceSteps.includes(step.helperMethod))
+    const reachesHidden = step.helperMethod?.startsWith('grab') || visibilityAgnosticSteps.includes(step.helperMethod)
+    store.visibleLocator = step.opts?.visibleLocator ?? (this.options.visibleLocator && !reachesHidden)
   }
 
   async _before(test) {
@@ -583,7 +584,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') {
@@ -592,7 +594,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()
@@ -697,6 +700,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
@@ -1525,6 +1534,7 @@ class Playwright extends Helper {
       assertElementExists(el, locator)
     }
 
+    await el.scrollIntoViewIfNeeded()
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await clickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)
@@ -3665,8 +3675,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

@@ -354,7 +354,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 +364,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
@@ -845,6 +853,9 @@ class Puppeteer extends Helper {
       }
     }
 
+    if (!(await el.isIntersectingViewport({ threshold: 1 }))) {
+      await el.evaluate(el => el.scrollIntoView({ block: 'center', inline: 'center' }))
+    }
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await getClickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)

package/lib/helper/clientscripts/cdpBrowserClient.js

@@ -387,6 +387,17 @@ export default function installCodeceptClient(xpathNeedsPolyfill) {
         return true
       }
 
+      if (resolveRole(el) === 'radiogroup') {
+        if (values.length > 1) return '__RADIOGROUP_MULTI__'
+        const radios = Array.from(el.querySelectorAll('[role="radio"]'))
+        const [wanted] = values
+        const named = (radio, matchFn) => roleTextCandidates(radio).some(matchFn)
+        const radio = radios.find(r => named(r, t => t === wanted)) || radios.find(r => named(r, t => t.indexOf(wanted) !== -1))
+        if (!radio) return false
+        radio.click()
+        return true
+      }
+
       // ARIA combobox/listbox widgets: click the trigger (if any) to reveal the
       // listbox, then click each matching [role="option"].
       let container = el

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.2",
+  "version": "4.2.0-beta.4",
   "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

@@ -3423,15 +3423,26 @@ 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
      *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
      * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
      *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-     *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-     *   free port picked automatically), waits for it to answer, connects, and kills it in
-     *   `_finishTest`.
+     *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+     *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+     *   it in `_finishTest`.
      * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
      *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
      *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -3440,16 +3451,29 @@ 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.0/obscura-x86_64-linux.tar.gz | tar xz
+     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
      * ```
      *
-     * `--allow-private-network` is always passed by this helper (it's required to reach apps running
-     * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-     * private-network requests by default).
+     * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+     * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+     * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+     * default.
      *
      * ## Config presets
      *
@@ -3468,7 +3492,7 @@ declare namespace CodeceptJS {
      * ## Limitations
      *
      * - `input` is always `synthetic`, even on rendering builds — see `input` above.
-     * - No frames, popups, or file uploads.
+     * - No frames or popups.
      * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
      *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
      *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -3607,7 +3631,7 @@ declare namespace CodeceptJS {
      * @property [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
      * @property [bypassCSP] - bypass Content Security Policy or CSP
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
-     * @property [visibleLocator = false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
+     * @property [visibleLocator = false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
      * @property [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
      * @property [testIdAttribute = data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
      * @property [storageState] - Playwright storage state (path to JSON file or object)

package/typings/types.d.ts

@@ -3456,15 +3456,26 @@ 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
      *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
      * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
      *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-     *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-     *   free port picked automatically), waits for it to answer, connects, and kills it in
-     *   `_finishTest`.
+     *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+     *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+     *   it in `_finishTest`.
      * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
      *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
      *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -3473,16 +3484,29 @@ 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.0/obscura-x86_64-linux.tar.gz | tar xz
+     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
      * ```
      *
-     * `--allow-private-network` is always passed by this helper (it's required to reach apps running
-     * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-     * private-network requests by default).
+     * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+     * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+     * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+     * default.
      *
      * ## Config presets
      *
@@ -3501,7 +3525,7 @@ declare namespace CodeceptJS {
      * ## Limitations
      *
      * - `input` is always `synthetic`, even on rendering builds — see `input` above.
-     * - No frames, popups, or file uploads.
+     * - No frames or popups.
      * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
      *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
      *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -3641,7 +3665,7 @@ declare namespace CodeceptJS {
      * @property [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
      * @property [bypassCSP] - bypass Content Security Policy or CSP
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
-     * @property [visibleLocator = false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
+     * @property [visibleLocator = false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
      * @property [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
      * @property [testIdAttribute = data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
      * @property [storageState] - Playwright storage state (path to JSON file or object)