codeceptjs 4.0.0-rc.9 → 4.0.0

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
@@ -54,6 +80,7 @@ export default function (config = {}) {
   event.dispatcher.on(event.test.before, test => {
     currentTest = test
     healedSteps = 0
+    healTries = 0
     caughtError = null
   })
 
@@ -65,21 +92,38 @@ export default function (config = {}) {
 
     if (!heal.hasCorrespondingRecipes(step)) return
 
+    if (trigger.on === 'file' && !matchStepFile(step, trigger.path, trigger.line)) return
+
     recorder.catchWithoutStop(async err => {
+      if (healTries >= config.healLimit) throw err
       isHealing = true
+      healTries++
       if (caughtError === err) throw err // avoid double handling
       caughtError = err
 
       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())
 
       await heal.healStep(step, err, { test })
 
-      healTries++
-
       recorder.add('close healing session', () => {
         recorder.reset()
         recorder.session.restore('heal')

package/lib/plugin/junitReporter.js

@@ -0,0 +1,303 @@
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { mkdirp } from 'mkdirp'
+import { DOMImplementation, XMLSerializer } from '@xmldom/xmldom'
+
+import event from '../event.js'
+import store from '../store.js'
+import output from '../output.js'
+
+const defaultConfig = {
+  outputName: 'report.xml',
+  output: null,
+  testGroupName: 'CodeceptJS',
+  attachSteps: true,
+  attachMeta: true,
+  stepsInFailure: true,
+}
+
+const INVALID_XML_CHARS = new RegExp('[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\uFFFE\\uFFFF]', 'g')
+
+/**
+ *
+ * Generates a JUnit-compatible XML report after a test run.
+ *
+ * Unlike Mocha's `mocha-junit-reporter`, this plugin understands CodeceptJS steps and substeps.
+ * For every `<testcase>` it includes:
+ *
+ * * `<properties>` — the test's meta information: every `meta` key from `Scenario('...', { meta })`, plus its `tags` and `retries`
+ * * `<system-out>` — an indented step/substep log (substeps are nested under their meta step); only failed steps are marked
+ * * `<failure>` — for failed tests: the error message, type, stack trace and (optionally) the step trace
+ *
+ * The produced file is consumable by Jenkins, GitLab CI, CircleCI, GitHub Actions test reporters, etc.
+ *
+ * #### Configuration
+ *
+ * ```js
+ * "plugins": {
+ *    "junitReporter": {
+ *      "enabled": true
+ *    }
+ *  }
+ * ```
+ *
+ * Possible config options:
+ *
+ * * `outputName`: file name for the report. Default: `report.xml`.
+ * * `output`: directory where the report is stored, relative to the project root. Default: the `output` directory.
+ * * `testGroupName`: value of the `name` attribute on the root `<testsuites>` element. Default: `CodeceptJS`.
+ * * `attachMeta`: add the test's meta information (`meta` keys, `tags`, `retries`) as `<properties>`. Default: true.
+ * * `attachSteps`: add the step/substep log as `<system-out>`. Default: true.
+ * * `stepsInFailure`: append the step trace to the `<failure>` body. Default: true.
+ *
+ * CLI examples:
+ *
+ * ```
+ * npx codeceptjs run -p junitReporter
+ * npx codeceptjs run -p junitReporter:outputName=junit.xml
+ * ```
+ *
+ * > ℹ When running with `run-workers`, steps are serialized between processes and substep nesting is flattened.
+ *
+ * @param {*} config
+ */
+export default function (config = {}) {
+  config = Object.assign({}, defaultConfig, config)
+
+  let written = false
+
+  const writeReport = result => {
+    if (written) return
+    if (!result || !Array.isArray(result.tests)) return
+    written = true
+
+    const dir = config.output ? path.resolve(store.codeceptDir || process.cwd(), config.output) : store.outputDir || process.cwd()
+    mkdirp.sync(dir)
+    const file = path.join(dir, config.outputName)
+
+    fs.writeFileSync(file, buildXml(result, config))
+    output.plugin('junitReporter', `JUnit report saved to ${file}`)
+  }
+
+  event.dispatcher.on(event.all.result, writeReport)
+  event.dispatcher.on(event.workers.result, writeReport)
+}
+
+function buildXml(result, config) {
+  const doc = new DOMImplementation().createDocument(null, null, null)
+  const suites = groupBySuite(result.tests)
+
+  const root = doc.createElement('testsuites')
+  setAttr(root, 'name', config.testGroupName)
+  setAttr(root, 'tests', result.tests.length)
+  setAttr(root, 'failures', countState(result.tests, 'failed'))
+  setAttr(root, 'skipped', countSkipped(result.tests))
+  setAttr(root, 'errors', 0)
+  setAttr(root, 'time', toSeconds(sumDuration(result.tests)))
+  setAttr(root, 'timestamp', toIso(result.stats && result.stats.start))
+  doc.appendChild(root)
+
+  suites.forEach((tests, index) => {
+    const suite = tests[0] && tests[0].parent
+    const suiteName = (suite && suite.title) || 'Tests'
+    const suiteFile = (suite && suite.file) || (tests[0] && tests[0].file) || ''
+
+    const suiteEl = doc.createElement('testsuite')
+    setAttr(suiteEl, 'name', suiteName)
+    setAttr(suiteEl, 'id', index)
+    setAttr(suiteEl, 'tests', tests.length)
+    setAttr(suiteEl, 'failures', countState(tests, 'failed'))
+    setAttr(suiteEl, 'skipped', countSkipped(tests))
+    setAttr(suiteEl, 'errors', 0)
+    setAttr(suiteEl, 'time', toSeconds(sumDuration(tests)))
+    setAttr(suiteEl, 'timestamp', toIso(suite && suite.startedAt))
+    setAttr(suiteEl, 'hostname', os.hostname())
+    if (suiteFile) setAttr(suiteEl, 'file', suiteFile)
+    root.appendChild(suiteEl)
+
+    for (const test of tests) {
+      suiteEl.appendChild(buildTestCase(doc, test, suiteName, config))
+    }
+  })
+
+  return '<?xml version="1.0" encoding="UTF-8"?>\n' + new XMLSerializer().serializeToString(doc) + '\n'
+}
+
+function buildTestCase(doc, test, suiteName, config) {
+  const testEl = doc.createElement('testcase')
+  setAttr(testEl, 'name', test.title || '(no title)')
+  setAttr(testEl, 'classname', suiteName)
+  setAttr(testEl, 'time', toSeconds(test.duration || 0))
+  const file = test.file || (test.parent && test.parent.file)
+  if (file) setAttr(testEl, 'file', file)
+
+  if (config.attachMeta) {
+    const properties = metaProperties(test)
+    if (properties.length) {
+      const propertiesEl = doc.createElement('properties')
+      for (const [name, value] of properties) {
+        const prop = doc.createElement('property')
+        setAttr(prop, 'name', name)
+        setAttr(prop, 'value', value)
+        propertiesEl.appendChild(prop)
+      }
+      testEl.appendChild(propertiesEl)
+    }
+  }
+
+  const flat = flattenSteps(Array.isArray(test.steps) ? test.steps : [])
+
+  if (test.state === 'skipped' || test.state === 'pending') {
+    const skipped = doc.createElement('skipped')
+    const reason = skipReason(test)
+    if (reason) setAttr(skipped, 'message', reason)
+    testEl.appendChild(skipped)
+  } else if (test.state === 'failed') {
+    const err = test.err || {}
+    const failure = doc.createElement('failure')
+    setAttr(failure, 'message', err.message || 'Test failed')
+    setAttr(failure, 'type', err.name || 'Error')
+    let body = err.stack || err.message || 'Test failed'
+    if (config.stepsInFailure && flat.length) {
+      body += '\n\nSteps:\n' + flat.map(stepLogLine).join('\n')
+    }
+    failure.appendChild(doc.createTextNode(cleanText(body)))
+    testEl.appendChild(failure)
+  }
+
+  if (config.attachSteps && flat.length) {
+    const out = doc.createElement('system-out')
+    out.appendChild(doc.createTextNode(cleanText(flat.map(stepLogLine).join('\n'))))
+    testEl.appendChild(out)
+  }
+
+  return testEl
+}
+
+function metaProperties(test) {
+  const props = []
+  const meta = test.meta || {}
+  for (const key of Object.keys(meta)) {
+    if (meta[key] === undefined || meta[key] === null) continue
+    props.push([key, stringifyMeta(meta[key])])
+  }
+  if (Array.isArray(test.tags) && test.tags.length) {
+    props.push(['tags', test.tags.join(' ')])
+  }
+  if (test.retries > 0 || test.retryNum > 0) {
+    props.push(['retries', String(test.retryNum || test.retries)])
+  }
+  return props
+}
+
+function stringifyMeta(value) {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  try {
+    return JSON.stringify(value)
+  } catch (err) {
+    return String(value)
+  }
+}
+
+function flattenSteps(steps) {
+  const out = []
+  let prevChain = []
+
+  for (const step of steps) {
+    const chain = metaChain(step)
+
+    let common = 0
+    while (common < chain.length && common < prevChain.length && chain[common].key === prevChain[common].key) common++
+
+    for (let d = common; d < chain.length; d++) {
+      out.push({ depth: d, step: chain[d].step })
+    }
+    out.push({ depth: chain.length, step })
+    prevChain = chain
+  }
+
+  return out
+}
+
+function metaChain(step) {
+  const chain = []
+  let meta = step && step.metaStep
+  while (meta) {
+    chain.unshift({ step: meta, key: meta })
+    meta = meta.metaStep
+  }
+  if (!chain.length && step && step.parent && step.parent.title) {
+    chain.push({ step: { title: step.parent.title, status: step.status }, key: `meta:${step.parent.title}` })
+  }
+  return chain
+}
+
+function stepLogLine(entry) {
+  const indent = '  '.repeat(entry.depth)
+  const mark = entry.step && entry.step.status === 'failed' ? '[FAILED] ' : ''
+  return `${indent}${mark}${stepText(entry.step)} (${stepDuration(entry.step)}ms)`
+}
+
+function stepText(step) {
+  if (step && typeof step.toString === 'function' && step.toString !== Object.prototype.toString) return step.toString()
+  return (step && step.title) || 'step'
+}
+
+function stepDuration(step) {
+  if (!step) return 0
+  if (typeof step.duration === 'number' && step.duration >= 0) return step.duration
+  if (step.startTime && step.endTime) return Math.max(0, step.endTime - step.startTime)
+  return 0
+}
+
+function groupBySuite(tests) {
+  const groups = []
+  const byKey = new Map()
+  for (const test of tests) {
+    const key = test.parent || test
+    if (!byKey.has(key)) {
+      const list = []
+      byKey.set(key, list)
+      groups.push(list)
+    }
+    byKey.get(key).push(test)
+  }
+  return groups
+}
+
+function skipReason(test) {
+  if (test.opts && test.opts.skipInfo && test.opts.skipInfo.message) return test.opts.skipInfo.message
+  if (test.meta && test.meta.skipReason) return test.meta.skipReason
+  return ''
+}
+
+function countState(tests, state) {
+  return tests.filter(t => t.state === state).length
+}
+
+function countSkipped(tests) {
+  return tests.filter(t => t.state === 'skipped' || t.state === 'pending').length
+}
+
+function sumDuration(tests) {
+  return tests.reduce((sum, t) => sum + (t.duration || 0), 0)
+}
+
+function toSeconds(ms) {
+  return (Math.max(0, ms) / 1000).toFixed(3)
+}
+
+function toIso(value) {
+  const date = value ? new Date(value) : new Date()
+  return Number.isNaN(date.getTime()) ? new Date().toISOString() : date.toISOString()
+}
+
+function cleanText(text) {
+  return String(text == null ? '' : text).replace(INVALID_XML_CHARS, '')
+}
+
+function setAttr(el, name, value) {
+  el.setAttribute(name, cleanText(value))
+}

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
+      }
+    })
+  })
+}