codeceptjs 4.2.0 → 4.2.1-beta.1

package/lib/helper/Obscura.js

@@ -1,43 +1,26 @@
-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:
+ * This helper should be configured in codecept.conf.js
  *
  * @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.
+ * @prop {string} [endpoint] - connect to a running Obscura instead of starting one (ATTACH mode).
+ * @prop {string} [binaryPath] - path to the `obscura` executable. Checked before `OBSCURA_PATH` and `PATH`.
+ * @prop {number} [port] - port for `obscura serve`. A free port is picked when unset, so parallel workers never collide.
+ * @prop {number} [serverStartTimeout=15000] - how long to wait for `obscura serve` to start, in milliseconds.
  */
 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.
+ * Obscura drives [Obscura](https://github.com/h4ckf0r0day/obscura), a lightweight headless
+ * browser controlled over the Chrome DevTools Protocol. Default builds from v0.2.0 render pages
+ * (layout, screenshots); `-no-render` builds and v0.1.x run JavaScript and the DOM only. The helper
+ * detects which build it runs against, so the same config works for both.
  *
- * 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.
+ * The helper starts and stops `obscura serve` for you, the same way Playwright manages its browser.
  *
  * > Obscura support is experimental in CodeceptJS 4.2. Pin the browser version in CI and keep a
  * > Playwright/WebDriver job for browser-compatibility coverage.
@@ -57,8 +40,8 @@ const config = {}
  * - **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 --allow-file-access` (`port` from
- *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
- *   it in `_finishTest`.
+ *   the config, or a free port picked automatically), waits for it to answer, connects, and stops
+ *   it when tests finish.
  * - **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
@@ -97,13 +80,11 @@ const config = {}
  *
  * | 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 |
+ * | `input` | `synthetic` | clicks that navigate are unreliable in Obscura, so `click` behaves like `forceClick` |
+ * | `xpathPolyfill` | `auto` | Obscura's XPath lacks attribute selection and `not()`, so the polyfill is used when needed |
  *
- * `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.
+ * `capabilities` are detected at runtime from the Obscura build. Set them in your config to skip
+ * detection or to force a mode.
  *
  * ## Limitations
  *
@@ -153,216 +134,18 @@ 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', '--allow-file-access'], { 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))
-      })
+    this._manageServer(config, {
+      name: 'obscura',
+      envVar: 'OBSCURA_PATH',
+      args: port => ['serve', '--port', String(port), '--allow-private-network', '--allow-file-access'],
+      releases: 'https://github.com/h4ckf0r0day/obscura/releases',
     })
   }
-
-  /**
-   * 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

@@ -27,6 +27,7 @@ import {
   normalizeSpacesInString,
   normalizePath,
   resolveUrl,
+  appendBaseUrl,
   relativeDir,
   getMimeType,
   base64EncodeFile,
@@ -1365,7 +1366,7 @@ class Playwright extends Helper {
     }
 
     if (!/^\w+\:(\/\/|.+)/.test(url)) {
-      url = this.options.url + (!this.options.url.endsWith('/') && url.startsWith('/') ? url : `/${url}`)
+      url = appendBaseUrl(this.options.url, url)
       this.debug(`Changed URL to base url + relative path: ${url}`)
     }
 
@@ -3124,7 +3125,7 @@ class Playwright extends Helper {
 
     if (url.startsWith('/')) {
       // local url
-      url = this.options.url + url
+      url = appendBaseUrl(this.options.url, url)
       this.debugSection('URL', url)
     }
 
@@ -4427,7 +4428,8 @@ async function proceedSee(assertType, text, context, strict = false) {
     description = `element ${locator.toString()}`
     const els = await this._locate(locator)
     assertElementExists(els, locator.toString())
-    allText = await Promise.all(els.map(el => el.innerText()))
+    allText = (await Promise.all(els.map(el => el.evaluateAll(nodes => nodes.map(node => node.innerText ?? node.textContent))))).flat()
+    assertElementExists(allText, locator.toString())
   }
 
   if (store?.currentStep?.opts?.ignoreCase === true) {
@@ -4945,7 +4947,7 @@ async function highlightActiveElement(element) {
 }
 
 async function elToString(el, numberOfElements) {
-  const html = await el.evaluate(node => node.outerHTML)
+  const html = await el.evaluate(node => node.outerHTML, undefined, { timeout: 100 }).catch(() => '<unavailable>')
   return (
     html
       .replace(/\n/g, '')

package/lib/helper/Puppeteer.js

@@ -30,6 +30,7 @@ import {
   normalizeSpacesInString,
   normalizePath,
   resolveUrl,
+  appendBaseUrl,
   getMimeType,
   base64EncodeFile,
 } from '../utils.js'
@@ -751,7 +752,7 @@ class Puppeteer extends Helper {
    */
   async amOnPage(url) {
     if (!/^\w+\:\/\//.test(url)) {
-      url = this.options.url + url
+      url = appendBaseUrl(this.options.url, url)
     }
 
     if (this.options.basicAuth && this.isAuthenticated !== true) {
@@ -3216,14 +3217,18 @@ async function proceedSee(assertType, text, context, strict = false) {
   let description
   let allText
   if (!context) {
-    let el = await this.context
+    if (this.withinLocator) {
+      let el = await this.context
 
-    if (el && !el.getProperty) {
-      // Fallback to body
-      el = await this.context.$('body')
-    }
+      if (el && !el.getProperty) {
+        el = await this.context.$('body')
+      }
 
-    allText = [await el.evaluate(node => node.innerText)]
+      allText = [await el.evaluate(node => node.innerText)]
+    } else {
+      const ctx = await this._getContext()
+      allText = [await ctx.evaluate(() => document.body.innerText)]
+    }
     description = 'web application'
   } else {
     const locator = new Locator(context, 'css')

package/lib/helper/WebDriver.js

@@ -27,6 +27,7 @@ import {
   modifierKeys,
   normalizePath,
   resolveUrl,
+  appendBaseUrl,
   getMimeType,
   base64EncodeFile,
 } from '../utils.js'
@@ -1063,7 +1064,7 @@ class WebDriver extends Helper {
     let split_url
     if (this.options.basicAuth) {
       if (url.startsWith('/')) {
-        url = this.options.url + url
+        url = appendBaseUrl(this.options.url, url)
       }
       split_url = url.split('//')
       url = `${split_url[0]}//${this.options.basicAuth.username}:${this.options.basicAuth.password}@${split_url[1]}`

package/lib/listener/result.js

@@ -9,4 +9,8 @@ export default function () {
   event.dispatcher.on(event.test.before, test => {
     container.result().addTest(test)
   })
+
+  event.dispatcher.on(event.test.failed, test => {
+    container.result().addTest(test)
+  })
 }

package/lib/mocha/bdd.js

@@ -145,15 +145,33 @@ const Before = fn => {
   event.dispatcher.on(event.test.started, fn)
 }
 
+const GherkinBefore = Before
+
 const After = fn => {
   event.dispatcher.on(event.test.finished, fn)
 }
 
+const GherkinAfter = After
+
 const Fail = fn => {
   event.dispatcher.on(event.test.failed, fn)
 }
 
-export { Given, When, Then, And, Before, After, Fail, matchStep, getSteps, clearSteps, defineParameterType }
+export {
+  Given,
+  When,
+  Then,
+  And,
+  Before,
+  GherkinBefore,
+  After,
+  GherkinAfter,
+  Fail,
+  matchStep,
+  getSteps,
+  clearSteps,
+  defineParameterType
+}
 
 export default {
   Given: addStep,

package/lib/plugin/junitReporter.js

@@ -122,7 +122,10 @@ export default function (config = {}) {
 
 function buildXml(result, config, hookFailures = []) {
   const doc = new DOMImplementation().createDocument(null, null, null)
-  const allTests = result.tests.concat(hookFailures)
+  const failureKey = (suiteTitle, message) => `${suiteTitle || ''}::${String(message || '').replace(/\s+/g, ' ').trim()}`
+  const hookFailureKeys = new Set(hookFailures.map(hf => failureKey(hf.parent && hf.parent.title, hf.err && hf.err.message)))
+  const tests = result.tests.filter(test => !hookFailureKeys.has(failureKey(test.parent && test.parent.title, test.err && test.err.message)))
+  const allTests = tests.concat(hookFailures)
   const suites = groupBySuite(allTests)
 
   const root = doc.createElement('testsuites')

package/lib/plugin/pause.js

@@ -2,6 +2,7 @@ import event from '../event.js'
 import pause from '../pause.js'
 import recorder from '../recorder.js'
 import output from '../output.js'
+import { isEffectActive } from '../effects.js'
 import {
   parsePluginArgs,
   resolveTrigger,
@@ -27,7 +28,8 @@ import {
  *
  * #### `on=` modes
  *
- * * **fail** — pause when a step fails (default)
+ * * **fail** — pause when a step fails (default). Failures inside `tryTo` and
+ *   non-final `retryTo` attempts are ignored
  * * **test** — pause after each test
  * * **step** — pause before the first step (interactive walk-through)
  * * **file** — pause when execution reaches `path=...[;line=...]`
@@ -69,6 +71,7 @@ function initFailMode() {
   })
 
   event.dispatcher.on(event.step.failed, () => {
+    if (isEffectActive()) return
     failed = true
   })