codeceptjs 4.0.0-rc.2 → 4.0.0-rc.21

package/lib/plugin/retryFailedStep.js

@@ -1,14 +1,24 @@
+import debugModule from 'debug'
 import event from '../event.js'
-
 import recorder from '../recorder.js'
-
 import store from '../store.js'
 
+const debug = debugModule('codeceptjs:retryFailedStep')
+
 const defaultConfig = {
   retries: 3,
   defaultIgnoredSteps: ['amOnPage', 'wait*', 'send*', 'execute*', 'run*', 'have*'],
   factor: 1.5,
   ignoredSteps: [],
+  deferToScenarioRetries: true,
+}
+
+const RETRY_PRIORITIES = {
+  MANUAL_STEP: 100,
+  STEP_PLUGIN: 50,
+  SCENARIO_CONFIG: 30,
+  FEATURE_CONFIG: 20,
+  HOOK_CONFIG: 10,
 }
 
 /**
@@ -49,6 +59,7 @@ const defaultConfig = {
  * * `ignoredSteps` - an array for custom steps to ignore on retry. Use it to append custom steps to ignored list.
  * You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
  * To append your own steps to ignore list - copy and paste a default steps list. Regexp values are accepted as well.
+ * * `deferToScenarioRetries` - when enabled (default), step retries are automatically disabled if scenario retries are configured to avoid excessive total retries.
  *
  * #### Example
  *
@@ -88,73 +99,72 @@ export default function (config) {
     if (!enableRetry) return
     if (store.debugMode) return false
     if (!store.autoRetries) return false
-    // Don't retry terminal errors (e.g., frame detachment errors)
     if (err && err.isTerminal) return false
-    // Don't retry navigation errors that are known to be terminal
     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
     if (customWhen) return customWhen(err)
     return true
   }
   config.when = when
 
-  // Ensure retry options are available before any steps run
   if (!recorder.retries.find(r => r === config)) {
     recorder.retries.push(config)
   }
 
   event.dispatcher.on(event.step.started, step => {
-    // if a step is ignored - return
     for (const ignored of config.ignoredSteps) {
       if (step.name === ignored) return
       if (ignored instanceof RegExp) {
         if (step.name.match(ignored)) return
       } else if (ignored.indexOf('*') && step.name.startsWith(ignored.slice(0, -1))) return
     }
-    enableRetry = true // enable retry for a step
+    enableRetry = true
   })
 
-  // Disable retry only after a successful step; keep it enabled for failure so retry logic can act
   event.dispatcher.on(event.step.passed, () => {
     enableRetry = false
   })
 
   event.dispatcher.on(event.test.before, test => {
-    // pass disableRetryFailedStep is a preferred way to disable retries
-    // test.disableRetryFailedStep is used for backward compatibility
     if (!test.opts) test.opts = {}
     if (test.opts.disableRetryFailedStep || test.disableRetryFailedStep) {
       store.autoRetries = false
-      return // disable retry when a test is not active
+      return
+    }
+
+    const scenarioRetries = typeof test.retries === 'function' ? test.retries() : -1
+    const stepRetryPriority = RETRY_PRIORITIES.STEP_PLUGIN
+    const scenarioPriority = test.opts.retryPriority || 0
+
+    if (scenarioRetries > 0 && config.deferToScenarioRetries !== false) {
+      store.autoRetries = false
+      return
     }
 
-    // Don't apply plugin retry logic if there are already manual retries configured
-    // Check if any retry configs exist that aren't from this plugin
     const hasManualRetries = recorder.retries.some(retry => retry !== config)
     if (hasManualRetries) {
       store.autoRetries = false
       return
     }
 
-    // this option is used to set the retries inside _before() block of helpers
     store.autoRetries = true
     test.opts.conditionalRetries = config.retries
-    // debug: record applied retries value for tests
-    if (process.env.DEBUG_RETRY_PLUGIN) {
-      // eslint-disable-next-line no-console
-      console.log('[retryFailedStep] applying retries =', config.retries, 'for test', test.title)
-    }
+    test.opts.stepRetryPriority = stepRetryPriority
+
+    debug('applying retries = %d for test %s', config.retries, test.title)
     recorder.retry(config)
   })
 
-  // Fallback for environments where event.test.before wasn't emitted (runner scenarios)
   event.dispatcher.on(event.test.started, test => {
     if (test.opts?.disableRetryFailedStep || test.disableRetryFailedStep) return
 
-    // Don't apply plugin retry logic if there are already manual retries configured
-    // Check if any retry configs exist that aren't from this plugin
     const hasManualRetries = recorder.retries.some(retry => retry !== config)
     if (hasManualRetries) return
 
+    const scenarioRetries = typeof test.retries === 'function' ? test.retries() : -1
+    if (scenarioRetries > 0 && config.deferToScenarioRetries !== false) {
+      return
+    }
+
     if (!store.autoRetries) {
       store.autoRetries = true
       test.opts.conditionalRetries = test.opts.conditionalRetries || config.retries

package/lib/plugin/screencast.js

@@ -0,0 +1,289 @@
+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.test.started, test => {
+    if (!options.video || state.startQueued) return
+    state.startQueued = true
+    recorder.add('screencast:start', async () => startScreencast(state.test, options, state), true)
+  })
+
+  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.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)
+  }
+}