codeceptjs 4.1.0 → 4.2.0-beta.2

package/lib/plugin/screencast.js

@@ -20,16 +20,21 @@ const defaultConfig = {
 }
 
 /**
- * Records WebM video of tests using Playwright's screencast API.
+ * Records a video of tests. Uses Playwright's `page.screencast` API (WebM) when the active
+ * helper is Playwright, or raw CDP `Page.startScreencast` (APNG, assembled in-process) when the
+ * active helper is `CDPBrowser` or a subclass (`Obscura`, `Kitesurf`, ...). Which path is used is
+ * detected automatically per test run; nothing in the config changes between them.
  *
- * When `captions` is enabled, action annotations are burned into the video;
- * when `subtitles` is enabled, a standalone `.srt` is also produced. Default
- * `on=fail` keeps videos for failed tests only; `on=test` keeps every test's
- * video.
+ * When `captions` is enabled, action annotations are burned into the video — Playwright only,
+ * via `page.screencast.showActions()`/`showChapter()`; silently absent on the CDP path, since CDP
+ * screencast frames are raw, uncomposited page captures with no overlay mechanism. `subtitles`
+ * (a standalone `.srt`) works identically on both paths, since it's driven by step events, not by
+ * the video API. Default `on=fail` keeps videos for failed tests only; `on=test` keeps every
+ * test's video.
  *
- * Note: enabling Playwright's helper-level `video: true` together with this
- * plugin produces two independent recordings (`output/videos/*.webm` from the
- * helper, `output/screencast/*.webm` from this plugin).
+ * Note: enabling Playwright's helper-level `video: true` together with this plugin produces two
+ * independent recordings (`output/videos/*.webm` from the helper, `output/screencast/*.webm` from
+ * this plugin).
  *
  * #### Configuration
  *
@@ -49,11 +54,11 @@ const defaultConfig = {
  *
  * Other config options:
  *
- * * `captions`: burn-in action overlays via `page.screencast.showActions()`. Default: true.
+ * * `captions`: burn-in action overlays via `page.screencast.showActions()`. Playwright only. Default: true.
  * * `subtitles`: also write a standalone `.srt` file alongside the video. Default: false.
  * * `video`: record a video. With `video=false, subtitles=true`, only the `.srt` is produced. Default: true.
- * * `size`: pass-through `{ width, height }` for `screencast.start`.
- * * `quality`: pass-through 0–100 for `screencast.start`.
+ * * `size`: pass-through `{ width, height }` — `screencast.start`'s `size` on Playwright, `maxWidth`/`maxHeight` on the CDP path.
+ * * `quality`: pass-through 0–100 for `screencast.start` (Playwright) or CDP `Page.startScreencast` (CDPBrowser family).
  *
  * CLI examples:
  *
@@ -64,7 +69,7 @@ const defaultConfig = {
  * ```
  */
 export default function (config = {}) {
-  const helper = getBrowserHelper()
+  const helper = getScreencastHelper()
   if (!helper) return
 
   const cliArgs = parsePluginArgs(config._args)
@@ -86,7 +91,9 @@ function wireScreencast(mode, options) {
   const state = {
     test: null,
     webmPath: null,
+    apngPath: null,
     srtPath: null,
+    kind: null,
     steps: null,
     startedAt: null,
     failed: false,
@@ -99,7 +106,9 @@ function wireScreencast(mode, options) {
     state.test = test
     state.failed = false
     state.webmPath = null
+    state.apngPath = null
     state.srtPath = null
+    state.kind = null
     state.startQueued = false
     state.started = false
     state.steps = options.subtitles ? {} : null
@@ -141,7 +150,9 @@ function wireScreencast(mode, options) {
     recorder.add('screencast:stop', async () => finalizeScreencast({
       test: state.test,
       webmPath: state.webmPath,
+      apngPath: state.apngPath,
       srtPath: state.srtPath,
+      kind: state.kind,
       steps: state.steps,
       failed: state.failed,
       started: state.started,
@@ -152,15 +163,25 @@ function wireScreencast(mode, options) {
 }
 
 async function startScreencast(test, options, state) {
-  const helper = getBrowserHelper()
-  if (!helper?.page?.screencast) {
-    if (!state.warnedNoApi) {
-      output.plugin('screencast', 'page.screencast not available — requires Playwright >= 1.59. Skipping.')
-      state.warnedNoApi = true
-    }
-    return
+  const helper = getScreencastHelper()
+
+  if (helper?.page?.screencast) {
+    state.kind = 'playwright'
+    return startPlaywrightScreencast(helper, test, options, state)
   }
 
+  if (typeof helper?.startScreencast === 'function') {
+    state.kind = 'cdp'
+    return startCdpScreencast(helper, test, options, state)
+  }
+
+  if (!state.warnedNoApi) {
+    output.plugin('screencast', 'No screencast API available on the active helper — requires Playwright >= 1.59, or a CDPBrowser-family helper (CDPBrowser/Obscura/Kitesurf). Skipping.')
+    state.warnedNoApi = true
+  }
+}
+
+async function startPlaywrightScreencast(helper, test, options, state) {
   const baseDir = path.join(store.outputDir || '_output', 'screencast')
   mkdirp.sync(baseDir)
   const baseName = testToFileName(test, { suffix: '', unique: true })
@@ -192,12 +213,42 @@ async function startScreencast(test, options, state) {
   }
 }
 
+async function startCdpScreencast(helper, test, options, state) {
+  const baseDir = path.join(store.outputDir || '_output', 'screencast')
+  mkdirp.sync(baseDir)
+  const baseName = testToFileName(test, { suffix: '', unique: true })
+  state.apngPath = path.join(baseDir, `${baseName}.apng`)
+  state.srtPath = path.join(baseDir, `${baseName}.srt`)
+
+  const startOpts = {}
+  if (options.size) {
+    startOpts.maxWidth = options.size.width
+    startOpts.maxHeight = options.size.height
+  }
+  if (options.quality != null) startOpts.quality = options.quality
+
+  try {
+    await helper.startScreencast(startOpts)
+    state.started = true
+  } catch (err) {
+    output.plugin('screencast', `Failed to start: ${err.message}`)
+    state.apngPath = null
+    state.srtPath = null
+    state.started = false
+  }
+
+  // captions/chapter burn-in (showActions/showChapter) is Playwright-only — CDP screencast
+  // frames are raw page captures with no overlay mechanism, so this is silently absent here.
+}
+
 async function finalizeScreencast(snapshot) {
-  const { test, options, mode, steps } = snapshot
-  let { webmPath, srtPath } = snapshot
+  const { test, options, mode, steps, kind } = snapshot
+  let { webmPath, apngPath, srtPath } = snapshot
 
-  const helper = getBrowserHelper()
-  if (snapshot.started && helper?.page?.screencast) {
+  const helper = getScreencastHelper()
+  let apngBuffer = null
+
+  if (kind === 'playwright' && snapshot.started && helper?.page?.screencast) {
     try {
       await helper.page.screencast.stop()
     } catch (err) {
@@ -205,6 +256,14 @@ async function finalizeScreencast(snapshot) {
     }
   }
 
+  if (kind === 'cdp' && snapshot.started && typeof helper?.stopScreencast === 'function') {
+    try {
+      apngBuffer = await helper.stopScreencast()
+    } catch (err) {
+      output.plugin('screencast', `stop failed: ${err.message}`)
+    }
+  }
+
   const shouldKeep = mode === 'test' || (mode === 'fail' && snapshot.failed)
 
   if (options.video && webmPath) {
@@ -218,6 +277,22 @@ async function finalizeScreencast(snapshot) {
     }
   }
 
+  if (options.video && apngPath) {
+    if (!shouldKeep || !apngBuffer) {
+      apngPath = null
+    } else {
+      try {
+        await fs.promises.writeFile(apngPath, apngBuffer)
+        ensureArtifactsObject(test)
+        test.artifacts.screencast = apngPath
+        attachJUnitArtifact(test, apngPath)
+      } catch (err) {
+        output.plugin('screencast', `failed to write APNG: ${err.message}`)
+        apngPath = null
+      }
+    }
+  }
+
   if (options.subtitles && steps) {
     if (options.video && !shouldKeep) {
       try { srtPath && fs.unlinkSync(srtPath) } catch { /* nothing to delete */ }
@@ -275,8 +350,25 @@ function buildSrt(steps) {
   return out
 }
 
+// `getBrowserHelper` (from `pluginParser.js`) only recognizes `Container.STANDARD_ACTING_HELPERS`
+// (`Playwright`/`WebDriver`/`Puppeteer`/`Appium`), so it never finds `CDPBrowser`/`Obscura`/
+// `Kitesurf`. Rather than widen that shared list — used by several other plugins with their own,
+// Playwright/WebDriver-specific assumptions — this plugin does its own duck-typed fallback lookup,
+// scoped to itself: any active helper exposing a `startScreencast` function qualifies, with no
+// hardcoded class names, so any future CDP-family helper picks this up automatically too.
+function getScreencastHelper() {
+  const standard = getBrowserHelper()
+  if (standard) return standard
+  const helpers = Container.helpers()
+  for (const name of Object.keys(helpers)) {
+    if (typeof helpers[name]?.startScreencast === 'function') return helpers[name]
+  }
+  return null
+}
+
 function ensureArtifactsObject(test) {
-  if (!test.artifacts || Array.isArray(test.artifacts)) test.artifacts = {}
+  if (!test.artifacts) test.artifacts = {}
+  else if (Array.isArray(test.artifacts)) test.artifacts = Object.assign({}, test.artifacts)
 }
 
 function attachJUnitArtifact(test, filePath) {

package/lib/step/base.js

@@ -1,4 +1,5 @@
 import color from 'chalk'
+import { pathToFileURL } from 'url'
 import Secret from '../secret.js'
 import { getCurrentTimeout } from '../timeout.js'
 import { ucfirst, humanizeString, serializeError } from '../utils.js'
@@ -149,8 +150,6 @@ class Step {
     const lines = this.stack.split('\n')
     if (lines[STACK_LINE]) {
       let line = lines[STACK_LINE].trim()
-        .replace(store.codeceptDir || '', '.')
-        .trim()
 
       // Map .temp.mjs back to original .ts files using container's tsFileMapping
       const fileMapping = store.tsFileMapping
@@ -160,10 +159,23 @@ class Step {
             line = line.replace(mjsFile, tsFile)
             break
           }
+
+          const mjsFileUrl = pathToFileURL(mjsFile).href
+          if (line.includes(mjsFileUrl)) {
+            line = line.replace(mjsFileUrl, pathToFileURL(tsFile).href)
+            break
+          }
         }
       }
 
-      return line
+      const codeceptDir = store.codeceptDir || ''
+      if (codeceptDir) {
+        line = line
+          .replace(pathToFileURL(codeceptDir).href, '.')
+          .replace(codeceptDir, '.')
+      }
+
+      return line.trim()
     }
     return ''
   }

package/lib/step/config.js

@@ -4,6 +4,7 @@
  * @property {boolean} [exact] - Enable strict mode for this step. Throws if multiple elements match.
  * @property {boolean} [strictMode] - Alias for exact.
  * @property {boolean} [ignoreCase] - Perform case-insensitive text matching.
+ * @property {boolean} [visibleLocator] - Match only visible elements. Overrides the Playwright helper `visibleLocator` config option for this step.
  */
 
 /**

package/lib/store.js

@@ -93,6 +93,12 @@ const store = {
   /** @type {CodeceptJS.Suite | null} */
   currentSuite: null,
 
+  /**
+   * Locators match only visible elements, resolved per step
+   * @type {boolean}
+   */
+  visibleLocator: false,
+
   /** @type {Map<string, string> | null} */
   tsFileMapping: null,
 

package/lib/utils/loaderCheck.js

@@ -6,10 +6,16 @@
  * Check if a TypeScript loader is available for test files
  * Note: This checks if loaders are in the require array, not if packages are installed
  * Package installation is checked when actually requiring modules
+ * Always true under Bun, which transpiles TypeScript itself
  * @param {string[]} requiredModules - Array of required modules from config
  * @returns {boolean}
  */
 export function checkTypeScriptLoader(requiredModules = []) {
+  // Bun transpiles TypeScript natively, so no loader is needed.
+  // Node is not treated the same way: its native type stripping rejects enums
+  // and does not resolve extensionless relative imports.
+  if (process.versions.bun) return true
+
   // Check if a loader is configured in the require array
   return (
     requiredModules.includes('tsx/esm') ||

package/lib/utils.js

@@ -108,7 +108,7 @@ export const methodsOfObject = function (obj, className) {
 export const template = function (template, data) {
   return template.replace(/{{([^{}]*)}}/g, (a, b) => {
     const r = data[b]
-    if (r === undefined) return ''
+    if (r === undefined || r === null) return ''
     return r.toString()
   })
 }

package/lib/workers.js

@@ -508,10 +508,27 @@ class Workers extends EventEmitter {
     // Create workers and set up message handlers immediately (not in recorder queue)
     // This prevents a race condition where workers start sending messages before handlers are attached
     const workerThreads = []
+    const staggerDelay = this.codecept.config.workerInitializationDelay !== undefined 
+      ? this.codecept.config.workerInitializationDelay 
+      : 200
+
+    // Maximum total stagger window (default 10 seconds). Allows capping total delay regardless of worker count.
+    const maxStagger = this.codecept.config.workerInitializationMaxDelay ?? 10000
+    // Compute effective per-worker delay to keep total stagger within maxStagger.
+    const effectiveDelay = staggerDelay > 0
+      ? Math.min(staggerDelay, Math.floor(maxStagger / Math.max(1, this.workers.length - 1)))
+      : 0
+
     for (const worker of this.workers) {
       const workerThread = createWorker(worker, this.isPoolMode)
       this._listenWorkerEvents(workerThread)
       workerThreads.push(workerThread)
+      
+      // Stagger worker creation to prevent CPU spikes 
+      // from massive V8 isolate creation and naturally stagger browser init
+      if (this.workers.length > 1 && effectiveDelay > 0) {
+        await new Promise(resolve => setTimeout(resolve, effectiveDelay))
+      }
     }
 
     recorder.add('workers started', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.1.0",
+  "version": "4.2.0-beta.2",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -78,6 +78,8 @@
     "test:unit:webbapi:puppeteer": "mocha test/helper/Puppeteer_test.js --reporter @testomatio/reporter/mocha",
     "test:unit:webbapi:webDriver": "mocha test/helper/WebDriver_test.js --timeout 10000 --reporter @testomatio/reporter/mocha",
     "test:unit:webbapi:webDriver:noSeleniumServer": "mocha test/helper/WebDriver.noSeleniumServer_test.js --timeout 10000 --reporter @testomatio/reporter/mocha",
+    "test:unit:webbapi:cdpbrowser": "mocha test/helper/CDPBrowser_chrome_test.js --timeout 30000 --reporter @testomatio/reporter/mocha",
+    "test:unit:webbapi:obscura": "mocha test/helper/CDPBrowser_obscura_test.js --timeout 30000 --reporter @testomatio/reporter/mocha",
     "test:unit:expect": "mocha test/helper/Expect_test.js --reporter @testomatio/reporter/mocha",
     "test:plugin": "mocha test/plugin/plugin_test.js --reporter @testomatio/reporter/mocha",
     "def": "./runok.cjs def",
@@ -134,6 +136,7 @@
     "promise-retry": "1.1.1",
     "sprintf-js": "1.1.3",
     "uuid": "11.1.0",
+    "ws": "^8.21.2",
     "xpath": "0.0.34",
     "zod": "^4.1.11"
   },
@@ -174,7 +177,7 @@
     "jsdoc": "^3.6.11",
     "jsdoc-typeof-plugin": "1.0.0",
     "json-server": "0.17.4",
-    "playwright": "^1.59.0",
+    "playwright": "^1.63.0",
     "prettier": "^3.3.2",
     "puppeteer": "24.36.0",
     "qrcode-terminal": "0.12.0",