fix bug and add test support to testomatio

Author: DenysKuchma

docs/aitrace.md

@@ -51,16 +51,18 @@ For each test, a `trace_<sha256>` directory is created with the following files:
 
 **trace.md** - AI-friendly markdown file with test execution history
 
-**0000_screenshot.png** - Screenshot for each step
+**0000_step_name_screenshot.png** - Screenshot for each step (file names include step names)
 
-**0000_page.html** - Full HTML of the page at each step
+**0000_step_name_page.html** - Full HTML of the page at each step
 
-**0000_aria.txt** - ARIA accessibility snapshot (AI-readable structure without HTML noise)
+**0000_step_name_aria.txt** - ARIA accessibility snapshot (AI-readable structure without HTML noise)
 
-**0000_console.json** - Browser console logs
+**0000_step_name_console.json** - Browser console logs
 
 When HAR or trace recording is enabled in your helper config, links to those files are also included.
 
+**Note:** Artifact files are named using step names for easier identification (e.g., `0000_I_see_Product_screenshot.png` instead of just `0000_screenshot.png`).
+
 ## Trace File Format
 
 The `trace.md` file contains a structured execution log with links to all artifacts:
@@ -73,20 +75,22 @@ time: 3.45s
 
 I am on page "https://example.com"
   > navigated to https://example.com/
-  > [HTML](./0000_page.html)
-  > [ARIA Snapshot](./0000_aria.txt)
-  > [Screenshot](./0000_screenshot.png)
-  > [Browser Logs](0000_console.json) (7 entries)
+  > [HTML](./0000_I_am_on_page_https_example.com_page.html)
+  > [ARIA Snapshot](./0000_I_am_on_page_https_example.com_aria.txt)
+  > [Screenshot](./0000_I_am_on_page_https_example.com_screenshot.png)
+  > [Browser Logs](./0000_I_am_on_page_https_example.com_console.json) (7 entries)
   > HTTP: see [HAR file](../har/...) for network requests
 
 I see "Welcome"
   > navigated to https://example.com/
-  > [HTML](./0001_page.html)
-  > [ARIA Snapshot](./0001_aria.txt)
-  > [Screenshot](./0001_screenshot.png)
-  > [Browser Logs](0001_console.json) (0 entries)
+  > [HTML](./0001_I_see_Welcome_page.html)
+  > [ARIA Snapshot](./0001_I_see_Welcome_aria.txt)
+  > [Screenshot](./0001_I_see_Welcome_screenshot.png)
+  > [Browser Logs](./0001_I_see_Welcome_console.json) (0 entries)
 ```
 
+Files are named with step descriptions for easier navigation and debugging.
+
 ## Configuration
 
 ### Basic Configuration

docs/plugins.md

@@ -103,10 +103,12 @@ exports.config = {
 For each test, a `trace_<sha256>` directory is created with:
 
 *   **trace.md** - AI-friendly markdown file with test execution history
-*   **0000_screenshot.png** - screenshot for each step
-*   **0000_page.html** - full HTML of the page at each step
-*   **0000_aria.txt** - ARIA accessibility snapshot (AI-readable structure)
-*   **0000_console.json** - browser console logs
+*   **0000_step_name_screenshot.png** - screenshot for each step (named with step description)
+*   **0000_step_name_page.html** - full HTML of the page at each step
+*   **0000_step_name_aria.txt** - ARIA accessibility snapshot (AI-readable structure)
+*   **0000_step_name_console.json** - browser console logs
+
+Artifact files include step names for easier identification (e.g., `0000_I_see_Product_screenshot.png`).
 
 When HAR or trace recording is enabled in your helper config, links to those files are also included.
 
@@ -120,20 +122,22 @@ time: 3.45s
 
 I am on page "https://example.com"
   > navigated to https://example.com/
-  > [HTML](./0000_page.html)
-  > [ARIA Snapshot](./0000_aria.txt)
-  > [Screenshot](./0000_screenshot.png)
-  > [Browser Logs](0000_console.json) (7 entries)
+  > [HTML](./0000_I_am_on_page_https_example.com_page.html)
+  > [ARIA Snapshot](./0000_I_am_on_page_https_example.com_aria.txt)
+  > [Screenshot](./0000_I_am_on_page_https_example.com_screenshot.png)
+  > [Browser Logs](./0000_I_am_on_page_https_example.com_console.json) (7 entries)
   > HTTP: see [HAR file](../har/...) for network requests
 
 I see "Welcome"
   > navigated to https://example.com/
-  > [HTML](./0001_page.html)
-  > [ARIA Snapshot](./0001_aria.txt)
-  > [Screenshot](./0001_screenshot.png)
-  > [Browser Logs](0001_console.json) (0 entries)
+  > [HTML](./0001_I_see_Welcome_page.html)
+  > [ARIA Snapshot](./0001_I_see_Welcome_aria.txt)
+  > [Screenshot](./0001_I_see_Welcome_screenshot.png)
+  > [Browser Logs](./0001_I_see_Welcome_console.json) (0 entries)
 ```
 
+Files are named with step descriptions for easier identification.
+
 #### Best Practices
 
 **Save disk space** - Only keep traces for failed tests:

lib/plugin/aiTrace.js

@@ -81,6 +81,8 @@ export default function (config) {
   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
 
@@ -111,6 +113,8 @@ export default function (config) {
       .slice(0, 8)
     dir = path.join(reportDir, `trace_${testTitle}_${uniqueHash}`)
     mkdirp.sync(dir)
+    deleteDir(dir)
+    mkdirp.sync(dir)
     stepNum = 0
     error = null
     steps = []
@@ -119,16 +123,88 @@ export default function (config) {
     currentTest = test
     testStartTime = Date.now()
     currentUrl = null
+    testFailed = false
+    firstFailedStepSaved = false
   })
 
-  event.dispatcher.on(event.step.after, step => {
+  event.dispatcher.on(event.step.after, async step => {
     if (!currentTest) return
-    recorder.add('save ai trace step', async () => persistStep(step), true)
+    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
+    }
+    recorder.add(`save artifacts for step ${step.toString()}`, async () => {
+      try {
+        await persistStep(step)
+      } catch (err) {
+        output.debug(`aiTrace: Error saving step: ${err.message}`)
+      }
+    }, true)
   })
 
-  event.dispatcher.on(event.step.failed, step => {
+  event.dispatcher.on(event.step.failed, async step => {
     if (!currentTest) return
-    recorder.add('save ai trace failed step', async () => persistStep(step), true)
+    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 => {
@@ -152,16 +228,19 @@ export default function (config) {
     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 = `${String(stepNum).padStart(4, '0')}`
+    const stepPrefix = generateStepPrefix(step, stepNum)
     stepNum++
 
     const stepData = {
@@ -182,28 +261,44 @@ export default function (config) {
       debugOutput = []
     }
 
+    await captureArtifactsForStep(step, stepData, stepPrefix)
+    steps.push(stepData)
+  }
+
+  async function captureArtifactsForStep(step, stepData, stepPrefix) {
+    if (!step.artifacts) {
+      step.artifacts = {}
+    }
+
+    let browserAvailable = true
+
     try {
-      if (helper.grabCurrentUrl) {
-        try {
+      try {
+        if (helper.grabCurrentUrl) {
           const url = await helper.grabCurrentUrl()
           stepData.meta.url = url
           currentUrl = url
-        } catch (err) {
-          // Ignore URL capture errors
         }
+      } catch (err) {
+        browserAvailable = false
+        output.debug(`aiTrace: Browser unavailable, partial artifact capture: ${err.message}`)
       }
 
-      // Save screenshot
       if (!step.artifacts?.screenshot) {
-        const screenshotFile = `${stepPrefix}_screenshot.png`
-        await helper.saveScreenshot(path.join(dir, screenshotFile), config.fullPageScreenshots)
-        stepData.artifacts.screenshot = screenshotFile
-      } else {
-        stepData.artifacts.screenshot = step.artifacts.screenshot
+        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) {
+      if (config.captureHTML && helper.grabSource && browserAvailable) {
         if (!step.artifacts?.html) {
           try {
             const html = await helper.grabSource()
@@ -219,7 +314,7 @@ export default function (config) {
       }
 
       // Save ARIA snapshot
-      if (config.captureARIA && helper.grabAriaSnapshot) {
+      if (config.captureARIA && helper.grabAriaSnapshot && browserAvailable) {
         try {
           const aria = await helper.grabAriaSnapshot()
           const ariaFile = `${stepPrefix}_aria.txt`
@@ -231,7 +326,7 @@ export default function (config) {
       }
 
       // Save browser logs
-      if (config.captureBrowserLogs && helper.grabBrowserLogs) {
+      if (config.captureBrowserLogs && helper.grabBrowserLogs && browserAvailable) {
         try {
           const logs = await helper.grabBrowserLogs()
           const logsFile = `${stepPrefix}_console.json`
@@ -245,8 +340,6 @@ export default function (config) {
     } catch (err) {
       output.plugin(`aiTrace: Can't save step artifacts: ${err}`)
     }
-
-    steps.push(stepData)
   }
 
   function persist(test, status) {
@@ -281,7 +374,9 @@ export default function (config) {
     }
 
     steps.forEach((stepData, index) => {
-      markdown += `${stepData.step}\n`
+      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`
@@ -343,5 +438,15 @@ export default function (config) {
     }
     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}`
+  }
+}

lib/plugin/stepByStepReport.js

@@ -207,7 +207,11 @@ export default function (config) {
     stepNum++
     slides[fileName] = step
     try {
-      await helper.saveScreenshot(path.join(dir, fileName), config.fullPageScreenshots)
+      const screenshotPath = path.join(dir, fileName)
+      await helper.saveScreenshot(screenshotPath, config.fullPageScreenshots)
+
+      step.artifacts = step.artifacts || {}
+      step.artifacts.screenshot = screenshotPath
     } catch (err) {
       output.plugin(`Can't save step screenshot: ${err}`)
       error = err