codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

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

@@ -7,6 +7,7 @@ import getFunctionArguments from 'fn-args'
 import deepClone from 'lodash.clonedeep'
 import merge from 'lodash.merge'
 import { convertColorToRGBA, isColorProperty } from './colorUtils.js'
+import store from './store.js'
 import Fuse from 'fuse.js'
 import crypto from 'crypto'
 import jsBeautify from 'js-beautify'
@@ -150,6 +151,24 @@ export const decodeUrl = function (url) {
   return decodeURIComponent(decodeURIComponent(decodeURIComponent(url)))
 }
 
+export const normalizePath = function (path) {
+  if (path === '' || path === '/') return '/'
+  return path
+    .replace(/\/+/g, '/')
+    .replace(/\/$/, '') || '/'
+}
+
+export const resolveUrl = function (url, baseUrl) {
+  if (!url) return url
+  if (url.indexOf('http') === 0) return url
+  if (!baseUrl) return url
+  try {
+    return new URL(url, baseUrl).href
+  } catch (e) {
+    return url
+  }
+}
+
 export const xpathLocator = {
   /**
    * @param {string} string
@@ -317,13 +336,13 @@ export const screenshotOutputFolder = function (fileName) {
   const fileSep = path.sep
 
   if (!fileName.includes(fileSep) || fileName.includes('record_')) {
-    return path.resolve(global.output_dir, fileName)
+    return path.resolve(store.outputDir, fileName)
   }
-  return path.resolve(global.codecept_dir, fileName)
+  return path.resolve(store.codeceptDir, fileName)
 }
 
 export const relativeDir = function (fileName) {
-  return fileName.replace(global.codecept_dir, '').replace(/^\//, '')
+  return fileName.replace(store.codeceptDir, '').replace(/^\//, '')
 }
 
 export const beautify = function (code) {
@@ -598,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
     }
@@ -628,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
@@ -640,6 +684,36 @@ export const base64EncodeFile = function (filePath) {
   return Buffer.from(fs.readFileSync(filePath)).toString('base64')
 }
 
+export const getMimeType = function (fileName) {
+  const ext = path.extname(fileName).toLowerCase()
+  const mimeTypes = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.zip': 'application/zip',
+    '.csv': 'text/csv',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.wav': 'audio/wav',
+  }
+  return mimeTypes[ext] || 'application/octet-stream'
+}
+
 export const markdownToAnsi = function (markdown) {
   return (
     markdown

package/lib/workers.js

@@ -20,6 +20,7 @@ import event from './event.js'
 import { deserializeTest } from './mocha/test.js'
 import { deserializeSuite } from './mocha/suite.js'
 import recorder from './recorder.js'
+import store from './store.js'
 import runHook from './hooks.js'
 import WorkerStorage from './workerStorage.js'
 import { createRuns } from './command/run-multiple/collection.js'
@@ -28,7 +29,7 @@ const pathToWorker = path.join(__dirname, 'command', 'workers', 'runTests.js')
 
 const initializeCodecept = async (configPath, options = {}) => {
   const config = await mainConfig.load(configPath || '.')
-  const codecept = new Codecept(config, options)
+  const codecept = new Codecept(config, { ...options, skipDefaultListeners: true })
   await codecept.init(getTestRoot(configPath))
   codecept.loadTests()
 
@@ -504,6 +505,7 @@ class Workers extends EventEmitter {
     await this._ensureInitialized()
     recorder.startUnlessRunning()
     event.dispatcher.emit(event.workers.before)
+    store.workerMode = true
     process.env.RUNS_WITH_WORKERS = 'true'
 
     // Create workers and set up message handlers immediately (not in recorder queue)
@@ -519,22 +521,8 @@ class Workers extends EventEmitter {
       // Workers are already running, this is just a placeholder step
     })
 
-    // Add overall timeout to prevent infinite hanging
-    const overallTimeout = setTimeout(() => {
-      console.error('[Main] Overall timeout reached (10 minutes). Force terminating remaining workers...')
-      workerThreads.forEach(w => {
-        try {
-          w.terminate()
-        } catch (e) {
-          // ignore
-        }
-      })
-      this._finishRun()
-    }, 600000) // 10 minutes
-
     return new Promise(resolve => {
       this.on('end', () => {
-        clearTimeout(overallTimeout)
         resolve()
       })
     })
@@ -563,7 +551,7 @@ class Workers extends EventEmitter {
     // Track last activity time to detect hanging workers
     let lastActivity = Date.now()
     let currentTest = null
-    const workerTimeout = 300000 // 5 minutes
+    const workerTimeout = process.env.CODECEPT_WORKER_TIMEOUT ? ms(process.env.CODECEPT_WORKER_TIMEOUT) : ms('5m')
     
     const timeoutChecker = setInterval(() => {
       const elapsed = Date.now() - lastActivity
@@ -625,13 +613,32 @@ class Workers extends EventEmitter {
 
           break
         case event.suite.before:
-          this.emit(event.suite.before, deserializeSuite(message.data))
+          {
+            const suite = deserializeSuite(message.data)
+            this.emit(event.suite.before, suite)
+            event.dispatcher.emit(event.suite.before, suite)
+          }
+          break
+        case event.suite.after:
+          {
+            const suite = deserializeSuite(message.data)
+            this.emit(event.suite.after, suite)
+            event.dispatcher.emit(event.suite.after, suite)
+          }
           break
         case event.test.before:
-          this.emit(event.test.before, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.before, test)
+            event.dispatcher.emit(event.test.before, test)
+          }
           break
         case event.test.started:
-          this.emit(event.test.started, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.started, test)
+            event.dispatcher.emit(event.test.started, test)
+          }
           break
         case event.test.failed:
           // For hook failures, emit immediately as there won't be a test.finished event
@@ -645,7 +652,11 @@ class Workers extends EventEmitter {
           // Skip individual passed events - we'll emit based on finished state
           break
         case event.test.skipped:
-          this.emit(event.test.skipped, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.skipped, test)
+            event.dispatcher.emit(event.test.skipped, test)
+          }
           break
         case event.test.finished:
           // Handle different types of test completion properly
@@ -674,28 +685,47 @@ class Workers extends EventEmitter {
               }
             }
 
-            this.emit(event.test.finished, deserializeTest(data))
+            const test = deserializeTest(data)
+            this.emit(event.test.finished, test)
+            event.dispatcher.emit(event.test.finished, test)
           }
           break
         case event.test.after:
-          this.emit(event.test.after, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.after, test)
+            event.dispatcher.emit(event.test.after, test)
+          }
           break
         case event.step.finished:
           this.emit(event.step.finished, message.data)
+          event.dispatcher.emit(event.step.finished, message.data)
           break
         case event.step.started:
           this.emit(event.step.started, message.data)
+          event.dispatcher.emit(event.step.started, message.data)
           break
         case event.step.passed:
           this.emit(event.step.passed, message.data)
+          event.dispatcher.emit(event.step.passed, message.data)
           break
         case event.step.failed:
           this.emit(event.step.failed, message.data, message.data.error)
+          event.dispatcher.emit(event.step.failed, message.data, message.data.error)
           break
         case event.hook.failed:
           // Hook failures are already reported as test failures by the worker
           // Just emit the hook.failed event for listeners
           this.emit(event.hook.failed, message.data)
+          event.dispatcher.emit(event.hook.failed, message.data)
+          break
+        case event.hook.passed:
+          this.emit(event.hook.passed, message.data)
+          event.dispatcher.emit(event.hook.passed, message.data)
+          break
+        case event.hook.finished:
+          this.emit(event.hook.finished, message.data)
+          event.dispatcher.emit(event.hook.finished, message.data)
           break
       }
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.0-rc.2",
+  "version": "4.0.0-rc.20",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -26,7 +26,8 @@
     "lib",
     "translations",
     "typings/**/*.d.ts",
-    "docs/webapi/**"
+    "docs/*.md",
+    "docs/helpers/**"
   ],
   "main": "lib/index.js",
   "module": "lib/index.js",
@@ -41,12 +42,15 @@
     "./els": "./lib/els.js",
     "./effects": "./lib/effects.js",
     "./steps": "./lib/steps.js",
-    "./store": "./lib/store.js"
+    "./store": "./lib/store.js",
+    "./assertions": "./lib/assertions.js"
   },
   "bin": {
-    "codeceptjs": "./bin/codecept.js"
+    "codeceptjs": "./bin/codecept.js",
+    "codeceptjs-mcp": "./bin/mcp-server.js",
+    "codeceptq": "./bin/codeceptq.js"
   },
-  "repository": "Codeception/codeceptjs",
+  "repository": "codeceptjs/CodeceptJS",
   "scripts": {
     "test-server": "node bin/test-server.js test/data/rest/db.json --host 0.0.0.0 -p 8010 --read-only",
     "test-server:writable": "node bin/test-server.js test/data/rest/db.json --host 0.0.0.0 -p 8010",
@@ -85,11 +89,12 @@
     "publish-beta": "./runok.cjs publish:next-beta-version"
   },
   "dependencies": {
-    "@codeceptjs/configure": "1.0.6",
+    "@codeceptjs/configure": "^4.0.0-beta.4",
     "@codeceptjs/helper": "2.0.4",
     "@cucumber/cucumber-expressions": "18",
     "@cucumber/gherkin": "38.0.0",
     "@cucumber/messages": "32.0.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@xmldom/xmldom": "0.9.8",
     "acorn": "8.15.0",
     "ai": "^6.0.43",
@@ -112,7 +117,6 @@
     "html-minifier-terser": "7.2.0",
     "inquirer": "^8.2.7",
     "invisi-data": "^1.0.0",
-    "joi": "18.0.2",
     "js-beautify": "1.15.4",
     "lodash.clonedeep": "4.5.0",
     "lodash.merge": "4.6.2",
@@ -128,14 +132,16 @@
     "promise-retry": "1.1.1",
     "resq": "1.11.0",
     "sprintf-js": "1.1.3",
-    "uuid": "11.1.0"
+    "uuid": "11.1.0",
+    "xpath": "0.0.34",
+    "zod": "^4.1.11"
   },
   "optionalDependencies": {
     "@codeceptjs/detox-helper": "1.1.13"
   },
   "devDependencies": {
     "@apollo/server": "^5",
-    "@codeceptjs/expect-helper": "^1.0.2",
+    "@codeceptjs/expect-helper": "^4.0.0-beta.5",
     "@codeceptjs/mock-request": "0.3.1",
     "@eslint/eslintrc": "3.3.3",
     "@eslint/js": "9.39.2",
@@ -170,7 +176,7 @@
     "jsdoc-typeof-plugin": "1.0.0",
     "json-server": "0.17.4",
     "mochawesome": "^7.1.3",
-    "playwright": "1.55.1",
+    "playwright": "^1.59.0",
     "prettier": "^3.3.2",
     "puppeteer": "24.36.0",
     "qrcode-terminal": "0.12.0",
@@ -189,8 +195,7 @@
     "typescript": "5.9.3",
     "wdio-docker-service": "3.2.1",
     "webdriverio": "9.23.0",
-    "xml2js": "0.6.2",
-    "xpath": "0.0.34"
+    "xml2js": "0.6.2"
   },
   "peerDependencies": {
     "tsx": "^4.0.0"
@@ -212,6 +217,7 @@
     }
   },
   "overrides": {
-    "tmp": "0.2.5"
+    "tmp": "0.2.5",
+    "js-yaml": "^4.1.1"
   }
 }