codeceptjs 4.0.0-rc.1 → 4.0.0-rc.11

package/lib/helper/extras/elementSelection.js

@@ -0,0 +1,58 @@
+import store from '../../store.js'
+import output from '../../output.js'
+import WebElement from '../../element/WebElement.js'
+import MultipleElementsFound from '../errors/MultipleElementsFound.js'
+
+function resolveElementIndex(value) {
+  if (value === 'first') return 1
+  if (value === 'last') return -1
+  return value
+}
+
+function isStrictStep(opts, helper) {
+  if (opts?.exact === true || opts?.strictMode === true) return true
+  if (opts?.exact === false || opts?.strictMode === false) return false
+  return helper.options.strict
+}
+
+function selectElement(els, locator, helper) {
+  const opts = store.currentStep?.opts
+  const rawIndex = opts?.elementIndex
+  const elementIndex = resolveElementIndex(rawIndex)
+
+  if (elementIndex != null) {
+    if (els.length === 1) return els[0]
+
+    if (!Number.isInteger(elementIndex) || elementIndex === 0) {
+      throw new Error(`elementIndex must be a non-zero integer or 'first'/'last', got: ${rawIndex}`)
+    }
+
+    let idx
+    if (elementIndex > 0) {
+      idx = elementIndex - 1
+      if (idx >= els.length) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    } else {
+      idx = els.length + elementIndex
+      if (idx < 0) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    }
+
+    output.debug(`[Elements] Using element #${elementIndex} out of ${els.length}`)
+    return els[idx]
+  }
+
+  if (isStrictStep(opts, helper)) {
+    if (els.length > 1) {
+      const webElements = Array.from(els).map(el => new WebElement(el, helper))
+      throw new MultipleElementsFound(locator, webElements)
+    }
+  }
+
+  if (els.length > 1) output.debug(`[Elements] Using first element out of ${els.length}`)
+  return els[0]
+}
+
+export { selectElement }

package/lib/helper/extras/focusCheck.js

@@ -0,0 +1,43 @@
+import store from '../../store.js'
+import NonFocusedType from '../errors/NonFocusedType.js'
+
+const MODIFIER_PATTERN = /^(control|ctrl|meta|cmd|command|commandorcontrol|ctrlorcommand)/i
+const EDITING_KEYS = new Set(['a', 'c', 'x', 'v', 'z', 'y'])
+
+async function isNoElementFocused(helper) {
+  return helper.executeScript(() => {
+    const ae = document.activeElement
+    return !ae || ae === document.documentElement || (ae === document.body && !ae.isContentEditable)
+  })
+}
+
+export async function checkFocusBeforeType(helper) {
+  if (!helper.options.strict && !store.debugMode) return
+  if (!await isNoElementFocused(helper)) return
+
+  const message = 'No element is in focus. Use I.click() or I.focus() to activate an element before typing.'
+  if (helper.options.strict) throw new NonFocusedType(message)
+  helper.debugSection('Warning', message)
+}
+
+export async function checkFocusBeforePressKey(helper, originalKey) {
+  if (!helper.options.strict && !store.debugMode) return
+  if (!Array.isArray(originalKey)) return
+
+  let hasCtrlOrMeta = false
+  let actionKey = null
+  for (const k of originalKey) {
+    if (MODIFIER_PATTERN.test(k)) {
+      hasCtrlOrMeta = true
+    } else {
+      actionKey = k
+    }
+  }
+  if (!hasCtrlOrMeta || !actionKey || !EDITING_KEYS.has(actionKey.toLowerCase())) return
+
+  if (!await isNoElementFocused(helper)) return
+
+  const message = `No element is in focus. Key combination with "${originalKey.join('+')}" may not work as expected. Use I.click() or I.focus() first.`
+  if (helper.options.strict) throw new NonFocusedType(message)
+  helper.debugSection('Warning', message)
+}

package/lib/helper/scripts/dropFile.js

@@ -0,0 +1,11 @@
+export const dropFile = (el, { base64Content, fileName, mimeType }) => {
+  const binaryStr = atob(base64Content)
+  const bytes = new Uint8Array(binaryStr.length)
+  for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i)
+  const fileObj = new File([bytes], fileName, { type: mimeType })
+  const dataTransfer = new DataTransfer()
+  dataTransfer.items.add(fileObj)
+  el.dispatchEvent(new DragEvent('dragenter', { dataTransfer, bubbles: true }))
+  el.dispatchEvent(new DragEvent('dragover', { dataTransfer, bubbles: true }))
+  el.dispatchEvent(new DragEvent('drop', { dataTransfer, bubbles: true }))
+}

package/lib/html.js

@@ -245,4 +245,17 @@ function splitByChunks(text, chunkSize) {
   return chunks.map(chunk => chunk.trim())
 }
 
-export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml }
+function simplifyHtmlElement(html, maxLength = 300) {
+  try {
+    html = removeNonInteractiveElements(html)
+    html = html.replace(/<html>(?:<head>.*?<\/head>)?<body>(.*)<\/body><\/html>/s, '$1').trim()
+  } catch (e) {
+    // keep raw html if minification fails
+  }
+  if (html.length > maxLength) {
+    html = html.slice(0, maxLength) + '...'
+  }
+  return html
+}
+
+export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement }

package/lib/listener/globalRetry.js

@@ -5,16 +5,27 @@ import { isNotSet } from '../utils.js'
 
 const hooks = ['Before', 'After', 'BeforeSuite', 'AfterSuite']
 
+const RETRY_PRIORITIES = {
+  MANUAL_STEP: 100,
+  STEP_PLUGIN: 50,
+  SCENARIO_CONFIG: 30,
+  FEATURE_CONFIG: 20,
+  HOOK_CONFIG: 10,
+}
+
 export default function () {
   event.dispatcher.on(event.suite.before, suite => {
     let retryConfig = Config.get('retry')
     if (!retryConfig) return
 
     if (Number.isInteger(+retryConfig)) {
-      // is number
       const retryNum = +retryConfig
       output.log(`Retries: ${retryNum}`)
-      suite.retries(retryNum)
+
+      if (suite.retries() === -1 || (suite.opts.retryPriority || 0) <= RETRY_PRIORITIES.FEATURE_CONFIG) {
+        suite.retries(retryNum)
+        suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
+      }
       return
     }
 
@@ -30,11 +41,18 @@ export default function () {
       hooks
         .filter(hook => !!config[hook])
         .forEach(hook => {
-          if (isNotSet(suite.opts[`retry${hook}`])) suite.opts[`retry${hook}`] = config[hook]
+          const retryKey = `retry${hook}`
+          if (isNotSet(suite.opts[retryKey])) {
+            suite.opts[retryKey] = config[hook]
+            suite.opts[`${retryKey}Priority`] = RETRY_PRIORITIES.HOOK_CONFIG
+          }
         })
 
       if (config.Feature) {
-        if (isNotSet(suite.retries())) suite.retries(config.Feature)
+        if (suite.retries() === -1 || (suite.opts.retryPriority || 0) <= RETRY_PRIORITIES.FEATURE_CONFIG) {
+          suite.retries(config.Feature)
+          suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
+        }
       }
 
       output.log(`Retries: ${JSON.stringify(config)}`)
@@ -46,7 +64,10 @@ export default function () {
     if (!retryConfig) return
 
     if (Number.isInteger(+retryConfig)) {
-      if (test.retries() === -1) test.retries(retryConfig)
+      if (test.retries() === -1) {
+        test.retries(retryConfig)
+        test.opts.retryPriority = RETRY_PRIORITIES.SCENARIO_CONFIG
+      }
       return
     }
 
@@ -62,9 +83,14 @@ export default function () {
       }
 
       if (config.Scenario) {
-        if (test.retries() === -1) test.retries(config.Scenario)
+        if (test.retries() === -1 || (test.opts.retryPriority || 0) <= RETRY_PRIORITIES.SCENARIO_CONFIG) {
+          test.retries(config.Scenario)
+          test.opts.retryPriority = RETRY_PRIORITIES.SCENARIO_CONFIG
+        }
         output.log(`Retries: ${config.Scenario}`)
       }
     }
   })
 }
+
+export { RETRY_PRIORITIES }

package/lib/mocha/cli.js

@@ -202,6 +202,16 @@ class Cli extends Base {
 
     // failures
     if (stats.failures) {
+      for (const test of this.failures) {
+        if (test.err && typeof test.err.fetchDetails === 'function') {
+          try {
+            await test.err.fetchDetails()
+          } catch (e) {
+            // ignore fetch errors
+          }
+        }
+      }
+
       // append step traces
       this.failures = this.failures.map(test => {
         // we will change the stack trace, so we need to clone the test

package/lib/plugin/aiTrace.js

@@ -0,0 +1,464 @@
+import crypto from 'crypto'
+import fs from 'fs'
+import { mkdirp } from 'mkdirp'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+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
+
+const defaultConfig = {
+  deleteSuccessful: false,
+  fullPageScreenshots: false,
+  output: global.output_dir,
+  captureHTML: true,
+  captureARIA: true,
+  captureBrowserLogs: true,
+  captureHTTP: true,
+  captureDebugOutput: true,
+  ignoreSteps: [],
+}
+
+/**
+ *
+ * Generates AI-friendly trace files for debugging with AI agents.
+ * This plugin creates a markdown file with test execution logs and links to all artifacts
+ * (screenshots, HTML, ARIA snapshots, browser logs, HTTP requests) for each step.
+ *
+ * #### Configuration
+ *
+ * ```js
+ * "plugins": {
+ *    "aiTrace": {
+ *      "enabled": true
+ *    }
+ *  }
+ * ```
+ *
+ * Possible config options:
+ *
+ * * `deleteSuccessful`: delete traces for successfully executed tests. Default: false.
+ * * `fullPageScreenshots`: should full page screenshots be used. Default: false.
+ * * `output`: a directory where traces should be stored. Default: `output`.
+ * * `captureHTML`: capture HTML for each step. Default: true.
+ * * `captureARIA`: capture ARIA snapshot for each step. Default: true.
+ * * `captureBrowserLogs`: capture browser console logs. Default: true.
+ * * `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.
+ *
+ * @param {*} config
+ */
+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) {
+    output.warn('aiTrace plugin: No supported helper found (Playwright, Puppeteer, WebDriver). Plugin disabled.')
+    return
+  }
+
+  let dir
+  let stepNum
+  let steps = []
+  let debugOutput = []
+  let error
+  let savedSteps = new Set()
+  let currentTest = null
+  let testStartTime
+  let currentUrl = null
+  let testFailed = false
+  let firstFailedStepSaved = false
+
+  const reportDir = config.output ? path.resolve(global.codecept_dir, config.output) : defaultConfig.output
+
+  if (config.captureDebugOutput) {
+    const originalDebug = output.debug
+    output.debug = function (...args) {
+      debugOutput.push(args.join(' '))
+      originalDebug.apply(output, args)
+    }
+  }
+
+  event.dispatcher.on(event.suite.before, suite => {
+    stepNum = -1
+  })
+
+  event.dispatcher.on(event.test.before, test => {
+    let title
+    try {
+      title = test.fullTitle ? test.fullTitle() : test.title
+    } 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}`)
+    mkdirp.sync(dir)
+    deleteDir(dir)
+    mkdirp.sync(dir)
+    stepNum = 0
+    error = null
+    steps = []
+    debugOutput = []
+    savedSteps.clear()
+    currentTest = test
+    testStartTime = Date.now()
+    currentUrl = null
+    testFailed = false
+    firstFailedStepSaved = false
+  })
+
+  event.dispatcher.on(event.step.after, step => {
+    if (!currentTest) return
+    if (step.status === 'failed') {
+      testFailed = true
+    }
+    if (step.status === 'queued' && testFailed) {
+      output.debug(`aiTrace: Skipping queued step "${step.toString()}" - testFailed: ${testFailed}`)
+      return
+    }
+    if (step.status === 'failed' && firstFailedStepSaved) {
+      output.debug(`aiTrace: Skipping failed step "${step.toString()}" - already handled by step.failed event`)
+      return
+    }
+    const stepPersistPromise = persistStep(step).catch(err => {
+      output.debug(`aiTrace: Error saving step: ${err.message}`)
+    })
+    recorder.add(`wait aiTrace step persistence: ${step.toString()}`, () => stepPersistPromise, true)
+  })
+
+  event.dispatcher.on(event.step.failed, async step => {
+    if (!currentTest) return
+    if (step.status === 'queued' && testFailed) {
+      output.debug(`aiTrace: Skipping queued failed step "${step.toString()}" - testFailed: ${testFailed}`)
+      return
+    }
+    if (firstFailedStepSaved) {
+      output.debug(`aiTrace: Skipping subsequent failed step "${step.toString()}" - already saved first failed step`)
+      return
+    }
+
+    const stepKey = step.toString()
+    if (savedSteps.has(stepKey)) {
+      const existingStep = steps.find(s => s.step === stepKey)
+      if (!existingStep) {
+        output.debug(`aiTrace: Step "${stepKey}" marked as saved but not found in steps array`)
+        return
+      }
+      existingStep.status = 'failed'
+
+      try {
+        await 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
+
+      const stepPrefix = generateStepPrefix(step, stepNum)
+      stepNum++
+
+      const stepData = {
+        step: stepKey,
+        status: 'failed',
+        prefix: stepPrefix,
+        artifacts: {},
+        meta: {},
+        debugOutput: [],
+      }
+
+      if (step.startTime && step.endTime) {
+        stepData.meta.duration = ((step.endTime - step.startTime) / 1000).toFixed(2) + 's'
+      }
+
+      savedSteps.add(stepKey)
+      steps.push(stepData)
+      firstFailedStepSaved = true
+
+      try {
+        await captureArtifactsForStep(step, stepData, stepPrefix)
+      } catch (err) {
+        output.debug(`aiTrace: Error capturing failed step artifacts: ${err.message}`)
+      }
+    }
+  })
+
+  event.dispatcher.on(event.test.passed, test => {
+    if (config.deleteSuccessful) {
+      deleteDir(dir)
+      return
+    }
+    persist(test, 'passed')
+  })
+
+  event.dispatcher.on(event.test.failed, (test, _err, hookName) => {
+    if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') {
+      return
+    }
+    persist(test, 'failed')
+  })
+
+  async function persistStep(step) {
+    if (stepNum === -1) return
+    if (isStepIgnored(step)) return
+    if (step.metaStep && step.metaStep.name === 'BeforeSuite') return
+
+    const stepKey = step.toString()
+
+    if (savedSteps.has(stepKey)) {
+      const existingStep = steps.find(s => s.step === stepKey)
+      if (existingStep && step.status === 'failed') {
+        existingStep.status = 'failed'
+        step.artifacts = {}
+        await captureArtifactsForStep(step, existingStep, existingStep.prefix)
+      }
+      return
+    }
+    savedSteps.add(stepKey)
+
+    const stepPrefix = generateStepPrefix(step, stepNum)
+    stepNum++
+
+    const stepData = {
+      step: step.toString(),
+      status: step.status,
+      prefix: stepPrefix,
+      artifacts: {},
+      meta: {},
+      debugOutput: [],
+    }
+
+    if (step.startTime && step.endTime) {
+      stepData.meta.duration = ((step.endTime - step.startTime) / 1000).toFixed(2) + 's'
+    }
+
+    if (config.captureDebugOutput && debugOutput.length > 0) {
+      stepData.debugOutput = [...debugOutput]
+      debugOutput = []
+    }
+
+    await captureArtifactsForStep(step, stepData, stepPrefix)
+    steps.push(stepData)
+  }
+
+  async function captureArtifactsForStep(step, stepData, stepPrefix) {
+    if (!step.artifacts) {
+      step.artifacts = {}
+    }
+
+    let browserAvailable = true
+
+    try {
+      try {
+        if (helper.grabCurrentUrl) {
+          const url = await helper.grabCurrentUrl()
+          stepData.meta.url = url
+          currentUrl = url
+        }
+      } catch (err) {
+        browserAvailable = false
+        output.debug(`aiTrace: Browser unavailable, partial artifact capture: ${err.message}`)
+      }
+
+      if (step.artifacts?.screenshot) {
+        const screenshotPath = path.isAbsolute(step.artifacts.screenshot)
+          ? step.artifacts.screenshot
+          : path.resolve(dir, step.artifacts.screenshot)
+        const screenshotFile = path.basename(screenshotPath)
+        stepData.artifacts.screenshot = screenshotFile
+        step.artifacts.screenshot = screenshotPath
+
+        if (!fs.existsSync(screenshotPath)) {
+          try {
+            await helper.saveScreenshot(screenshotPath, config.fullPageScreenshots)
+          } catch (err) {
+            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
+        }
+      }
+
+      // 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}`)
+        }
+      }
+
+      // 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}`)
+        }
+      }
+    } catch (err) {
+      output.plugin(`aiTrace: Can't save step artifacts: ${err}`)
+    }
+  }
+
+  function persist(test, status) {
+    if (!steps.length) {
+      output.debug('aiTrace: No steps to save in trace')
+      return
+    }
+
+    const testDuration = ((Date.now() - testStartTime) / 1000).toFixed(2)
+
+    let markdown = `file: ${test.file || 'unknown'}\n`
+    markdown += `name: ${test.title}\n`
+    markdown += `time: ${testDuration}s\n`
+    markdown += `---\n\n`
+
+    if (status === 'failed') {
+      if (test.art && test.art.message) {
+        markdown += `Error: ${test.art.message}\n\n`
+      }
+      if (test.art && test.art.stack) {
+        markdown += `${test.art.stack}\n\n`
+      }
+      markdown += `---\n\n`
+    }
+
+    if (config.captureDebugOutput && debugOutput.length > 0) {
+      markdown += `CodeceptJS Debug Output:\n\n`
+      debugOutput.forEach(line => {
+        markdown += `> ${line}\n`
+      })
+      markdown += `\n---\n\n`
+    }
+
+    steps.forEach((stepData, index) => {
+      const stepAnchor = clearString(stepData.step).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 50)
+      markdown += `### Step ${index + 1}: ${stepData.step}\n`
+      markdown += `<a id="${stepAnchor}"></a>\n`
+
+      if (stepData.meta.duration) {
+        markdown += `  > duration: ${stepData.meta.duration}\n`
+      }
+
+      if (stepData.meta.url) {
+        markdown += `  > navigated to ${stepData.meta.url}\n`
+      }
+
+      if (config.captureDebugOutput && stepData.debugOutput && stepData.debugOutput.length > 0) {
+        stepData.debugOutput.forEach(line => {
+          markdown += `  > ${line}\n`
+        })
+      }
+
+      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`
+      }
+
+      if (config.captureHTTP) {
+        if (test.artifacts && test.artifacts.har) {
+          const harPath = path.relative(reportDir, test.artifacts.har)
+          markdown += `  > HTTP: see [HAR file](../${harPath}) for network requests\n`
+        } else if (test.artifacts && test.artifacts.trace) {
+          const tracePath = path.relative(reportDir, test.artifacts.trace)
+          markdown += `  > HTTP: see [Playwright trace](../${tracePath}) for network requests\n`
+        }
+      }
+
+      markdown += `\n`
+    })
+
+    const traceFile = path.join(dir, 'trace.md')
+    fs.writeFileSync(traceFile, markdown)
+
+    output.print(`🤖 AI Trace: ${colors.white.bold(`file://${traceFile}`)}`)
+
+    if (!test.artifacts) test.artifacts = {}
+    test.artifacts.aiTrace = traceFile
+  }
+
+  function isStepIgnored(step) {
+    if (!config.ignoreSteps) return false
+    for (const pattern of config.ignoreSteps || []) {
+      if (step.name.match(pattern)) return true
+    }
+    return false
+  }
+
+  function generateStepPrefix(step, index) {
+    const stepName = step.toString()
+    const cleanedName = clearString(stepName)
+      .replace(/[^a-zA-Z0-9_-]/g, '_')
+      .replace(/_{2,}/g, '_')
+      .slice(0, 80)
+      .trim()
+
+    return `${String(index).padStart(4, '0')}_${cleanedName}`
+  }
+}