codeceptjs 4.0.0-rc.16 → 4.0.0-rc.18

package/lib/plugin/heal.js

@@ -10,21 +10,30 @@ import output from '../output.js'
 import healModule from '../heal.js'
 const heal = healModule.default || healModule
 import store from '../store.js'
+import {
+  parsePluginArgs,
+  resolveTrigger,
+  matchStepFile,
+  matchUrl,
+  getBrowserHelper,
+} from '../utils/pluginParser.js'
 
 
 const defaultConfig = {
+  on: 'fail',
   healLimit: 2,
 }
 
 /**
  * Self-healing tests with AI.
  *
- * Read more about heaking in [Self-Healing Tests](https://codecept.io/heal/)
+ * Read more about healing in [Self-Healing Tests](https://codecept.io/heal/)
  *
  * ```js
  * plugins: {
  *   heal: {
  *    enabled: true,
+ *    on: 'fail',
  *   }
  * }
  * ```
@@ -32,7 +41,17 @@ const defaultConfig = {
  * More config options are available:
  *
  * * `healLimit` - how many steps can be healed in a single test (default: 2)
+ * * `on` - trigger mode. `fail` (default), `file` (filter to a path), `url` (filter to a URL pattern).
  *
+ * #### `on=` modes
+ *
+ * Heal always runs on step failures; `on=` narrows when it engages.
+ *
+ * * **fail** — heal any failing step (default)
+ * * **file** — heal only failures in `path=...[;line=...]`
+ * * **url** — heal only failures when the current URL matches `pattern=...`
+ *
+ * `on=step` and `on=test` are not supported and are rejected with an error.
  */
 export default function (config = {}) {
   if (store.debugMode && !process.env.DEBUG) {
@@ -42,6 +61,13 @@ export default function (config = {}) {
     return
   }
 
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: defaultConfig.on }, {
+    name: 'heal',
+    validModes: ['fail', 'file', 'url'],
+  })
+  if (!trigger) return
+
   let currentTest = null
   let currentStep = null
   let healedSteps = 0
@@ -65,6 +91,8 @@ export default function (config = {}) {
 
     if (!heal.hasCorrespondingRecipes(step)) return
 
+    if (trigger.on === 'file' && !matchStepFile(step, trigger.path, trigger.line)) return
+
     recorder.catchWithoutStop(async err => {
       isHealing = true
       if (caughtError === err) throw err // avoid double handling
@@ -72,6 +100,21 @@ export default function (config = {}) {
 
       const test = currentTest
 
+      if (trigger.on === 'url') {
+        try {
+          const helper = getBrowserHelper()
+          const url = helper && helper.grabCurrentUrl ? await helper.grabCurrentUrl() : null
+          if (!matchUrl(url, trigger.pattern)) {
+            isHealing = false
+            throw err
+          }
+        } catch (e) {
+          if (e === err) throw e
+          isHealing = false
+          throw err
+        }
+      }
+
       recorder.session.start('heal')
 
       debug('Self-healing started', step.toCode())

package/lib/plugin/pageInfo.js

@@ -1,14 +1,15 @@
 import path from 'path'
 import fs from 'fs'
 import Container from '../container.js'
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
 import recorder from '../recorder.js'
 import event from '../event.js'
 import { scanForErrorMessages } from '../html.js'
+import { captureSnapshot, pickActingHelper } from '../utils/trace.js'
 import { output } from '../index.js'
 import store from '../store.js'
 import { humanizeString, ucfirst } from '../utils.js'
 import { testToFileName } from '../mocha/test.js'
+
 const defaultConfig = {
   errorClasses: ['error', 'warning', 'alert', 'danger'],
   browserLogs: ['error'],
@@ -37,57 +38,58 @@ const defaultConfig = {
  *
  */
 export default function (config = {}) {
-  const helpers = Container.helpers()
-  let helper
-
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
-
-  if (!helper) return // no helpers for screenshot
+  const helper = pickActingHelper(Container.helpers())
+  if (!helper) return
 
   event.dispatcher.on(event.test.failed, test => {
     const pageState = {}
 
-    recorder.add('URL of failed test', async () => {
-      try {
-        const url = await helper.grabCurrentUrl()
-        pageState.url = url
-      } catch (err) {
-        // not really needed
-      }
-    })
-    recorder.add('HTML snapshot failed test', async () => {
+    recorder.add('pageInfo capture', async () => {
       try {
-        const html = await helper.grabHTMLFrom('body')
-
-        if (!html) return
-
-        const errors = scanForErrorMessages(html, config.errorClasses)
-        if (errors.length) {
-          output.debug('Detected errors in HTML code')
-          errors.forEach(error => output.debug(error))
-          pageState.htmlErrors = errors
+        const prefix = `${testToFileName(test)}.pageInfo`
+        const captured = await captureSnapshot(helper, {
+          dir: store.outputDir,
+          prefix,
+          captureScreenshot: false,
+        })
+
+        if (captured.url) pageState.url = captured.url
+
+        if (captured.html) {
+          const htmlPath = path.join(store.outputDir, captured.html)
+          pageState.htmlSnapshot = htmlPath
+          // Scan raw HTML (pre-cleanHtml) so error classes containing digits
+          // or trash-class prefixes aren't stripped before detection.
+          const htmlForScan = captured.htmlRaw || (() => {
+            try { return fs.readFileSync(htmlPath, 'utf8') } catch { return '' }
+          })()
+          if (htmlForScan) {
+            try {
+              const errors = scanForErrorMessages(htmlForScan, config.errorClasses)
+              if (errors.length) {
+                output.debug('Detected errors in HTML code')
+                errors.forEach(error => output.debug(error))
+                pageState.htmlErrors = errors
+              }
+            } catch {}
+          }
         }
-      } catch (err) {
-        // not really needed
-      }
-    })
-
-    recorder.add('Browser logs for failed test', async () => {
-      try {
-        const logs = await helper.grabBrowserLogs()
 
-        if (!logs) return
+        if (captured.aria) {
+          pageState.ariaSnapshot = path.join(store.outputDir, captured.aria)
+        }
 
-        pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
-      } catch (err) {
-        // not really needed
-      }
+        if (captured.console) {
+          const consolePath = path.join(store.outputDir, captured.console)
+          pageState.consoleSnapshot = consolePath
+          try {
+            const logs = JSON.parse(fs.readFileSync(consolePath, 'utf8'))
+            pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
+          } catch {}
+        }
+      } catch {}
     })
 
     recorder.add('Save page info', () => {
@@ -127,15 +129,16 @@ function pageStateToMarkdown(pageState) {
 }
 
 function getBrowserErrors(logs, type = ['error']) {
-  // Playwright & WebDriver console messages
-  let errors = logs
+  // Accepts Playwright ConsoleMessage objects, normalized {type, text}, or strings
+  return logs
     .map(log => {
       if (typeof log === 'string') return log
-      if (!log.type) return null
-      return { type: log.type(), text: log.text() }
+      if (!log) return null
+      const t = typeof log.type === 'function' ? log.type() : log.type
+      const text = typeof log.text === 'function' ? log.text() : log.text
+      if (!t) return null
+      return { type: t, text }
     })
     .filter(l => l && (typeof l === 'string' || type.includes(l.type)))
     .map(l => (typeof l === 'string' ? l : l.text))
-
-  return errors
 }

package/lib/plugin/pause.js

@@ -0,0 +1,131 @@
+import event from '../event.js'
+import pause from '../pause.js'
+import recorder from '../recorder.js'
+import output from '../output.js'
+import {
+  parsePluginArgs,
+  resolveTrigger,
+  matchStepFile,
+  matchUrl,
+  getBrowserHelper,
+} from '../utils/pluginParser.js'
+
+/**
+ * Pauses test execution interactively. Replaces the legacy `pauseOnFail`
+ * plugin. The default `on=fail` matches the old `pauseOnFail` behavior.
+ *
+ * #### Configuration
+ *
+ * ```js
+ * plugins: {
+ *   pause: {
+ *     enabled: false,
+ *     on: 'fail',
+ *   }
+ * }
+ * ```
+ *
+ * #### `on=` modes
+ *
+ * * **fail** — pause when a step fails (default)
+ * * **test** — pause after each test
+ * * **step** — pause before the first step (interactive walk-through)
+ * * **file** — pause when execution reaches `path=...[;line=...]`
+ * * **url** — pause when the browser URL matches `pattern=...`
+ *
+ * CLI examples:
+ *
+ * ```
+ * npx codeceptjs run -p pause
+ * npx codeceptjs run -p pause:on=step
+ * npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
+ * npx codeceptjs run -p pause:on=url:pattern=/users/*
+ * ```
+ */
+export default function (config = {}) {
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: 'fail' }, { name: 'pause' })
+  if (!trigger) return
+
+  switch (trigger.on) {
+    case 'fail':
+      return initFailMode()
+    case 'test':
+      return initTestMode()
+    case 'step':
+      return initStepMode()
+    case 'file':
+      return initFileMode(trigger.path, trigger.line)
+    case 'url':
+      return initUrlMode(trigger.pattern)
+  }
+}
+
+function initFailMode() {
+  let failed = false
+
+  event.dispatcher.on(event.test.started, () => {
+    failed = false
+  })
+
+  event.dispatcher.on(event.step.failed, () => {
+    failed = true
+  })
+
+  event.dispatcher.on(event.test.after, () => {
+    if (failed) pause()
+  })
+}
+
+function initTestMode() {
+  event.dispatcher.on(event.test.after, () => pause())
+}
+
+function initStepMode() {
+  let activated = false
+
+  event.dispatcher.on(event.test.before, () => {
+    if (activated) return
+    activated = true
+    recorder.add('pause:step', () => pause())
+  })
+}
+
+function initFileMode(targetPath, targetLine) {
+  let paused = false
+
+  event.dispatcher.on(event.step.before, step => {
+    if (paused) return
+    if (!matchStepFile(step, targetPath, targetLine)) return
+    paused = true
+    recorder.add('pause:file', () => pause())
+  })
+}
+
+function initUrlMode(pattern) {
+  const helper = getBrowserHelper()
+
+  if (!helper) {
+    output.error('pause:on=url requires a browser helper (Playwright, WebDriver, Puppeteer, Appium)')
+    return
+  }
+
+  let paused = false
+
+  event.dispatcher.on(event.step.after, () => {
+    if (paused) return
+
+    recorder.add('pause:url check', async () => {
+      if (paused) return
+      try {
+        const currentUrl = await helper.grabCurrentUrl()
+        if (matchUrl(currentUrl, pattern)) {
+          paused = true
+          return pause()
+        }
+      } catch (err) {
+        // page may not be loaded yet
+      }
+    })
+  })
+}

package/lib/plugin/pauseOnFail.js

@@ -1,39 +1,15 @@
-import event from '../event.js'
+import output from '../output.js'
+import pause from './pause.js'
 
-import pause from '../pause.js'
+let warned = false
 
 /**
- * Automatically launches [interactive pause](/basics/#pause) when a test fails.
- *
- * Useful for debugging flaky tests on local environment.
- * Add this plugin to config file:
- *
- * ```js
- * plugins: {
- *   pauseOnFail: {},
- * }
- * ```
- *
- * Unlike other plugins, `pauseOnFail` is not recommended to be enabled by default.
- * Enable it manually on each run via `-p` option:
- *
- * ```
- * npx codeceptjs run -p pauseOnFail
- * ```
- *
+ * @deprecated Use the `pause` plugin with `on: 'fail'` (the default).
  */
-export default function() {
-  let failed = false
-
-  event.dispatcher.on(event.test.started, () => {
-    failed = false
-  })
-
-  event.dispatcher.on(event.step.failed, () => {
-    failed = true
-  })
-
-  event.dispatcher.on(event.test.after, () => {
-    if (failed) pause()
-  })
+export default function (config = {}) {
+  if (!warned) {
+    output.error('pauseOnFail is deprecated; use the `pause` plugin (default on=fail).')
+    warned = true
+  }
+  return pause({ ...config, on: 'fail' })
 }

package/lib/plugin/screencast.js

@@ -0,0 +1,287 @@
+import fs from 'fs'
+import path from 'path'
+import { mkdirp } from 'mkdirp'
+import { v4 as uuidv4 } from 'uuid'
+
+import Container from '../container.js'
+import recorder from '../recorder.js'
+import event from '../event.js'
+import output from '../output.js'
+import store from '../store.js'
+
+import { testToFileName } from '../mocha/test.js'
+import { parsePluginArgs, resolveTrigger, getBrowserHelper } from '../utils/pluginParser.js'
+
+const defaultConfig = {
+  on: 'fail',
+  captions: true,
+  subtitles: false,
+  video: true,
+}
+
+/**
+ * Records WebM video of tests using Playwright's screencast API.
+ *
+ * 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.
+ *
+ * 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
+ *
+ * ```js
+ * plugins: {
+ *   screencast: {
+ *     enabled: true,
+ *     on: 'fail',
+ *   }
+ * }
+ * ```
+ *
+ * #### `on=` modes
+ *
+ * * **fail** — record while running; delete on pass, keep on fail (default)
+ * * **test** — record and keep every test's video
+ *
+ * Other config options:
+ *
+ * * `captions`: burn-in action overlays via `page.screencast.showActions()`. 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`.
+ *
+ * CLI examples:
+ *
+ * ```
+ * npx codeceptjs run -p screencast
+ * npx codeceptjs run -p screencast:on=test
+ * npx codeceptjs run -p screencast:on=test;captions=false;subtitles=true
+ * ```
+ */
+export default function (config = {}) {
+  const helper = getBrowserHelper()
+  if (!helper) return
+
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: defaultConfig.on }, {
+    name: 'screencast',
+    validModes: ['fail', 'test'],
+  })
+  if (!trigger) return
+
+  const options = Object.assign({}, defaultConfig, config)
+  options.captions = cliArgs.captions ?? config.captions ?? defaultConfig.captions
+  options.subtitles = cliArgs.subtitles ?? config.subtitles ?? defaultConfig.subtitles
+  options.video = cliArgs.video ?? config.video ?? defaultConfig.video
+
+  return wireScreencast(trigger.on, options)
+}
+
+function wireScreencast(mode, options) {
+  const state = {
+    test: null,
+    webmPath: null,
+    srtPath: null,
+    steps: null,
+    startedAt: null,
+    failed: false,
+    startQueued: false,
+    started: false,
+    warnedNoApi: false,
+  }
+
+  event.dispatcher.on(event.test.before, test => {
+    state.test = test
+    state.failed = false
+    state.webmPath = null
+    state.srtPath = null
+    state.startQueued = false
+    state.started = false
+    state.steps = options.subtitles ? {} : null
+    state.startedAt = options.subtitles ? Date.now() : null
+  })
+
+  event.dispatcher.on(event.step.started, step => {
+    if (state.steps) {
+      const at = Date.now()
+      step.id = step.id || uuidv4()
+      state.steps[step.id] = {
+        start: formatTimestamp(at - state.startedAt),
+        startedAt: at,
+        title: stepTitle(step),
+      }
+    }
+    if (!options.video || state.startQueued || !state.test) return
+    state.startQueued = true
+    const test = state.test
+    recorder.add('screencast:start', async () => startScreencast(test, options, state), true)
+  })
+
+  if (options.subtitles) {
+    event.dispatcher.on(event.step.finished, step => {
+      if (!state.steps || !step?.id || !state.steps[step.id]) return
+      state.steps[step.id].end = formatTimestamp(Date.now() - state.startedAt)
+    })
+  }
+
+  event.dispatcher.on(event.test.failed, (test, _err, hookName) => {
+    if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') return
+    state.failed = true
+  })
+
+  event.dispatcher.on(event.test.after, () => {
+    if (!state.test) return
+    recorder.add('screencast:stop', async () => finalizeScreencast({
+      test: state.test,
+      webmPath: state.webmPath,
+      srtPath: state.srtPath,
+      steps: state.steps,
+      failed: state.failed,
+      started: state.started,
+      options,
+      mode,
+    }), true)
+  })
+}
+
+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 baseDir = path.join(store.outputDir || '_output', 'screencast')
+  mkdirp.sync(baseDir)
+  const baseName = testToFileName(test, { suffix: '', unique: true })
+  state.webmPath = path.join(baseDir, `${baseName}.webm`)
+  state.srtPath = path.join(baseDir, `${baseName}.srt`)
+
+  const startOpts = { path: state.webmPath }
+  if (options.size) startOpts.size = options.size
+  if (options.quality != null) startOpts.quality = options.quality
+
+  try {
+    await helper.page.screencast.start(startOpts)
+    state.started = true
+  } catch (err) {
+    output.plugin('screencast', `Failed to start: ${err.message}`)
+    state.webmPath = null
+    state.srtPath = null
+    state.started = false
+    return
+  }
+
+  if (options.captions && typeof helper.page.screencast.showActions === 'function') {
+    try { await helper.page.screencast.showActions() }
+    catch (err) { output.plugin('screencast', `showActions failed: ${err.message}`) }
+  }
+  if (typeof helper.page.screencast.showChapter === 'function') {
+    try { await helper.page.screencast.showChapter(String(test.title || '')) }
+    catch (err) { output.plugin('screencast', `showChapter failed: ${err.message}`) }
+  }
+}
+
+async function finalizeScreencast(snapshot) {
+  const { test, options, mode, steps } = snapshot
+  let { webmPath, srtPath } = snapshot
+
+  const helper = getBrowserHelper()
+  if (snapshot.started && helper?.page?.screencast) {
+    try {
+      await helper.page.screencast.stop()
+    } catch (err) {
+      output.plugin('screencast', `stop failed: ${err.message}`)
+    }
+  }
+
+  const shouldKeep = mode === 'test' || (mode === 'fail' && snapshot.failed)
+
+  if (options.video && webmPath) {
+    if (!shouldKeep) {
+      try { fs.unlinkSync(webmPath) } catch { /* file may not exist yet */ }
+      webmPath = null
+    } else {
+      ensureArtifactsObject(test)
+      test.artifacts.screencast = webmPath
+      attachJUnitArtifact(test, webmPath)
+    }
+  }
+
+  if (options.subtitles && steps) {
+    if (options.video && !shouldKeep) {
+      try { srtPath && fs.unlinkSync(srtPath) } catch { /* nothing to delete */ }
+      return
+    }
+
+    let target = srtPath
+    if (!options.video) {
+      if (test.artifacts && test.artifacts.video) {
+        const { dir, name } = path.parse(test.artifacts.video)
+        target = path.join(dir, `${name}.srt`)
+      } else {
+        const baseDir = path.join(store.outputDir || '_output', 'screencast')
+        mkdirp.sync(baseDir)
+        const baseName = testToFileName(test, { suffix: '', unique: true })
+        target = path.join(baseDir, `${baseName}.srt`)
+      }
+    }
+
+    if (!target) return
+    try {
+      await fs.promises.writeFile(target, buildSrt(steps))
+      ensureArtifactsObject(test)
+      test.artifacts.subtitle = target
+    } catch (err) {
+      output.plugin('screencast', `failed to write SRT: ${err.message}`)
+    }
+  }
+}
+
+function formatTimestamp(timestampInMs) {
+  const date = new Date(0, 0, 0, 0, 0, 0, timestampInMs)
+  const hours = date.getHours()
+  const minutes = date.getMinutes()
+  const seconds = date.getSeconds()
+  const ms = timestampInMs - (hours * 3600000 + minutes * 60000 + seconds * 1000)
+  return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')},${ms.toString().padStart(3, '0')}`
+}
+
+function stepTitle(step) {
+  let title = `${step.actor}.${step.name}(${step.args ? step.args.join(',') : ''})`
+  if (title.length > 100) title = `${title.substring(0, 100)}...`
+  return title
+}
+
+function buildSrt(steps) {
+  const sorted = Object.values(steps).sort((a, b) => a.startedAt - b.startedAt)
+  let out = ''
+  let index = 1
+  for (const step of sorted) {
+    if (!step.end) continue
+    out += `${index}\n${step.start} --> ${step.end}\n${step.title}\n\n`
+    index++
+  }
+  return out
+}
+
+function ensureArtifactsObject(test) {
+  if (!test.artifacts || Array.isArray(test.artifacts)) test.artifacts = {}
+}
+
+function attachJUnitArtifact(test, filePath) {
+  const mocha = Container.mocha?.()
+  const junit = mocha?.options?.reporterOptions?.['mocha-junit-reporter']
+  if (junit?.options?.attachments) {
+    test.attachments = test.attachments || []
+    test.attachments.push(filePath)
+  }
+}