codeceptjs 4.0.0-rc.8 → 4.0.0

package/lib/pause.js

@@ -18,6 +18,8 @@ let nextStep
 let finish
 let next
 let registeredVariables = {}
+let externalHandler = null
+
 /**
  * Pauses test execution and starts interactive shell
  * @param {Object<string, *>} [passedObject]
@@ -37,10 +39,10 @@ const pause = function (passedObject = {}) {
   })
 
   event.dispatcher.on(event.test.finished, () => {
-    finish()
+    if (typeof finish === 'function') finish()
     recorder.session.restore('pause')
-    rl.close()
-    history.save()
+    if (rl) rl.close()
+    if (!externalHandler) history.save()
   })
 
   recorder.add('Start new session', () => pauseSession(passedObject))
@@ -49,6 +51,15 @@ const pause = function (passedObject = {}) {
 function pauseSession(passedObject = {}) {
   registeredVariables = passedObject
   recorder.session.start('pause')
+
+  if (externalHandler) {
+    store.onPause = true
+    return externalHandler({ registeredVariables }).then(() => {
+      store.onPause = false
+      recorder.session.restore('pause')
+    })
+  }
+
   if (!next) {
     let vars = Object.keys(registeredVariables).join(', ')
     if (vars) vars = `(vars: ${vars})`
@@ -234,5 +245,28 @@ function registerVariable(name, value) {
   registeredVariables[name] = value
 }
 
+/**
+ * Hook for external pause drivers (e.g. the MCP server). When set, pauseSession
+ * delegates to the handler instead of opening a readline REPL. The handler
+ * receives `{ registeredVariables }` and returns a Promise that resolves when
+ * the driver decides to continue (resume) or step.
+ *
+ * The driver controls step-vs-resume by mutating `next` via setNextStep before
+ * resolving its Promise.
+ */
+function setPauseHandler(handler) {
+  externalHandler = handler
+}
+
+/**
+ * Trigger a one-shot pause from outside the test (e.g. the MCP server,
+ * pausing the test at a specific step index without modifying the test).
+ * Schedules pauseSession through the recorder so it slots between steps.
+ */
+function pauseNow(passedObject = {}) {
+  if (store.dryRun) return
+  recorder.add('Triggered pause', () => pauseSession(passedObject))
+}
+
 export default pause
-export { registerVariable }
+export { registerVariable, setPauseHandler, pauseNow }

package/lib/plugin/aiTrace.js

@@ -1,22 +1,26 @@
-import crypto from 'crypto'
 import fs from 'fs'
 import { mkdirp } from 'mkdirp'
 import path from 'path'
-import { fileURLToPath } from 'url'
 
+import store from '../store.js'
 import Container from '../container.js'
 import recorder from '../recorder.js'
 import event from '../event.js'
 import output from '../output.js'
 import { deleteDir, clearString } from '../utils.js'
-import colors from 'chalk'
-
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
+import { captureSnapshot, pickActingHelper, traceDirFor, artifactLinks } from '../utils/trace.js'
+import {
+  parsePluginArgs,
+  resolveTrigger,
+  matchStepFile,
+  matchUrl,
+} from '../utils/pluginParser.js'
 
 const defaultConfig = {
+  on: 'step',
   deleteSuccessful: false,
   fullPageScreenshots: false,
-  output: global.output_dir,
+  output: store.outputDir,
   captureHTML: true,
   captureARIA: true,
   captureBrowserLogs: true,
@@ -52,20 +56,26 @@ const defaultConfig = {
  * * `captureHTTP`: capture HTTP requests (requires `trace` or `recordHar` enabled in helper config). Default: true.
  * * `captureDebugOutput`: capture CodeceptJS debug output. Default: true.
  * * `ignoreSteps`: steps to ignore in trace. Array of RegExps is expected.
+ * * `on`: trigger mode — `step` (default), `fail`, `test`, `file`, `url`.
+ *
+ * #### `on=` modes
+ *
+ * * **step** — persist every step (default)
+ * * **fail** — persist only the failed step
+ * * **test** — persist only the last step of each test
+ * * **file** — persist steps from `path=...[;line=...]`
+ * * **url** — persist when the current URL matches `pattern=...`
  *
  * @param {*} config
  */
-export default function (config) {
-  const helpers = Container.helpers()
-  let helper
+export default function (config = {}) {
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: defaultConfig.on }, { name: 'aiTrace' })
+  if (!trigger) return
 
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
+  const helper = pickActingHelper(Container.helpers())
 
   if (!helper) {
     output.warn('aiTrace plugin: No supported helper found (Playwright, Puppeteer, WebDriver). Plugin disabled.')
@@ -82,9 +92,10 @@ export default function (config) {
   let testStartTime
   let currentUrl = null
   let testFailed = false
+  let pendingArtifactCapture = null
   let firstFailedStepSaved = false
 
-  const reportDir = config.output ? path.resolve(global.codecept_dir, config.output) : defaultConfig.output
+  const reportDir = config.output ? path.resolve(store.codeceptDir, config.output) : defaultConfig.output
 
   if (config.captureDebugOutput) {
     const originalDebug = output.debug
@@ -105,13 +116,7 @@ export default function (config) {
     } catch (err) {
       title = test.title
     }
-    const testTitle = clearString(title).slice(0, 200)
-    const uniqueHash = crypto
-      .createHash('sha256')
-      .update(test.file + test.title)
-      .digest('hex')
-      .slice(0, 8)
-    dir = path.join(reportDir, `trace_${testTitle}_${uniqueHash}`)
+    dir = traceDirFor(test.file, title, reportDir)
     mkdirp.sync(dir)
     deleteDir(dir)
     mkdirp.sync(dir)
@@ -125,6 +130,7 @@ export default function (config) {
     currentUrl = null
     testFailed = false
     firstFailedStepSaved = false
+    pendingArtifactCapture = null
   })
 
   event.dispatcher.on(event.step.after, step => {
@@ -140,13 +146,30 @@ export default function (config) {
       output.debug(`aiTrace: Skipping failed step "${step.toString()}" - already handled by step.failed event`)
       return
     }
-    const stepPersistPromise = persistStep(step).catch(err => {
+
+    // on= filtering
+    if (trigger.on === 'fail') return // failed steps handled by step.failed
+    if (trigger.on === 'file' && !matchStepFile(step, trigger.path, trigger.line)) return
+    if (trigger.on === 'url') {
+      recorder.add('aiTrace:url check', async () => {
+        try {
+          if (!helper.grabCurrentUrl) return
+          const url = await helper.grabCurrentUrl()
+          if (!matchUrl(url, trigger.pattern)) return
+          await persistStep(step)
+        } catch (err) {
+          output.debug(`aiTrace: Error in url-mode step persistence: ${err.message}`)
+        }
+      }, true)
+      return
+    }
+
+    recorder.add(`aiTrace step persistence: ${step.toString()}`, () => persistStep(step).catch(err => {
       output.debug(`aiTrace: Error saving step: ${err.message}`)
-    })
-    recorder.add(`wait aiTrace step persistence: ${step.toString()}`, () => stepPersistPromise, true)
+    }), true)
   })
 
-  event.dispatcher.on(event.step.failed, async step => {
+  event.dispatcher.on(event.step.failed, step => {
     if (!currentTest) return
     if (step.status === 'queued' && testFailed) {
       output.debug(`aiTrace: Skipping queued failed step "${step.toString()}" - testFailed: ${testFailed}`)
@@ -166,15 +189,13 @@ export default function (config) {
       }
       existingStep.status = 'failed'
 
-      try {
-        await captureArtifactsForStep(step, existingStep, existingStep.prefix)
-      } catch (err) {
+      pendingArtifactCapture = captureArtifactsForStep(step, existingStep, existingStep.prefix).catch(err => {
         output.debug(`aiTrace: Error updating failed step: ${err.message}`)
-      }
+      })
     } else {
       if (stepNum === -1) return
       if (isStepIgnored(step)) return
-      if (step.metaStep && step.metaStep.name === 'BeforeSuite') return
+      if (step.metaStep && step.metaStep.title === 'BeforeSuite') return
 
       const stepPrefix = generateStepPrefix(step, stepNum)
       stepNum++
@@ -196,11 +217,9 @@ export default function (config) {
       steps.push(stepData)
       firstFailedStepSaved = true
 
-      try {
-        await captureArtifactsForStep(step, stepData, stepPrefix)
-      } catch (err) {
+      pendingArtifactCapture = captureArtifactsForStep(step, stepData, stepPrefix).catch(err => {
         output.debug(`aiTrace: Error capturing failed step artifacts: ${err.message}`)
-      }
+      })
     }
   })
 
@@ -216,13 +235,19 @@ export default function (config) {
     if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') {
       return
     }
-    persist(test, 'failed')
+    recorder.add('aiTrace:persist failed', async () => {
+      if (pendingArtifactCapture) {
+        await pendingArtifactCapture
+        pendingArtifactCapture = null
+      }
+      persist(test, 'failed')
+    }, true)
   })
 
   async function persistStep(step) {
     if (stepNum === -1) return
     if (isStepIgnored(step)) return
-    if (step.metaStep && step.metaStep.name === 'BeforeSuite') return
+    if (step.metaStep && step.metaStep.title === 'BeforeSuite') return
 
     const stepKey = step.toString()
 
@@ -281,6 +306,7 @@ export default function (config) {
         output.debug(`aiTrace: Browser unavailable, partial artifact capture: ${err.message}`)
       }
 
+      let preExistingScreenshot = false
       if (step.artifacts?.screenshot) {
         const screenshotPath = path.isAbsolute(step.artifacts.screenshot)
           ? step.artifacts.screenshot
@@ -288,6 +314,7 @@ export default function (config) {
         const screenshotFile = path.basename(screenshotPath)
         stepData.artifacts.screenshot = screenshotFile
         step.artifacts.screenshot = screenshotPath
+        preExistingScreenshot = true
 
         if (!fs.existsSync(screenshotPath)) {
           try {
@@ -296,58 +323,31 @@ export default function (config) {
             output.debug(`aiTrace: Could not save screenshot: ${err.message}`)
           }
         }
-      } else {
-        try {
-          const screenshotFile = `${stepPrefix}_screenshot.png`
-          const screenshotPath = path.join(dir, screenshotFile)
-          await helper.saveScreenshot(screenshotPath, config.fullPageScreenshots)
-
-          stepData.artifacts.screenshot = screenshotFile
-          step.artifacts.screenshot = screenshotPath
-        } catch (err) {
-          output.debug(`aiTrace: Could not save screenshot: ${err.message}`)
-        }
       }
 
-      // Save HTML
-      if (config.captureHTML && helper.grabSource && browserAvailable) {
-        if (!step.artifacts?.html) {
-          try {
-            const html = await helper.grabSource()
-            const htmlFile = `${stepPrefix}_page.html`
-            fs.writeFileSync(path.join(dir, htmlFile), html)
-            stepData.artifacts.html = htmlFile
-          } catch (err) {
-            output.debug(`aiTrace: Could not capture HTML: ${err.message}`)
-          }
-        } else {
-          stepData.artifacts.html = step.artifacts.html
-        }
-      }
+      const captured = await captureSnapshot(helper, {
+        dir,
+        prefix: stepPrefix,
+        fullPage: config.fullPageScreenshots,
+        captureHTML: config.captureHTML && browserAvailable,
+        captureARIA: config.captureARIA && browserAvailable,
+        captureBrowserLogs: config.captureBrowserLogs && browserAvailable,
+        captureStorage: false,
+      })
 
-      // Save ARIA snapshot
-      if (config.captureARIA && helper.grabAriaSnapshot && browserAvailable) {
-        try {
-          const aria = await helper.grabAriaSnapshot()
-          const ariaFile = `${stepPrefix}_aria.txt`
-          fs.writeFileSync(path.join(dir, ariaFile), aria)
-          stepData.artifacts.aria = ariaFile
-        } catch (err) {
-          output.debug(`aiTrace: Could not capture ARIA snapshot: ${err.message}`)
-        }
+      if (!preExistingScreenshot && captured.screenshot) {
+        stepData.artifacts.screenshot = captured.screenshot
+        step.artifacts.screenshot = path.join(dir, captured.screenshot)
       }
-
-      // Save browser logs
-      if (config.captureBrowserLogs && helper.grabBrowserLogs && browserAvailable) {
-        try {
-          const logs = await helper.grabBrowserLogs()
-          const logsFile = `${stepPrefix}_console.json`
-          fs.writeFileSync(path.join(dir, logsFile), JSON.stringify(logs || [], null, 2))
-          stepData.artifacts.console = logsFile
-          stepData.meta.consoleCount = logs ? logs.length : 0
-        } catch (err) {
-          output.debug(`aiTrace: Could not capture browser logs: ${err.message}`)
-        }
+      if (step.artifacts?.html) {
+        stepData.artifacts.html = step.artifacts.html
+      } else if (captured.html) {
+        stepData.artifacts.html = captured.html
+      }
+      if (captured.aria) stepData.artifacts.aria = captured.aria
+      if (captured.console) {
+        stepData.artifacts.console = captured.console
+        stepData.meta.consoleCount = captured.consoleCount
       }
     } catch (err) {
       output.plugin(`aiTrace: Can't save step artifacts: ${err}`)
@@ -360,6 +360,12 @@ export default function (config) {
       return
     }
 
+    // on=test: only render the last step in markdown; artifacts of earlier steps
+    // remain on disk unreferenced.
+    if (trigger.on === 'test') {
+      steps = steps.slice(-1)
+    }
+
     const testDuration = ((Date.now() - testStartTime) / 1000).toFixed(2)
 
     let markdown = `file: ${test.file || 'unknown'}\n`
@@ -404,22 +410,8 @@ export default function (config) {
         })
       }
 
-      if (stepData.artifacts.html) {
-        markdown += `  > [HTML](./${stepData.artifacts.html})\n`
-      }
-
-      if (stepData.artifacts.aria) {
-        markdown += `  > [ARIA Snapshot](./${stepData.artifacts.aria})\n`
-      }
-
-      if (stepData.artifacts.screenshot) {
-        markdown += `  > [Screenshot](./${stepData.artifacts.screenshot})\n`
-      }
-
-      if (stepData.artifacts.console) {
-        const count = stepData.meta.consoleCount || 0
-        markdown += `  > [Browser Logs](./${stepData.artifacts.console}) (${count} entries)\n`
-      }
+      const links = artifactLinks(stepData.artifacts, { consoleCount: stepData.meta.consoleCount })
+      if (links) markdown += links + '\n'
 
       if (config.captureHTTP) {
         if (test.artifacts && test.artifacts.har) {
@@ -437,7 +429,7 @@ export default function (config) {
     const traceFile = path.join(dir, 'trace.md')
     fs.writeFileSync(traceFile, markdown)
 
-    output.print(`🤖 AI Trace: ${colors.white.bold(`file://${traceFile}`)}`)
+    output.print(`Trace Saved: file://${traceFile}`)
 
     if (!test.artifacts) test.artifacts = {}
     test.artifacts.aiTrace = traceFile
@@ -445,8 +437,9 @@ export default function (config) {
 
   function isStepIgnored(step) {
     if (!config.ignoreSteps) return false
+    if (!step.title) return false
     for (const pattern of config.ignoreSteps || []) {
-      if (step.name.match(pattern)) return true
+      if (step.title.match(pattern)) return true
     }
     return false
   }

package/lib/plugin/analyze.js

@@ -12,6 +12,7 @@ const ai = aiModule.default || aiModule
 import colors from 'chalk'
 import ora from 'ora'
 import event from '../event.js'
+import recorder from '../recorder.js'
 
 import output from '../output.js'
 
@@ -154,10 +155,9 @@ const defaultConfig = {
       if (config.vision && test.artifacts.screenshot) {
         debug('Adding screenshot to prompt')
         messages[0].content.push({
-          type: 'image_url',
-          image_url: {
-            url: 'data:image/png;base64,' + base64EncodeFile(test.artifacts.screenshot),
-          },
+          type: 'image',
+          image: base64EncodeFile(test.artifacts.screenshot),
+          mediaType: 'image/png',
         })
       }
 
@@ -227,14 +227,14 @@ export default function (config = {}) {
     console.log('Enabled AI analysis')
   })
 
-  event.dispatcher.on(event.all.result, async result => {
+  event.dispatcher.on(event.all.result, result => {
     if (!isMainThread) return // run only on main thread
     if (!ai.isEnabled) {
       console.log('AI is disabled, no analysis will be performed. Run tests with --ai flag to enable it.')
       return
     }
 
-    printReport(result)
+    recorder.add('analyze:print-ai-report', () => printReport(result), true)
   })
 
   event.dispatcher.on(event.workers.result, async result => {
@@ -248,7 +248,7 @@ export default function (config = {}) {
       return
     }
 
-    printReport(result)
+    await printReport(result)
   })
 
   async function printReport(result) {
@@ -294,7 +294,7 @@ export default function (config = {}) {
       console.error('Error analyzing failed tests', err)
     }
 
-    if (!Object.keys(container.plugins()).includes('pageInfo')) {
+    if (!Object.keys(Container.plugins()).includes('pageInfo')) {
       console.log('To improve analysis, enable pageInfo plugin to get more context for failed tests.')
     }
   }
@@ -353,7 +353,7 @@ function serializeError(error) {
     errorMessage +=
       '\n' +
       error.stack
-        .replace(global.codecept_dir || '', '.')
+        .replace(store.codeceptDir || '', '.')
         .split('\n')
         .map(line => line.replace(ansiRegExp(), ''))
         .slice(0, 5)

package/lib/plugin/auth.js

@@ -321,7 +321,7 @@ export default function (config) {
       }
       if (config.saveToFile) {
         output.debug(`Saved user session into file for ${name}`)
-        fs.writeFileSync(path.join(global.output_dir, `${name}_session.json`), JSON.stringify(cookies))
+        fs.writeFileSync(path.join(store.outputDir, `${name}_session.json`), JSON.stringify(cookies))
       }
       store[`${name}_session`] = cookies
     }
@@ -377,7 +377,7 @@ export default function (config) {
       }
 
       if (!config.saveToFile) return
-      const cookieFile = path.join(global.output_dir, `${name}_session.json`)
+      const cookieFile = path.join(store.outputDir, `${name}_session.json`)
 
       if (!fileExists(cookieFile)) {
         return
@@ -412,7 +412,7 @@ export default function (config) {
 
 function loadCookiesFromFile(config) {
   for (const name in config.users) {
-    const fileName = path.join(global.output_dir, `${name}_session.json`)
+    const fileName = path.join(store.outputDir, `${name}_session.json`)
     if (!fileExists(fileName)) continue
     const data = fs.readFileSync(fileName).toString()
     try {

package/lib/plugin/browser.js

@@ -0,0 +1,77 @@
+import output from '../output.js'
+
+/**
+ * Overrides browser helper config from the command line. Works for all browser helpers
+ * (Playwright, Puppeteer, WebDriver, Appium) without touching `codecept.conf`.
+ *
+ * Enable it via `-p` option with one or more colon-chained args:
+ *
+ * ```
+ * npx codeceptjs run -p browser:show
+ * npx codeceptjs run -p browser:hide
+ * npx codeceptjs run -p browser:browser=firefox
+ * npx codeceptjs run -p browser:windowSize=1024x768:video=false
+ * npx codeceptjs run -p browser:hide:browser=webkit:windowSize=800x600
+ * ```
+ *
+ * #### Args
+ *
+ * * **show** — force visible browser
+ * * **hide** — force headless (also injects `--headless` into WebDriver chrome/firefox capability args)
+ * * **`<key>=<value>`** — set `helpers.<eachBrowserHelper>.<key> = <value>`. Three keys
+ *   get per-helper translation via `setBrowserConfig`:
+ *     * `browser=<name>` — Puppeteer receives `product`, Playwright receives `browser`
+ *     * `windowSize=WxH` — also adds `--window-size=W,H` chromium/chrome args
+ *     * `show=true|false` — toggles `show` on Playwright/Puppeteer; injects/strips
+ *       `--headless` in WebDriver chrome/firefox capability args
+ *
+ * Values stay as strings. `true` / `false` are coerced to booleans.
+ *
+ * Requires `@codeceptjs/configure` to be installed; if missing, the plugin
+ * logs a hint and skips the override.
+ */
+export default async function (config = {}) {
+  const { _args, enabled, ...rest } = config
+  const opts = { ...rest, ...parseArgs(_args || []) }
+  if (Object.keys(opts).length === 0) return
+
+  const configure = await tryImportConfigure()
+  if (!configure) return
+
+  configure.setBrowserConfig(opts)
+  output.debug(`browser plugin: applied ${formatOpts(opts)}`)
+}
+
+async function tryImportConfigure() {
+  try {
+    return await import('@codeceptjs/configure')
+  } catch (err) {
+    output.error("browser plugin: '@codeceptjs/configure' is not installed; CLI overrides are skipped. Run `npm i @codeceptjs/configure` to enable.")
+    return null
+  }
+}
+
+function parseArgs(args) {
+  return args.filter(Boolean).reduce((acc, arg) => Object.assign(acc, parseArg(arg)), {})
+}
+
+function parseArg(arg) {
+  if (arg === 'show') return { show: true }
+  if (arg === 'hide') return { show: false }
+  if (arg.includes('=')) {
+    const [key, ...rest] = arg.split('=')
+    return { [key]: parseValue(rest.join('=')) }
+  }
+  output.error(`browser plugin: unknown arg "${arg}"`)
+  return {}
+}
+
+function parseValue(v) {
+  if (v === 'true') return true
+  if (v === 'false') return false
+  return v
+}
+
+function formatOpts(opts) {
+  return Object.entries(opts).map(([k, v]) => `${k}=${v}`).join(', ')
+}