codeceptjs 4.0.2-beta.9 → 4.0.2

package/lib/plugin/pageInfo.js

@@ -1,13 +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'],
@@ -36,67 +38,66 @@ 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
-
   event.dispatcher.on(event.test.failed, test => {
+    const helper = pickActingHelper(Container.helpers())
+    if (!helper) return
+
     const pageState = {}
 
-    recorder.add('URL of failed test', async () => {
+    recorder.add('pageInfo capture', async () => {
       try {
-        const url = await helper.grabCurrentUrl()
-        pageState.url = url
-      } catch (err) {
-        // not really needed
-      }
-    })
-    recorder.add('HTML snapshot failed test', 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
+          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 {}
+    }, true)
 
     recorder.add('Save page info', () => {
       test.addNote('pageInfo', pageStateToMarkdown(pageState))
 
-      const pageStateFileName = path.join(global.output_dir, `${testToFileName(test)}.pageInfo.md`)
+      const pageStateFileName = path.join(store.outputDir, `${testToFileName(test)}.pageInfo.md`)
       fs.writeFileSync(pageStateFileName, pageStateToMarkdown(pageState))
       test.artifacts.pageInfo = pageStateFileName
       return pageState
-    })
+    }, true)
   })
 }
 
@@ -126,15 +127,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,17 @@
-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
- * ```
+ * Starts an interactive pause when a test fails.
  *
+ * **Deprecated:** use the `pause` plugin with `on: 'fail'`, which is the default behavior.
  */
-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/retryFailedStep.js

@@ -1,14 +1,27 @@
+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*'],
+  minTimeout: 150,
+  maxTimeout: 10000,
   factor: 1.5,
+  randomize: false,
   ignoredSteps: [],
+  deferToScenarioRetries: true,
+}
+
+const RETRY_PRIORITIES = {
+  MANUAL_STEP: 100,
+  STEP_PLUGIN: 50,
+  SCENARIO_CONFIG: 30,
+  FEATURE_CONFIG: 20,
+  HOOK_CONFIG: 10,
 }
 
 /**
@@ -34,10 +47,9 @@ const defaultConfig = {
  * #### Configuration:
  *
  * * `retries` - number of retries (by default 3),
- * * `when` - function, when to perform a retry (accepts error as parameter)
  * * `factor` - The exponential factor to use. Default is 1.5.
- * * `minTimeout` - The number of milliseconds before starting the first retry. Default is 1000.
- * * `maxTimeout` - The maximum number of milliseconds between two retries. Default is Infinity.
+ * * `minTimeout` - The number of milliseconds before starting the first retry. Default is 150.
+ * * `maxTimeout` - The maximum number of milliseconds between two retries. Default is 10000.
  * * `randomize` - Randomizes the timeouts by multiplying with a factor from 1 to 2. Default is false.
  * * `defaultIgnoredSteps` - an array of steps to be ignored for retry. Includes:
  *     * `amOnPage`
@@ -49,6 +61,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
  *
@@ -66,7 +79,7 @@ const defaultConfig = {
  *
  * #### Disable Per Test
  *
- * This plugin can be disabled per test. In this case you will need to stet `I.retry()` to all flaky steps:
+ * This plugin can be disabled per test. In this case you will need to add `step.retry()` to all flaky steps:
  *
  * Use scenario configuration to disable plugin for a test
  *
@@ -78,9 +91,8 @@ const defaultConfig = {
  *
  */
 export default function (config) {
-  config = Object.assign(defaultConfig, config)
+  config = Object.assign({}, defaultConfig, config)
   config.ignoredSteps = config.ignoredSteps.concat(config.defaultIgnoredSteps)
-  const customWhen = config.when
 
   let enableRetry = false
 
@@ -88,73 +100,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
+    if (!step.title) return
     for (const ignored of config.ignoredSteps) {
-      if (step.name === ignored) return
+      if (step.title === ignored) return
       if (ignored instanceof RegExp) {
-        if (step.name.match(ignored)) return
-      } else if (ignored.indexOf('*') && step.name.startsWith(ignored.slice(0, -1))) return
+        if (step.title.match(ignored)) return
+      } else if (ignored.indexOf('*') !== -1 && step.title.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