codeceptjs 4.1.0 → 4.2.0-beta.1

package/lib/helper/Kitesurf.js

@@ -0,0 +1,139 @@
+import axios from 'axios'
+import CDPBrowser from './CDPBrowser.js'
+
+/**
+ * ## Configuration
+ *
+ * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
+ * accepts (see its config table), plus:
+ *
+ * @typedef KitesurfConfig
+ * @type {object}
+ * @prop {string} [url=http://localhost] - base URL for tests
+ * @prop {string} [accountId] - Cloudflare account ID; defaults to CF_ACCOUNT_ID env var
+ * @prop {string} [apiToken] - Cloudflare API token; defaults to CF_API_TOKEN env var
+ * @prop {number} [keepAlive=240000] - session keep-alive time in milliseconds
+ * @prop {string} [apiBase=https://api.cloudflare.com/client/v4] - Cloudflare API base URL
+ * @prop {string} [input=cdp] - input method for user actions; defaults to 'cdp' for Kitesurf's real layout engine, but can be overridden
+ * @prop {object} [capabilities] - pre-configured capabilities; Kitesurf uses { layout: 'real', screenshot: true }
+ */
+const config = {}
+
+/**
+ * Kitesurf is a cloud browser helper that extends CDPBrowser to run tests against
+ * Cloudflare's Browser Run service (Kitesurf browser). It automates real browser
+ * sessions in Cloudflare's cloud infrastructure, eliminating the need to manage
+ * local browser instances.
+ *
+ * **Status:** Beta
+ *
+ * ## Requirements
+ *
+ * - Cloudflare account with Browser Run enabled
+ * - API token with **Browser Rendering Edit** permission
+ *
+ * ## Setup
+ *
+ * To create an API token with Browser Rendering Edit permission:
+ * 1. Log in to your Cloudflare dashboard
+ * 2. Go to My Profile > API Tokens
+ * 3. Click "Create Token"
+ * 4. Use the "Custom token" template
+ * 5. Under "Permissions", select "Browser Rendering" > "Edit"
+ * 6. Set the account scope to your target account
+ * 7. Copy the token and set it as `CF_API_TOKEN` environment variable
+ *
+ * For more details, see:
+ * - [Cloudflare Browser Run Developers Docs](https://developers.cloudflare.com/browser-run/)
+ * - [Cloudflare Blog - Kitesurf Announcement](https://blog.cloudflare.com/kitesurf/)
+ *
+ * ## Example
+ *
+ * ```js
+ * // codecept.conf.js
+ * {
+ *   helpers: {
+ *     Kitesurf: {
+ *       url: 'https://example.com',
+ *       accountId: process.env.CF_ACCOUNT_ID,
+ *       apiToken: process.env.CF_API_TOKEN,
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Or set environment variables and rely on defaults:
+ *
+ * ```bash
+ * export CF_ACCOUNT_ID="your-account-id"
+ * export CF_API_TOKEN="your-api-token"
+ * ```
+ *
+ * <!-- configuration -->
+ *
+ * ## Methods
+ */
+class Kitesurf extends CDPBrowser {
+  /**
+   * @param {KitesurfConfig} config
+   */
+  constructor(config) {
+    super({
+      input: 'cdp',
+      keepAlive: 240000,
+      apiBase: 'https://api.cloudflare.com/client/v4',
+      ...config,
+      capabilities: { layout: 'real', screenshot: true, ...(config.capabilities || {}) },
+    })
+    this.options.accountId = this.options.accountId || process.env.CF_ACCOUNT_ID
+    this.options.apiToken = this.options.apiToken || process.env.CF_API_TOKEN
+    this.cloudSessionId = null
+  }
+
+  /**
+   * Acquires a Kitesurf browser session from the Cloudflare Browser Run API and resolves it to
+   * the `wss://` debugger URL `CDPConnection` connects to. Overrides `CDPBrowser._resolveEndpoint`,
+   * which resolves a fixed local endpoint instead of provisioning a cloud session per test.
+   *
+   * @returns {Promise<string>} a `wss://` debugger URL ready to be passed to `CDPConnection`.
+   * @protected
+   */
+  async _resolveEndpoint() {
+    if (!this.options.accountId || !this.options.apiToken) {
+      throw new Error('Kitesurf requires accountId and apiToken (or CF_ACCOUNT_ID / CF_API_TOKEN env vars)')
+    }
+    const url = `${this.options.apiBase}/accounts/${this.options.accountId}/browser-run/devtools/browser?browser=kitesurf&keep_alive=${this.options.keepAlive}`
+    const res = await axios.post(url, null, { headers: { Authorization: `Bearer ${this.options.apiToken}` }, validateStatus: () => true })
+    const data = res.data
+    if (!data || !data.webSocketDebuggerUrl) {
+      throw new Error(`Could not acquire Kitesurf session: ${JSON.stringify(data).slice(0, 300)}`)
+    }
+    this.cloudSessionId = data.sessionId
+    this.options.headers = { Authorization: `Bearer ${this.options.apiToken}` }
+    return data.webSocketDebuggerUrl
+  }
+
+  /**
+   * Closes the target as `CDPBrowser._finishTest` does, then releases the cloud session acquired
+   * in `_resolveEndpoint` via the Cloudflare API so it does not linger for the full `keepAlive`
+   * window. The release runs in a `finally` so a rejection while closing the CDP connection still
+   * frees the cloud session instead of leaving the browser alive until `keepAlive` expires; the
+   * session id is cleared before the request, so a repeated call never releases it twice.
+   *
+   * @protected
+   */
+  async _finishTest() {
+    try {
+      await super._finishTest()
+    } finally {
+      if (this.cloudSessionId) {
+        const sessionId = this.cloudSessionId
+        this.cloudSessionId = null
+        const url = `${this.options.apiBase}/accounts/${this.options.accountId}/browser-run/devtools/browser/${sessionId}`
+        await axios.delete(url, { headers: { Authorization: `Bearer ${this.options.apiToken}` } }).catch(() => null)
+      }
+    }
+  }
+}
+
+export default Kitesurf

package/lib/helper/Obscura.js

@@ -0,0 +1,344 @@
+import { spawn } from 'child_process'
+import fs from 'fs'
+import net from 'net'
+import path from 'path'
+import axios from 'axios'
+import CDPBrowser from './CDPBrowser.js'
+import { isFile, isWindows } from '../utils.js'
+
+/**
+ * ## Configuration
+ *
+ * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
+ * accepts (see its config table), plus:
+ *
+ * @typedef ObscuraConfig
+ * @type {object}
+ * @prop {string} [endpoint] - 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).
+ * @prop {string} [binaryPath] - path to the `obscura` executable, used in SELF-MANAGED mode
+ * (`endpoint` unset). Checked before `OBSCURA_PATH` and `PATH`.
+ * @prop {number} [port] - 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.
+ * @prop {number} [serverStartTimeout=15000] - milliseconds to wait for a spawned `obscura serve`
+ * to answer `/json/version` before `_connect` gives up.
+ */
+const config = {}
+
+/**
+ * Obscura drives [Obscura](https://github.com/h4ckf0r0day/obscura), a minimal headless
+ * browser exposed over the Chrome DevTools Protocol. From v0.2.0, default release builds ship a
+ * real rendering engine (layout, paint, screenshots); `-no-render` variants and v0.1.x builds keep
+ * the original single-V8-isolate, nothing-rendered mode. This helper does not hardcode which mode a
+ * given binary is in — `CDPBrowser._probeCapabilities` detects `layout`/`screenshot` per binary at
+ * runtime, so the same helper works against either.
+ *
+ * This helper is a thin `CDPBrowser` subclass: it changes nothing about how locating or acting on
+ * 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.
+ *
+ * ## 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`.
+ * - **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
+ *   helper's process to kill. If neither a binary nor a running server on :9222 can be found, the
+ *   helper throws a loud, actionable error.
+ *
+ * ## 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:
+ *
+ * ```sh
+ * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/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).
+ *
+ * ## Config presets
+ *
+ * These are set automatically and only need overriding for unusual setups:
+ *
+ * | option | value | why |
+ * | --- | --- | --- |
+ * | `input` | `synthetic` | coordinate-click navigation is unreliable over CDP on Obscura even on rendering builds (no `frameNavigated` event, stale `page.url()`); `click` always takes the `forceClick` path — on Obscura, `click` and `forceClick` are the same thing |
+ * | `xpathPolyfill` | `auto` | probed per binary/page: Obscura's native `document.evaluate` still doesn't support attribute selection or `not()`, so the polyfill is used until that lands |
+ *
+ * `capabilities.layout`/`capabilities.screenshot`/`capabilities.xpath` are intentionally left
+ * unset here — `CDPBrowser._probeCapabilities` detects them at runtime from the actual binary
+ * (`'real'`/`true` on v0.2.0+ default builds, `'none'`/`false` on `-no-render` builds and v0.1.x).
+ * 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.
+ * - 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.
+ * - On v0.2.0+ default (rendering) builds: layout, screenshots, and CSS work, but it's a new,
+ *   independently implemented rendering/CSS engine — expect edge cases and gaps versus a real browser.
+ * - Single V8 isolate: heavy or long-running pages, or many pages in parallel against one
+ *   `obscura serve` process, compete for the same isolate.
+ *
+ * <!-- configuration -->
+ *
+ * ## Example
+ *
+ * ```js
+ * // inside codecept.conf.js — SELF-LAUNCH mode (recommended): the helper finds/starts/stops
+ * // obscura serve on its own, on a free port. Ideal for run-workers: every worker gets its own
+ * // instance with no config.
+ * {
+ *   helpers: {
+ *     Obscura: {
+ *       url: 'http://localhost',
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ```js
+ * // ATTACH mode — connect to an Obscura instance you manage yourself (remote host, container, etc.)
+ * {
+ *   helpers: {
+ *     Obscura: {
+ *       url: 'http://localhost',
+ *       endpoint: 'http://127.0.0.1:9222',
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Methods
+ */
+class Obscura extends CDPBrowser {
+  /**
+   * @param {ObscuraConfig} config
+   */
+  constructor(config) {
+    const explicitEndpoint = !!(config && config.endpoint)
+    super({
+      input: 'synthetic',
+      xpathPolyfill: 'auto',
+      ...config,
+    })
+    this.mode = explicitEndpoint ? 'attach' : 'self-managed'
+    if (!explicitEndpoint) {
+      this.options.endpoint = null
+    }
+    this.serverProcess = null
+    this.serverError = null
+    this.binaryPath = null
+    this._selfManagedResolved = false
+  }
+
+  /**
+   * In ATTACH mode, connects exactly as `CDPBrowser._connect` would. In SELF-MANAGED mode,
+   * resolves and spawns `obscura serve` (or courtesy-attaches to an already-running one on
+   * :9222) exactly once via `_resolveSelfManaged`, then connects.
+   *
+   * A spawn failure (e.g. a bad binary) is delivered asynchronously by Node as an `error`
+   * event; it is recorded on `this.serverError` and surfaced as a rejection from `_waitForServer`
+   * instead of crashing the process as an uncaught exception.
+   *
+   * @protected
+   */
+  async _connect() {
+    if (this.mode !== 'attach' && !this._selfManagedResolved) {
+      await this._resolveSelfManaged()
+      this._selfManagedResolved = true
+    }
+    return super._connect()
+  }
+
+  /**
+   * Resolves how to reach Obscura when no explicit `endpoint` was configured, trying, in order:
+   * spawn a binary (`binaryPath` config, then `OBSCURA_PATH` env, then `obscura` on `PATH`),
+   * courtesy-attach to `http://127.0.0.1:9222` if something already answers there, or throw a
+   * loud, actionable error. Sets `this.options.endpoint` as a side effect.
+   *
+   * @protected
+   */
+  async _resolveSelfManaged() {
+    const binaryPath = this._resolveBinary()
+    if (binaryPath) {
+      this.binaryPath = binaryPath
+      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.on('error', err => {
+        this.serverError = err
+      })
+      await this._waitForServer()
+      this.options.endpoint = `ws://127.0.0.1:${port}/devtools/browser`
+      return
+    }
+    if (await this._probeUp('http://127.0.0.1:9222/json/version')) {
+      this.debugSection('Obscura', 'no binaryPath/OBSCURA_PATH/obscura-on-PATH found — courtesy-attaching to an already-running obscura serve on 127.0.0.1:9222 (this helper will not manage or kill it)')
+      this.options.endpoint = 'http://127.0.0.1:9222'
+      return
+    }
+    throw new Error(
+      [
+        'Obscura has no endpoint configured, no binary could be resolved (checked config.binaryPath, OBSCURA_PATH, and PATH), and nothing answered http://127.0.0.1:9222/json/version.',
+        'Start it yourself:  obscura serve --port 9222 --allow-private-network',
+        'Or let this helper launch it: put a release binary on PATH, set OBSCURA_PATH=/path/to/obscura, or pass binaryPath in the config.',
+        'Releases: https://github.com/h4ckf0r0day/obscura/releases',
+      ].join('\n  '),
+    )
+  }
+
+  /**
+   * Resolves the `obscura` binary to spawn, in priority order: `options.binaryPath`, then the
+   * `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The `PATH` lookup walks the
+   * 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|null} an absolute or relative path to the binary, or null if none resolved.
+   * @protected
+   */
+  _resolveBinary() {
+    if (this.options.binaryPath) return this.options.binaryPath
+    if (process.env.OBSCURA_PATH) return process.env.OBSCURA_PATH
+    const windows = isWindows()
+    const extensions = windows ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : ['']
+    for (const entry of (process.env.PATH || '').split(path.delimiter)) {
+      const dir = windows ? entry.replace(/^"|"$/g, '') : entry
+      if (!dir) continue
+      for (const extension of extensions) {
+        const candidate = path.join(dir, `obscura${extension}`)
+        if (!isFile(candidate)) continue
+        try {
+          fs.accessSync(candidate, fs.constants.X_OK)
+          return candidate
+        } catch (e) {
+          continue
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the OS-assigned
+   * 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<number>} a free port.
+   * @protected
+   */
+  async _findFreePort() {
+    return new Promise((resolve, reject) => {
+      const srv = net.createServer()
+      srv.unref()
+      srv.on('error', reject)
+      srv.listen(0, '127.0.0.1', () => {
+        const { port } = srv.address()
+        srv.close(() => resolve(port))
+      })
+    })
+  }
+
+  /**
+   * Probes a `/json/version`-style URL with a short timeout, used for the COURTESY-ATTACH check.
+   *
+   * @param {string} url
+   * @returns {Promise<boolean>} true if the URL answered.
+   * @protected
+   */
+  async _probeUp(url) {
+    try {
+      await axios.get(url, { timeout: 1000 })
+      return true
+    } catch (e) {
+      return false
+    }
+  }
+
+  /**
+   * Polls `http://127.0.0.1:<port>/json/version` until `obscura serve` responds, `this.serverError`
+   * is set by the spawned process' `error` event, or `options.serverStartTimeout` elapses. The
+   * process typically comes up within tens of milliseconds — a 20ms retry interval (down from a
+   * previous 200ms) keeps the wasted tail after the server is actually ready small, since this cost
+   * is paid once per run and counts directly toward real-world startup latency.
+   *
+   * @protected
+   */
+  async _waitForServer() {
+    const timeout = this.options.serverStartTimeout || 15000
+    const deadline = Date.now() + timeout
+    while (Date.now() < deadline) {
+      if (this.serverError) {
+        throw new Error(`Failed to start obscura at ${this.binaryPath}: ${this.serverError.message}`)
+      }
+      try {
+        await axios.get(`http://127.0.0.1:${this.options.port}/json/version`)
+        return
+      } catch (e) {
+        await new Promise(r => setTimeout(r, 20))
+      }
+    }
+    if (this.serverError) {
+      throw new Error(`Failed to start obscura at ${this.binaryPath}: ${this.serverError.message}`)
+    }
+    throw new Error(`obscura serve did not start on port ${this.options.port} within ${timeout}ms`)
+  }
+
+  /**
+   * Closes the CDP connection (via `CDPBrowser._finishTest`), then kills the `obscura serve`
+   * process spawned by `_connect`, if any (never runs in ATTACH or COURTESY-ATTACH mode, since
+   * `this.serverProcess` is only ever set in SELF-LAUNCH mode). Runs in a `finally` so the process
+   * is always reaped even if closing the CDP connection throws. Sends `SIGTERM` first and waits for
+   * the process to exit; a process that ignores `SIGTERM` is escalated to `SIGKILL` after 5s. The
+   * promise only resolves once the child has actually exited (confirmed via the `exit` event, not
+   * merely once `SIGKILL` was sent — the kernel needs a moment to reap it), with a final safety-net
+   * timeout so a stuck child can never keep the event loop alive even if that confirmation is
+   * somehow lost.
+   *
+   * @protected
+   */
+  async _finishTest() {
+    try {
+      await super._finishTest()
+    } finally {
+      if (this.serverProcess) {
+        const proc = this.serverProcess
+        this.serverProcess = null
+        await new Promise(resolve => {
+          if (proc.exitCode !== null || proc.signalCode !== null) {
+            resolve()
+            return
+          }
+          let settled = false
+          const finish = () => {
+            if (settled) return
+            settled = true
+            clearTimeout(killTimer)
+            clearTimeout(safetyTimer)
+            resolve()
+          }
+          proc.once('exit', finish)
+          const killTimer = setTimeout(() => proc.kill('SIGKILL'), 5000)
+          const safetyTimer = setTimeout(finish, 5500)
+          proc.kill()
+        })
+      }
+    }
+  }
+}
+
+export default Obscura

package/lib/helper/Playwright.js

@@ -50,6 +50,7 @@ let defaultSelectorEnginesInitialized = false
 const popupStore = new Popup()
 const consoleLogStore = new Console()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
+const checkableRoles = ['checkbox', 'radio', 'switch']
 
 import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
 import { createValueEngine, createDisabledEngine } from './extras/PlaywrightPropEngine.js'
@@ -2404,6 +2405,10 @@ class Playwright extends Helper {
     els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
     if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
+    // Fuzzy: try radiogroup
+    els = await findByRole(comboboxSearchCtx, { role: 'radiogroup', name: matchedLocator.value })
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
+
     // Fuzzy: try native select
     els = await findFields.call(this, select, context)
     assertElementExists(els, select, 'Selectable element')
@@ -3423,7 +3428,6 @@ class Playwright extends Helper {
    */
   async waitInUrl(urlPart, sec = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
-    const expectedUrl = resolveUrl(urlPart, this.options.url)
 
     return this.page
       .waitForFunction(
@@ -3431,13 +3435,13 @@ class Playwright extends Helper {
           const currUrl = decodeURIComponent(decodeURIComponent(decodeURIComponent(window.location.href)))
           return currUrl.indexOf(urlPart) > -1
         },
-        expectedUrl,
+        urlPart,
         { timeout: waitTimeout },
       )
       .catch(async e => {
         const currUrl = await this._getPageUrl()
         if (/Timeout/i.test(e.message)) {
-          throw new Error(`expected url to include ${expectedUrl}, but found ${currUrl}`)
+          throw new Error(`expected url to include ${urlPart}, but found ${currUrl}`)
         } else {
           throw e
         }
@@ -4385,6 +4389,17 @@ async function findCheckable(locator, context) {
     return findElements.call(this, contextEl, matchedLocator)
   }
 
+  for (const exact of [true, false]) {
+    for (const role of checkableRoles) {
+      try {
+        const roleEls = await contextEl.getByRole(role, { name: matchedLocator.value, exact }).all()
+        if (roleEls.length) return roleEls
+      } catch (err) {
+        // getByRole not supported or failed
+      }
+    }
+  }
+
   const literal = xpathLocator.literal(matchedLocator.value)
   let els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
   if (els.length) {
@@ -4477,6 +4492,18 @@ async function proceedSelect(context, el, option) {
     return this._waitForAction()
   }
 
+  if (role === 'radiogroup') {
+    if (options.length > 1) throw new Error(`selectOption: a radio group holds one value, but ${options.length} options were passed: ${options.join(', ')}`)
+    const [opt] = options
+    let optEl = el.getByRole('radio', { name: opt, exact: true }).first()
+    if (!(await optEl.count())) optEl = el.getByRole('radio', { name: opt }).first()
+    if (!(await optEl.count())) throw new ElementNotFound(opt, 'Option', 'was not found in this radio group')
+    this.debugSection('SelectOption', `Clicking: "${opt}"`)
+    await highlightActiveElement.call(this, optEl)
+    await optEl.click()
+    return this._waitForAction()
+  }
+
   await highlightActiveElement.call(this, el)
   let optionToSelect = option
   try {