codeceptjs 4.0.0-rc.17 → 4.0.0-rc.18

package/lib/plugin/screenshotOnFail.js

@@ -1,177 +1,15 @@
-import fs from 'fs'
-import path from 'path'
-
-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 { fileExists } from '../utils.js'
-import Codeceptjs from '../index.js'
-import { testToFileName } from '../mocha/test.js'
-
-const defaultConfig = {
-  uniqueScreenshotNames: false,
-  disableScreenshots: false,
-  fullPageScreenshots: false,
-}
+import screenshot from './screenshot.js'
 
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
+let warned = false
 
 /**
- * Creates screenshot on failure. Screenshot is saved into `output` directory.
- *
- * Initially this functionality was part of corresponding helper but has been moved into plugin since 1.4
- *
- * This plugin is **enabled by default**.
- *
- * #### Configuration
- *
- * Configuration can either be taken from a corresponding helper (deprecated) or a from plugin config (recommended).
- *
- * ```js
- * plugins: {
- *    screenshotOnFail: {
- *      enabled: true
- *    }
- * }
- * ```
- *
- * Possible config options:
- *
- * * `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
- * * `fullPageScreenshots`: make full page screenshots. Default: false.
- *
- *
+ * @deprecated Use the `screenshot` plugin with `on: 'fail'` (the default).
  */
-export default function (config) {
-  const helpers = Container.helpers()
-  let helper
-
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
-
-  if (!helper) return // no helpers for screenshot
-
-  const options = Object.assign(defaultConfig, helper.options, config)
-
-  if (helpers.Mochawesome) {
-    if (helpers.Mochawesome.config) {
-      options.uniqueScreenshotNames = helpers.Mochawesome.config.uniqueScreenshotNames
-    }
-  }
-
-  if (Codeceptjs.container.mocha()) {
-    options.reportDir = Codeceptjs.container.mocha()?.options?.reporterOptions && Codeceptjs.container.mocha()?.options?.reporterOptions?.reportDir
-  }
-
-  if (options.disableScreenshots) {
-    // old version of disabling screenshots
-    return
+export default function (config = {}) {
+  if (!warned) {
+    output.error('screenshotOnFail is deprecated; use the `screenshot` plugin (default on=fail).')
+    warned = true
   }
-
-  event.dispatcher.on(event.test.failed, (test, _err, hookName) => {
-    if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') {
-      // no browser here
-      return
-    }
-
-    recorder.add(
-      'screenshot of failed test',
-      async () => {
-        const dataType = 'image/png'
-        // This prevents data driven to be included in the failed screenshot file name
-        let fileName
-
-        if (options.uniqueScreenshotNames && test) {
-          fileName = `${testToFileName(test, { suffix: '', unique: true })}.failed.png`
-        } else {
-          fileName = `${testToFileName(test, { suffix: '', unique: false })}.failed.png`
-        }
-        const quietMode = !store.outputDir
-        if (!quietMode) {
-          output.plugin('screenshotOnFail', 'Test failed, try to save a screenshot')
-        }
-
-        // Re-check helpers at runtime in case they weren't ready during plugin init
-        const runtimeHelpers = Container.helpers()
-        let runtimeHelper = null
-        for (const helperName of supportedHelpers) {
-          if (Object.keys(runtimeHelpers).indexOf(helperName) > -1) {
-            runtimeHelper = runtimeHelpers[helperName]
-            break
-          }
-        }
-
-        if (runtimeHelper && typeof runtimeHelper.saveScreenshot === 'function') {
-          helper = runtimeHelper
-        }
-
-        try {
-          if (options.reportDir) {
-            fileName = path.join(options.reportDir, fileName)
-            const mochaReportDir = path.resolve(process.cwd(), options.reportDir)
-            if (!fileExists(mochaReportDir)) {
-              fs.mkdirSync(mochaReportDir)
-            }
-          }
-
-          // Check if browser/page is still available before attempting screenshot
-          if (helper.page && helper.page.isClosed && helper.page.isClosed()) {
-            throw new Error('Browser page has been closed')
-          }
-          if (helper.browser && helper.browser.isConnected && !helper.browser.isConnected()) {
-            throw new Error('Browser has been disconnected')
-          }
-
-          // Add timeout wrapper to prevent hanging with shorter timeout for ESM
-          const screenshotPromise = helper.saveScreenshot(fileName, options.fullPageScreenshots)
-          const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => reject(new Error('Screenshot timeout after 5 seconds')), 5000)
-          })
-
-          await Promise.race([screenshotPromise, timeoutPromise])
-
-          if (!test.artifacts) test.artifacts = {}
-          const baseOutputDir = store.outputDir || null
-          if (baseOutputDir) {
-            test.artifacts.screenshot = path.join(baseOutputDir, fileName)
-            if (Container.mocha().options.reporterOptions['mocha-junit-reporter'] && Container.mocha().options.reporterOptions['mocha-junit-reporter'].options.attachments) {
-              test.attachments = [path.join(baseOutputDir, fileName)]
-            }
-          } else {
-            // Fallback: just store the file name to keep tests stable without triggering path errors
-            test.artifacts.screenshot = fileName
-          }
-        } catch (err) {
-          if (!quietMode) {
-            output.plugin('screenshotOnFail', `Failed to save screenshot: ${err.message}`)
-          }
-          // Enhanced error handling for browser closed scenarios
-          if (
-            err &&
-            ((err.message &&
-              (err.message.includes('Target page, context or browser has been closed') ||
-                err.message.includes('Browser page has been closed') ||
-                err.message.includes('Browser has been disconnected') ||
-                err.message.includes('was terminated due to') ||
-                err.message.includes('no such window: target window already closed') ||
-                err.message.includes('Screenshot timeout after'))) ||
-              (err.type && err.type === 'RuntimeError'))
-          ) {
-            output.log(`Can't make screenshot, ${err.message}`)
-            helper.isRunning = false
-          }
-        }
-      },
-      true,
-    )
-  })
+  return screenshot({ ...config, on: 'fail' })
 }

package/lib/utils/pluginParser.js

@@ -0,0 +1,151 @@
+import Container from '../container.js'
+import output from '../output.js'
+
+const supportedHelpers = Container.STANDARD_ACTING_HELPERS
+
+const RESERVED_KEYS = new Set(['on', 'path', 'line', 'pattern'])
+const ALL_MODES = ['fail', 'test', 'step', 'file', 'url']
+
+/**
+ * Parse a plugin's _args (from CLI `-p plugin:key=value:key=value`) into a flat dict.
+ * Each entry is split on `;` then on the first `=`. Bare segments become `{ key: true }`.
+ *
+ * Examples:
+ *   parsePluginArgs(['on=fail'])
+ *     → { on: 'fail' }
+ *   parsePluginArgs(['on=file', 'path=tests/foo.js;line=43'])
+ *     → { on: 'file', path: 'tests/foo.js', line: '43' }
+ *   parsePluginArgs(['on=file', 'path=tests/foo.js', 'line=43'])
+ *     → { on: 'file', path: 'tests/foo.js', line: '43' }
+ *   parsePluginArgs(['show'])
+ *     → { show: true }
+ */
+export function parsePluginArgs(args = []) {
+  const opts = {}
+  for (const arg of args) {
+    if (!arg) continue
+    for (const segment of arg.split(';')) {
+      if (!segment) continue
+      if (segment.includes('=')) {
+        const eq = segment.indexOf('=')
+        const key = segment.slice(0, eq)
+        const value = segment.slice(eq + 1)
+        opts[key] = coerce(value)
+      } else {
+        opts[segment] = true
+      }
+    }
+  }
+  return opts
+}
+
+function coerce(v) {
+  if (v === 'true') return true
+  if (v === 'false') return false
+  return v
+}
+
+/**
+ * Compose CLI args > config > defaults into a normalized trigger spec, then
+ * validate it. Returns `{ on, path, line, pattern, ...rest }` with `line`
+ * coerced to a number, or `null` if validation failed (an error is printed).
+ *
+ * @param {object} cliArgs           — output of parsePluginArgs(config._args)
+ * @param {object} config            — full plugin config object
+ * @param {object} defaults          — fallback values, e.g. `{ on: 'fail' }`
+ * @param {object} options
+ * @param {string} options.name      — plugin name, used in error messages
+ * @param {string[]} [options.validModes] — accepted values for `on`
+ *                                          (default: fail, test, step, file, url)
+ */
+export function resolveTrigger(cliArgs = {}, config = {}, defaults = {}, options = {}) {
+  const { name = 'plugin', validModes = ALL_MODES } = options
+  const merged = { ...defaults, ...pickKnown(config), ...cliArgs }
+  if (merged.line != null) merged.line = parseInt(merged.line, 10)
+
+  const valid = new Set(validModes)
+  if (!valid.has(merged.on)) {
+    output.error(`${name}: unknown on="${merged.on}". Valid: ${validModes.join(', ')}`)
+    return null
+  }
+  if (merged.on === 'file' && !merged.path) {
+    output.error(`${name}:on=file requires path=. Example: -p ${name}:on=file:path=tests/foo.js`)
+    return null
+  }
+  if (merged.on === 'url' && !merged.pattern) {
+    output.error(`${name}:on=url requires pattern=. Example: -p ${name}:on=url:pattern=/users/*`)
+    return null
+  }
+
+  return merged
+}
+
+function pickKnown(config) {
+  const out = {}
+  for (const key of Object.keys(config || {})) {
+    if (RESERVED_KEYS.has(key)) out[key] = config[key]
+  }
+  return out
+}
+
+/**
+ * Match a step's source location against a `path` (substring/suffix) and optional `line`.
+ * Reads the step's stack via `step.line()` to get `file:row:col`.
+ */
+export function matchStepFile(step, targetPath, targetLine) {
+  if (!targetPath) return false
+  const stepLine = step.line && step.line()
+  if (!stepLine) return false
+
+  const parsed = parseStepLine(stepLine)
+  if (!parsed) return false
+
+  const fileMatches = parsed.file.includes(targetPath) || parsed.file.endsWith(targetPath)
+  if (!fileMatches) return false
+
+  if (targetLine != null && !Number.isNaN(targetLine) && parsed.line !== targetLine) return false
+  return true
+}
+
+function parseStepLine(stepLine) {
+  let line = stepLine.trim()
+  if (line.startsWith('at ')) line = line.substring(3).trim()
+
+  const lastColon = line.lastIndexOf(':')
+  if (lastColon < 0) return null
+  const secondLastColon = line.lastIndexOf(':', lastColon - 1)
+  if (secondLastColon < 0) return null
+
+  const file = line.substring(0, secondLastColon)
+  const lineNum = parseInt(line.substring(secondLastColon + 1, lastColon), 10)
+
+  if (Number.isNaN(lineNum)) return null
+  return { file, line: lineNum }
+}
+
+/**
+ * Match a URL string against a glob-style pattern (supports `*` wildcards).
+ */
+export function matchUrl(currentUrl, pattern) {
+  if (!pattern || !currentUrl) return false
+  return patternToRegex(pattern).test(currentUrl)
+}
+
+function patternToRegex(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+  const regexStr = escaped.replace(/\*/g, '.*')
+  return new RegExp(regexStr)
+}
+
+/**
+ * Return the first available standard browser helper, or null.
+ */
+export function getBrowserHelper() {
+  const helpers = Container.helpers()
+  for (const name of supportedHelpers) {
+    if (Object.keys(helpers).indexOf(name) > -1) {
+      return helpers[name]
+    }
+  }
+  return null
+}

package/lib/utils/trace.js

@@ -0,0 +1,297 @@
+import crypto from 'crypto'
+import fs from 'fs'
+import path from 'path'
+import { pathToFileURL } from 'url'
+import Container from '../container.js'
+import { clearString } from '../utils.js'
+import { formatHtml } from '../html.js'
+import { diffAriaSnapshots } from '../aria.js'
+
+// ---------------------------------------------------------------------------
+// Helper / directory naming
+// ---------------------------------------------------------------------------
+
+export function pickActingHelper(helpers) {
+  for (const name of Container.STANDARD_ACTING_HELPERS) {
+    if (helpers[name]) return helpers[name]
+  }
+  return null
+}
+
+export function traceDirFor(testFile, testTitle, baseDir) {
+  const hash = crypto.createHash('sha256').update((testFile || '') + (testTitle || '')).digest('hex').slice(0, 8)
+  const cleanTitle = clearString(testTitle || '').slice(0, 200)
+  return path.resolve(baseDir, `trace_${cleanTitle}_${hash}`)
+}
+
+export function snapshotDirFor(baseDir) {
+  const hash = crypto.randomBytes(4).toString('hex')
+  return path.resolve(baseDir, `snapshot_${Date.now()}_${hash}`)
+}
+
+// ---------------------------------------------------------------------------
+// Artifact link rendering (trace.md)
+// ---------------------------------------------------------------------------
+
+const ARTIFACT_LABELS = {
+  html: 'HTML',
+  aria: 'ARIA',
+  screenshot: 'Screenshot',
+  console: 'Browser Logs',
+  storage: 'Storage',
+}
+
+export function artifactLinks(artifacts, { indent = '  ', consoleCount } = {}) {
+  const lines = []
+  const order = ['html', 'aria', 'screenshot', 'console', 'storage']
+
+  for (const key of order) {
+    const file = artifacts[key]
+    if (!file) continue
+    const label = ARTIFACT_LABELS[key]
+    let line = `${indent}> [${label}](./${file})`
+    if (key === 'console') {
+      const count = consoleCount ?? artifacts.consoleCount ?? 0
+      line += ` (${count} entries)`
+    } else if (key === 'storage') {
+      const cookies = artifacts.cookieCount ?? 0
+      const ls = artifacts.localStorageCount ?? 0
+      line += ` (${cookies} cookies, ${ls} localStorage)`
+    }
+    lines.push(line)
+  }
+
+  return lines.join('\n')
+}
+
+export function fileToUrl(dir, basename) {
+  return pathToFileURL(path.join(dir, basename)).href
+}
+
+export function writeTraceMarkdown({ dir, title, file, durationMs, commands, captured, error }) {
+  let md = `file: ${file || 'mcp'}\n`
+  md += `name: ${title}\n`
+  md += `time: ${(durationMs / 1000).toFixed(2)}s\n`
+  md += `---\n\n`
+
+  if (error) md += `Error: ${error}\n\n---\n\n`
+
+  if (commands && commands.length) {
+    md += `### Commands\n`
+    for (const c of commands) md += `- ${c}\n`
+    md += `\n`
+  }
+
+  md += `### Final State\n`
+  if (captured.url) md += `  > URL: ${captured.url}\n`
+  const links = artifactLinks(captured)
+  if (links) md += links + '\n'
+
+  const traceFile = path.join(dir, 'trace.md')
+  fs.writeFileSync(traceFile, md)
+  return traceFile
+}
+
+export function artifactsToFileUrls(captured, dir) {
+  const out = {}
+  if (captured.url) out.url = captured.url
+  if (captured.screenshot) out.screenshot = fileToUrl(dir, captured.screenshot)
+  if (captured.html) out.html = fileToUrl(dir, captured.html)
+  if (captured.aria) out.aria = fileToUrl(dir, captured.aria)
+  if (captured.console) out.console = fileToUrl(dir, captured.console)
+  if (captured.storage) out.storage = fileToUrl(dir, captured.storage)
+  if (typeof captured.consoleCount === 'number') out.consoleCount = captured.consoleCount
+  if (typeof captured.cookieCount === 'number') out.cookieCount = captured.cookieCount
+  if (typeof captured.localStorageCount === 'number') out.localStorageCount = captured.localStorageCount
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot capture (HTML / ARIA / screenshot / console / storage)
+// ---------------------------------------------------------------------------
+
+function normalizeBrowserLogs(logs) {
+  return (logs || []).map(l => {
+    if (typeof l === 'string') return l
+    if (l && typeof l.type === 'function' && typeof l.text === 'function') {
+      return { type: l.type(), text: l.text() }
+    }
+    return l
+  })
+}
+
+async function captureStorageState(helper) {
+  if (typeof helper.grabStorageState === 'function') {
+    try {
+      const state = await helper.grabStorageState()
+      if (state) return state
+    } catch {}
+  }
+
+  const state = { cookies: [], origins: [] }
+
+  if (typeof helper.grabCookie === 'function') {
+    try {
+      const cookies = await helper.grabCookie()
+      if (Array.isArray(cookies)) state.cookies = cookies
+    } catch {}
+  }
+
+  if (typeof helper.executeScript === 'function') {
+    try {
+      const result = await helper.executeScript(() => {
+        const out = { origin: location.origin, items: [] }
+        for (let i = 0; i < localStorage.length; i++) {
+          const name = localStorage.key(i)
+          out.items.push({ name, value: localStorage.getItem(name) })
+        }
+        return out
+      })
+      if (result?.items?.length) {
+        state.origins.push({ origin: result.origin, localStorage: result.items })
+      }
+    } catch {}
+  }
+
+  return state
+}
+
+export async function captureSnapshot(helper, {
+  dir,
+  prefix = 'snapshot',
+  fullPage = false,
+  captureURL = true,
+  captureScreenshot = true,
+  captureHTML = true,
+  captureARIA = true,
+  captureBrowserLogs = true,
+  captureStorage = true,
+} = {}) {
+  if (!helper) return {}
+  const out = {}
+
+  if (captureURL) {
+    try {
+      if (helper.grabCurrentUrl) out.url = await helper.grabCurrentUrl()
+    } catch {}
+  }
+
+  if (captureScreenshot && helper.saveScreenshot) {
+    try {
+      const file = `${prefix}_screenshot.png`
+      await helper.saveScreenshot(path.join(dir, file), fullPage)
+      out.screenshot = file
+    } catch {}
+  }
+
+  if (captureHTML && helper.grabSource) {
+    try {
+      const html = await helper.grabSource()
+      // Universal funnel: every captured HTML snapshot flows through formatHtml
+      // (minify -> cleanHtml -> beautify). Don't add direct grabSource->writeFile
+      // paths elsewhere; route through this util so trash-class cleanup stays
+      // consistent across aiTrace, pageInfo, and MCP tools.
+      const formatted = await formatHtml(html)
+      const file = `${prefix}_page.html`
+      fs.writeFileSync(path.join(dir, file), formatted)
+      out.html = file
+      // Expose pre-cleanup HTML for consumers that need to inspect classes
+      // stripped by cleanHtml (e.g. pageInfo's error-class scan).
+      out.htmlRaw = html
+    } catch {}
+  }
+
+  if (captureARIA && helper.grabAriaSnapshot) {
+    try {
+      const aria = await helper.grabAriaSnapshot()
+      const file = `${prefix}_aria.txt`
+      fs.writeFileSync(path.join(dir, file), aria)
+      out.aria = file
+    } catch {}
+  }
+
+  if (captureBrowserLogs && helper.grabBrowserLogs) {
+    try {
+      const logs = await helper.grabBrowserLogs()
+      const normalized = normalizeBrowserLogs(logs)
+      const file = `${prefix}_console.json`
+      fs.writeFileSync(path.join(dir, file), JSON.stringify(normalized, null, 2))
+      out.console = file
+      out.consoleCount = normalized.length
+    } catch {}
+  }
+
+  if (captureStorage) {
+    try {
+      const state = await captureStorageState(helper)
+      const cookieCount = state.cookies?.length || 0
+      const localStorageCount = (state.origins || [])
+        .reduce((sum, o) => sum + (o.localStorage?.length || 0), 0)
+      if (cookieCount || localStorageCount) {
+        const file = `${prefix}_storage.json`
+        fs.writeFileSync(path.join(dir, file), JSON.stringify(state, null, 2))
+        out.storage = file
+        out.cookieCount = cookieCount
+        out.localStorageCount = localStorageCount
+      }
+    } catch {}
+  }
+
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// TraceReader — read artifacts already on disk (written by aiTrace, MCP, etc.)
+// ---------------------------------------------------------------------------
+
+const KIND_SUFFIX = {
+  aria: '_aria.txt',
+  html: '_page.html',
+  screenshot: '_screenshot.png',
+  console: '_console.json',
+  storage: '_storage.json',
+}
+
+export class TraceReader {
+  constructor(dir) {
+    this.dir = dir
+  }
+
+  // Filenames of a given kind, sorted in capture order. aiTrace prefixes with
+  // a zero-padded step index (`0000_`, `0001_`...), so a lexical sort is
+  // chronological.
+  list(kind) {
+    const suffix = KIND_SUFFIX[kind]
+    if (!suffix || !this.dir || !fs.existsSync(this.dir)) return []
+    let entries
+    try { entries = fs.readdirSync(this.dir) } catch { return [] }
+    return entries.filter(f => f.endsWith(suffix)).sort()
+  }
+
+  // Path of the n-th file of `kind`, or null. Python-style indexing:
+  // 0..N-1 from the start, -1..-N from the end.
+  pathAt(n, kind) {
+    const files = this.list(kind)
+    if (!files.length) return null
+    const i = n < 0 ? files.length + n : n
+    if (i < 0 || i >= files.length) return null
+    return path.join(this.dir, files[i])
+  }
+
+  // Read content of the n-th file of `kind`. Binary kinds (screenshot) are
+  // returned as Buffer; text kinds as utf8 string.
+  nth(n, kind) {
+    const p = this.pathAt(n, kind)
+    if (!p) return null
+    try {
+      if (kind === 'screenshot') return fs.readFileSync(p)
+      return fs.readFileSync(p, 'utf8')
+    } catch { return null }
+  }
+
+  first(kind) { return this.nth(0, kind) }
+  last(kind)  { return this.nth(-1, kind) }
+  count(kind) { return this.list(kind).length }
+}
+
+export const ariaDiff = diffAriaSnapshots

package/lib/utils.js

@@ -617,6 +617,12 @@ function createCircularSafeReplacer(keysToSkip = []) {
       return undefined
     }
 
+    // Coerce types that JSON.stringify can't handle natively
+    if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`
+    if (typeof value === 'bigint') return `${value.toString()}n`
+    if (typeof value === 'symbol') return value.toString()
+    if (value instanceof Error) return { name: value.name, message: value.message, stack: value.stack }
+
     if (value === null || typeof value !== 'object') {
       return value
     }
@@ -647,6 +653,25 @@ export const safeStringify = function (obj, keysToSkip = [], space = 0) {
   }
 }
 
+/**
+ * Truncate a string at a byte cap, returning structured info.
+ * @param {string} str
+ * @param {number} maxBytes
+ * @returns {{ value: string, truncated: boolean, fullLength: number }}
+ */
+export const truncateString = function (str, maxBytes) {
+  if (typeof str !== 'string') str = String(str)
+  if (str.length <= maxBytes) {
+    return { value: str, truncated: false, fullLength: str.length }
+  }
+  const dropped = str.length - maxBytes
+  return {
+    value: `${str.slice(0, maxBytes)}\n...[truncated ${dropped} more chars]`,
+    truncated: true,
+    fullLength: str.length,
+  }
+}
+
 export const serializeError = function (error) {
   if (error) {
     const { stack, uncaught, message, actual, expected } = error