@testomatio/reporter 2.9.3 → 2.9.4

package/lib/adapter/codecept.js

@@ -135,20 +135,36 @@ function CodeceptReporter(config) {
     });
     // mark as failed all tests inside the failed hook
     event.dispatcher.on(event.hook.failed, hook => {
-        if (hook.name !== 'BeforeSuiteHook' && hook.name !== 'BeforeHook')
-            return;
-        const suite = hook.runnable.parent;
-        if (!suite)
-            return;
-        const error = hook?.ctx?.currentTest?.err;
-        for (const test of suite.tests) {
-            reportedTestUids.add(test.uid);
+        const error = hook?.ctx?.currentTest?.err || hook?.err;
+        // Handle BeforeSuite and Before hooks: mark all tests in suite as failed
+        if (hook.name === 'BeforeSuiteHook' || hook.name === 'BeforeHook') {
+            const suite = hook.runnable.parent;
+            if (!suite)
+                return;
+            for (const test of suite.tests) {
+                reportedTestUids.add(test.uid);
+                const reportTestPromise = client.addTestRun('failed', {
+                    ...stripExampleFromTitle(test.title),
+                    rid: test.uid,
+                    test_id: (0, utils_js_1.getTestomatIdFromTestTitle)(test.title),
+                    suite_title: stripTagsFromTitle(suite.title),
+                    error,
+                    time: hook?.runnable?.duration,
+                });
+                reportTestPromises.push(reportTestPromise);
+            }
+        }
+        if (hook.name === 'AfterSuiteHook') {
+            const suite = hook.runnable?.parent || hook.suite;
+            const suiteTitle = suite ? stripTagsFromTitle(suite.title) : 'Unknown Suite';
+            const stepHierarchy = buildUnifiedStepHierarchy(null, hookSteps);
+            // Report the hook failure as a separate test entry
             const reportTestPromise = client.addTestRun('failed', {
-                ...stripExampleFromTitle(test.title),
-                rid: test.uid,
-                test_id: (0, utils_js_1.getTestomatIdFromTestTitle)(test.title),
-                suite_title: stripTagsFromTitle(suite.title),
+                title: 'AfterSuite Hook',
+                suite_title: suiteTitle,
                 error,
+                message: error?.message || 'AfterSuite hook failed',
+                steps: stepHierarchy,
                 time: hook?.runnable?.duration,
             });
             reportTestPromises.push(reportTestPromise);
@@ -169,8 +185,10 @@ function CodeceptReporter(config) {
         testTimeMap[test.uid] = Date.now();
     });
     event.dispatcher.on(event.all.after, () => {
-        recorder.add('Finishing run', async () => {
-            await finalizeRun('all.after');
+        setImmediate(() => {
+            finalizeRun('all.after').catch(err => {
+                debug('Error finalizing run:', err);
+            });
         });
     });
     event.dispatcher.on(event.test.skipped, test => {

package/lib/pipe/html.d.ts

@@ -6,6 +6,7 @@ declare class HtmlPipe {
     description: any;
     apiKey: any;
     isHtml: any;
+    htmlCopyArtifacts: any;
     isEnabled: boolean;
     htmlOutputPath: string;
     filenameMsg: string;

package/lib/pipe/html.js

@@ -15,6 +15,7 @@ const utils_js_1 = require("../utils/utils.js");
 const constants_js_1 = require("../constants.js");
 const node_url_1 = require("node:url");
 const debug = (0, debug_1.default)('@testomatio/reporter:pipe:html');
+const HTML_ARTIFACTS_DIR = 'artifacts';
 // @ts-ignore – this line will be removed in compiled code (already defined in the global scope of commonjs)
 class HtmlPipe {
     constructor(params, store = {}) {
@@ -23,6 +24,7 @@ class HtmlPipe {
         this.description = params.description || process.env.TESTOMATIO_DESCRIPTION;
         this.apiKey = params.apiKey || process.env.TESTOMATIO;
         this.isHtml = params.html ?? process.env.TESTOMATIO_HTML_REPORT_SAVE;
+        this.htmlCopyArtifacts = params.htmlCopyArtifacts;
         debug('HTML Pipe: ', this.apiKey ? 'API KEY' : '*no api key provided*');
         this.isEnabled = false;
         this.htmlOutputPath = '';
@@ -124,6 +126,8 @@ class HtmlPipe {
             console.log(picocolors_1.default.blue(msg));
         }
         const aggregatedTests = aggregateTestRetries(tests);
+        const copyLocalArtifacts = resolveHtmlCopyArtifacts(this.htmlCopyArtifacts);
+        const portableArtifacts = new Map();
         aggregatedTests.forEach(test => {
             const logsRaw = test.logs || test.meta?.logs || test.meta?.console || test.meta?.stdout || test.meta?.stderr || '';
             const stackRaw = test.stack || '';
@@ -180,7 +184,11 @@ class HtmlPipe {
             if (!test.title?.trim()) {
                 test.title = 'Unknown test title';
             }
+            test.title = buildExampleTitle(test.title, test.example);
             test.artifacts = normalizeArtifacts(test);
+            if (copyLocalArtifacts) {
+                makeLocalArtifactsPortable(test, outputPath, portableArtifacts);
+            }
             const allPossibleArtifacts = [
                 ...(test.artifacts || []),
                 ...(test.manuallyAttachedArtifacts || []),
@@ -373,6 +381,20 @@ function parseRetryInfo(test) {
             test.retries.retryCount = n;
     }
 }
+function buildExampleTitle(title, example) {
+    if (example == null)
+        return title;
+    let exampleText;
+    try {
+        exampleText = JSON.stringify(example);
+    }
+    catch (e) {
+        return title;
+    }
+    if (!exampleText || title.includes(exampleText))
+        return title;
+    return `${title} | ${exampleText}`;
+}
 function escapeHtml(str = '') {
     return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -864,51 +886,7 @@ function normalizeArtifacts(test) {
         ...(test.meta?.manuallyAttachedArtifacts || []),
     ];
     return allArtifacts
-        .map(artifact => {
-        if (typeof artifact === 'string') {
-            if (/^https?:\/\//i.test(artifact)) {
-                const base = path_1.default.basename(new URL(artifact).pathname) || artifact;
-                return {
-                    name: base,
-                    title: base,
-                    path: artifact,
-                    fsPath: null,
-                    relativePath: artifact,
-                };
-            }
-            const abs = path_1.default.isAbsolute(artifact) ? artifact : path_1.default.resolve(process.cwd(), artifact);
-            const href = artifact.startsWith('file://') ? artifact : (0, file_url_1.default)(abs, { resolve: true });
-            const base = path_1.default.basename(abs);
-            return {
-                name: base,
-                title: base,
-                path: href,
-                fsPath: abs,
-                relativePath: artifact,
-            };
-        }
-        if (artifact?.path) {
-            const raw = String(artifact.path);
-            const isFileUrl = raw.startsWith('file://');
-            const isHttpUrl = /^https?:\/\//i.test(raw);
-            const abs = isFileUrl || isHttpUrl ? null : path_1.default.isAbsolute(raw) ? raw : path_1.default.resolve(process.cwd(), raw);
-            const href = isFileUrl || isHttpUrl ? raw : (0, file_url_1.default)(abs, { resolve: true });
-            const base = abs
-                ? path_1.default.basename(abs)
-                : isHttpUrl
-                    ? path_1.default.basename(new URL(raw).pathname) || artifact.name || artifact.title || 'attachment'
-                    : artifact.name || artifact.title || 'attachment';
-            return {
-                ...artifact,
-                name: artifact.name || artifact.title || base,
-                title: artifact.title || artifact.name || base,
-                path: href,
-                fsPath: abs || artifact.fsPath || null,
-                relativePath: artifact.relativePath || raw,
-            };
-        }
-        return artifact;
-    })
+        .map(normalizeArtifact)
         .filter(Boolean)
         .filter(artifact => {
         const isTrace = (artifact.title === 'trace' || artifact.name === 'trace') &&
@@ -918,6 +896,135 @@ function normalizeArtifacts(test) {
         return !isTrace;
     });
 }
+function resolveHtmlCopyArtifacts(value) {
+    if (value !== undefined)
+        return (0, utils_js_1.transformEnvVarToBoolean)(value);
+    if (process.env.TESTOMATIO_HTML_REPORT_COPY_ARTIFACTS !== undefined) {
+        return (0, utils_js_1.transformEnvVarToBoolean)(process.env.TESTOMATIO_HTML_REPORT_COPY_ARTIFACTS);
+    }
+    return !isS3ArtifactsUploadEnabled();
+}
+function isS3ArtifactsUploadEnabled() {
+    return Boolean(process.env.S3_BUCKET && !(0, utils_js_1.transformEnvVarToBoolean)(process.env.TESTOMATIO_DISABLE_ARTIFACTS));
+}
+function normalizeArtifact(artifact) {
+    if (typeof artifact === 'string') {
+        return normalizeArtifactPath({ raw: artifact });
+    }
+    if (artifact?.path) {
+        return normalizeArtifactPath({
+            raw: String(artifact.path),
+            artifact,
+        });
+    }
+    return artifact;
+}
+/**
+ * @param {{
+ *   raw: string,
+ *   artifact?: { name?: string, title?: string, relativePath?: string, [key: string]: any }
+ * }} params
+ */
+function normalizeArtifactPath({ raw, artifact = {} }) {
+    const url = parseUrl(raw);
+    const fsPath = getLocalArtifactPath(raw, url);
+    const base = getArtifactBaseName({ raw, url, fsPath, artifact });
+    const href = fsPath && url?.protocol !== 'file:' ? (0, file_url_1.default)(fsPath, { resolve: true }) : raw;
+    return {
+        ...artifact,
+        name: artifact.name || artifact.title || base,
+        title: artifact.title || artifact.name || base,
+        path: href,
+        fsPath,
+        relativePath: artifact.relativePath || raw,
+    };
+}
+function makeLocalArtifactsPortable(test, outputPath, portableArtifacts) {
+    const reportDir = path_1.default.dirname(path_1.default.resolve(outputPath));
+    test.artifacts = makeArtifactsPortable(test.artifacts, reportDir, portableArtifacts);
+    if (Array.isArray(test.stepsArray)) {
+        makeStepArtifactsPortable(test.stepsArray, reportDir, portableArtifacts);
+    }
+}
+function makeStepArtifactsPortable(steps, reportDir, portableArtifacts) {
+    steps.forEach(step => {
+        if (Array.isArray(step.artifacts)) {
+            const normalizedArtifacts = step.artifacts.map(normalizeArtifact).filter(Boolean);
+            step.artifacts = makeArtifactsPortable(normalizedArtifacts, reportDir, portableArtifacts);
+        }
+        if (Array.isArray(step.steps)) {
+            makeStepArtifactsPortable(step.steps, reportDir, portableArtifacts);
+        }
+    });
+}
+function makeArtifactsPortable(artifacts, reportDir, portableArtifacts) {
+    if (!Array.isArray(artifacts))
+        return artifacts;
+    return artifacts.map(artifact => {
+        const fsPath = artifact?.fsPath;
+        if (!fsPath || !fs_1.default.existsSync(fsPath))
+            return artifact;
+        const relativePath = copyArtifactToReport(fsPath, reportDir, portableArtifacts);
+        return { ...artifact, path: relativePath, relativePath };
+    });
+}
+function copyArtifactToReport(fsPath, reportDir, portableArtifacts) {
+    const absoluteSource = path_1.default.resolve(fsPath);
+    if (portableArtifacts.has(absoluteSource))
+        return portableArtifacts.get(absoluteSource);
+    const artifactsDir = path_1.default.join(reportDir, HTML_ARTIFACTS_DIR);
+    const ext = path_1.default.extname(absoluteSource);
+    const baseName = path_1.default.basename(absoluteSource, ext) || 'attachment';
+    let destinationPath = path_1.default.join(artifactsDir, `${baseName}${ext}`);
+    let index = 1;
+    while (Array.from(portableArtifacts.values()).includes(getRelativeArtifactPath(reportDir, destinationPath))) {
+        destinationPath = path_1.default.join(artifactsDir, `${baseName}-${index}${ext}`);
+        index += 1;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(destinationPath), { recursive: true });
+    fs_1.default.copyFileSync(absoluteSource, destinationPath);
+    const relativePath = getRelativeArtifactPath(reportDir, destinationPath);
+    portableArtifacts.set(absoluteSource, relativePath);
+    return relativePath;
+}
+function getLocalArtifactPath(raw, url = parseUrl(raw)) {
+    if (path_1.default.isAbsolute(raw))
+        return raw;
+    if (isRemoteUrl(url))
+        return null;
+    if (url?.protocol === 'file:') {
+        try {
+            return (0, node_url_1.fileURLToPath)(url);
+        }
+        catch (_) {
+            return null;
+        }
+    }
+    if (url)
+        return null;
+    return path_1.default.resolve(process.cwd(), raw);
+}
+function getArtifactBaseName({ raw, url, fsPath, artifact }) {
+    if (fsPath)
+        return path_1.default.basename(fsPath);
+    if (url?.pathname)
+        return path_1.default.basename(url.pathname) || artifact.name || artifact.title || 'attachment';
+    return artifact.name || artifact.title || path_1.default.basename(raw) || 'attachment';
+}
+function parseUrl(value) {
+    try {
+        return new URL(String(value));
+    }
+    catch (_) {
+        return null;
+    }
+}
+function isRemoteUrl(url) {
+    return url?.protocol === 'http:' || url?.protocol === 'https:';
+}
+function getRelativeArtifactPath(reportDir, artifactPath) {
+    return `./${String(path_1.default.relative(reportDir, artifactPath)).split(path_1.default.sep).join('/')}`;
+}
 /**
  * Loads trace files from test.files and converts them to base64 data URLs
  * @param {object} test - Test object with files array

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/reporter",
-  "version": "2.9.3",
+  "version": "2.9.4",
   "description": "Testomatio Reporter Client",
   "engines": {
     "node": ">=18"

package/src/adapter/codecept.js

@@ -154,21 +154,40 @@ function CodeceptReporter(config) {
 
   // mark as failed all tests inside the failed hook
   event.dispatcher.on(event.hook.failed, hook => {
-    if (hook.name !== 'BeforeSuiteHook' && hook.name !== 'BeforeHook') return;
-    const suite = hook.runnable.parent;
+    const error = hook?.ctx?.currentTest?.err || hook?.err;
+
+    // Handle BeforeSuite and Before hooks: mark all tests in suite as failed
+    if (hook.name === 'BeforeSuiteHook' || hook.name === 'BeforeHook') {
+      const suite = hook.runnable.parent;
+      if (!suite) return;
+
+      for (const test of suite.tests) {
+        reportedTestUids.add(test.uid);
+        const reportTestPromise = client.addTestRun('failed', {
+          ...stripExampleFromTitle(test.title),
+          rid: test.uid,
+          test_id: getTestomatIdFromTestTitle(test.title),
+          suite_title: stripTagsFromTitle(suite.title),
+          error,
+          time: hook?.runnable?.duration,
+        });
+        reportTestPromises.push(reportTestPromise);
+      }
+    }
 
-    if (!suite) return;
+    if (hook.name === 'AfterSuiteHook') {
+      const suite = hook.runnable?.parent || hook.suite;
+      const suiteTitle = suite ? stripTagsFromTitle(suite.title) : 'Unknown Suite';
 
-    const error = hook?.ctx?.currentTest?.err;
+      const stepHierarchy = buildUnifiedStepHierarchy(null, hookSteps);
 
-    for (const test of suite.tests) {
-      reportedTestUids.add(test.uid);
+      // Report the hook failure as a separate test entry
       const reportTestPromise = client.addTestRun('failed', {
-        ...stripExampleFromTitle(test.title),
-        rid: test.uid,
-        test_id: getTestomatIdFromTestTitle(test.title),
-        suite_title: stripTagsFromTitle(suite.title),
+        title: 'AfterSuite Hook',
+        suite_title: suiteTitle,
         error,
+        message: error?.message || 'AfterSuite hook failed',
+        steps: stepHierarchy,
         time: hook?.runnable?.duration,
       });
       reportTestPromises.push(reportTestPromise);
@@ -194,8 +213,10 @@ function CodeceptReporter(config) {
   });
 
   event.dispatcher.on(event.all.after, () => {
-    recorder.add('Finishing run', async () => {
-      await finalizeRun('all.after');
+    setImmediate(() => {
+      finalizeRun('all.after').catch(err => {
+        debug('Error finalizing run:', err);
+      });
     });
   });
 

package/src/pipe/html.js

@@ -6,11 +6,12 @@ import pc from 'picocolors';
 import handlebars from 'handlebars';
 import { marked } from 'marked';
 import fileUrl from 'file-url';
-import { fileSystem, isSameTest, ansiRegExp, formatStep } from '../utils/utils.js';
+import { fileSystem, isSameTest, ansiRegExp, formatStep, transformEnvVarToBoolean } from '../utils/utils.js';
 import { HTML_REPORT } from '../constants.js';
 import { fileURLToPath } from 'node:url';
 
 const debug = createDebugMessages('@testomatio/reporter:pipe:html');
+const HTML_ARTIFACTS_DIR = 'artifacts';
 
 // @ts-ignore – this line will be removed in compiled code (already defined in the global scope of commonjs)
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -22,6 +23,7 @@ class HtmlPipe {
     this.description = params.description || process.env.TESTOMATIO_DESCRIPTION;
     this.apiKey = params.apiKey || process.env.TESTOMATIO;
     this.isHtml = params.html ?? process.env.TESTOMATIO_HTML_REPORT_SAVE;
+    this.htmlCopyArtifacts = params.htmlCopyArtifacts;
 
     debug('HTML Pipe: ', this.apiKey ? 'API KEY' : '*no api key provided*');
 
@@ -151,6 +153,8 @@ class HtmlPipe {
 
     const aggregatedTests = aggregateTestRetries(tests);
 
+    const copyLocalArtifacts = resolveHtmlCopyArtifacts(this.htmlCopyArtifacts);
+    const portableArtifacts = new Map();
     aggregatedTests.forEach(test => {
       const logsRaw =
         test.logs || test.meta?.logs || test.meta?.console || test.meta?.stdout || test.meta?.stderr || '';
@@ -228,7 +232,12 @@ class HtmlPipe {
         test.title = 'Unknown test title';
       }
 
+      test.title = buildExampleTitle(test.title, test.example);
+
       test.artifacts = normalizeArtifacts(test);
+      if (copyLocalArtifacts) {
+        makeLocalArtifactsPortable(test, outputPath, portableArtifacts);
+      }
 
       const allPossibleArtifacts = [
         ...(test.artifacts || []),
@@ -460,6 +469,21 @@ function parseRetryInfo(test) {
   }
 }
 
+function buildExampleTitle(title, example) {
+  if (example == null) return title;
+
+  let exampleText;
+  try {
+    exampleText = JSON.stringify(example);
+  } catch (e) {
+    return title;
+  }
+
+  if (!exampleText || title.includes(exampleText)) return title;
+
+  return `${title} | ${exampleText}`;
+}
+
 function escapeHtml(str = '') {
   return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -1013,57 +1037,7 @@ function normalizeArtifacts(test) {
   ];
 
   return allArtifacts
-    .map(artifact => {
-      if (typeof artifact === 'string') {
-        if (/^https?:\/\//i.test(artifact)) {
-          const base = path.basename(new URL(artifact).pathname) || artifact;
-
-          return {
-            name: base,
-            title: base,
-            path: artifact,
-            fsPath: null,
-            relativePath: artifact,
-          };
-        }
-
-        const abs = path.isAbsolute(artifact) ? artifact : path.resolve(process.cwd(), artifact);
-        const href = artifact.startsWith('file://') ? artifact : fileUrl(abs, { resolve: true });
-        const base = path.basename(abs);
-
-        return {
-          name: base,
-          title: base,
-          path: href,
-          fsPath: abs,
-          relativePath: artifact,
-        };
-      }
-
-      if (artifact?.path) {
-        const raw = String(artifact.path);
-        const isFileUrl = raw.startsWith('file://');
-        const isHttpUrl = /^https?:\/\//i.test(raw);
-        const abs = isFileUrl || isHttpUrl ? null : path.isAbsolute(raw) ? raw : path.resolve(process.cwd(), raw);
-        const href = isFileUrl || isHttpUrl ? raw : fileUrl(abs, { resolve: true });
-        const base = abs
-          ? path.basename(abs)
-          : isHttpUrl
-            ? path.basename(new URL(raw).pathname) || artifact.name || artifact.title || 'attachment'
-            : artifact.name || artifact.title || 'attachment';
-
-        return {
-          ...artifact,
-          name: artifact.name || artifact.title || base,
-          title: artifact.title || artifact.name || base,
-          path: href,
-          fsPath: abs || artifact.fsPath || null,
-          relativePath: artifact.relativePath || raw,
-        };
-      }
-
-      return artifact;
-    })
+    .map(normalizeArtifact)
     .filter(Boolean)
     .filter(artifact => {
       const isTrace = (artifact.title === 'trace' || artifact.name === 'trace') &&
@@ -1074,6 +1048,151 @@ function normalizeArtifacts(test) {
     });
 }
 
+function resolveHtmlCopyArtifacts(value) {
+  if (value !== undefined) return transformEnvVarToBoolean(value);
+  if (process.env.TESTOMATIO_HTML_REPORT_COPY_ARTIFACTS !== undefined) {
+    return transformEnvVarToBoolean(process.env.TESTOMATIO_HTML_REPORT_COPY_ARTIFACTS);
+  }
+  return !isS3ArtifactsUploadEnabled();
+}
+
+function isS3ArtifactsUploadEnabled() {
+  return Boolean(process.env.S3_BUCKET && !transformEnvVarToBoolean(process.env.TESTOMATIO_DISABLE_ARTIFACTS));
+}
+
+function normalizeArtifact(artifact) {
+  if (typeof artifact === 'string') {
+    return normalizeArtifactPath({ raw: artifact });
+  }
+
+  if (artifact?.path) {
+    return normalizeArtifactPath({
+      raw: String(artifact.path),
+      artifact,
+    });
+  }
+
+  return artifact;
+}
+
+/**
+ * @param {{
+ *   raw: string,
+ *   artifact?: { name?: string, title?: string, relativePath?: string, [key: string]: any }
+ * }} params
+ */
+function normalizeArtifactPath({ raw, artifact = {} }) {
+  const url = parseUrl(raw);
+  const fsPath = getLocalArtifactPath(raw, url);
+  const base = getArtifactBaseName({ raw, url, fsPath, artifact });
+  const href = fsPath && url?.protocol !== 'file:' ? fileUrl(fsPath, { resolve: true }) : raw;
+
+  return {
+    ...artifact,
+    name: artifact.name || artifact.title || base,
+    title: artifact.title || artifact.name || base,
+    path: href,
+    fsPath,
+    relativePath: artifact.relativePath || raw,
+  };
+}
+
+function makeLocalArtifactsPortable(test, outputPath, portableArtifacts) {
+  const reportDir = path.dirname(path.resolve(outputPath));
+
+  test.artifacts = makeArtifactsPortable(test.artifacts, reportDir, portableArtifacts);
+
+  if (Array.isArray(test.stepsArray)) {
+    makeStepArtifactsPortable(test.stepsArray, reportDir, portableArtifacts);
+  }
+}
+
+function makeStepArtifactsPortable(steps, reportDir, portableArtifacts) {
+  steps.forEach(step => {
+    if (Array.isArray(step.artifacts)) {
+      const normalizedArtifacts = step.artifacts.map(normalizeArtifact).filter(Boolean);
+      step.artifacts = makeArtifactsPortable(normalizedArtifacts, reportDir, portableArtifacts);
+    }
+
+    if (Array.isArray(step.steps)) {
+      makeStepArtifactsPortable(step.steps, reportDir, portableArtifacts);
+    }
+  });
+}
+
+function makeArtifactsPortable(artifacts, reportDir, portableArtifacts) {
+  if (!Array.isArray(artifacts)) return artifacts;
+
+  return artifacts.map(artifact => {
+    const fsPath = artifact?.fsPath;
+    if (!fsPath || !fs.existsSync(fsPath)) return artifact;
+
+    const relativePath = copyArtifactToReport(fsPath, reportDir, portableArtifacts);
+    return { ...artifact, path: relativePath, relativePath };
+  });
+}
+
+function copyArtifactToReport(fsPath, reportDir, portableArtifacts) {
+  const absoluteSource = path.resolve(fsPath);
+  if (portableArtifacts.has(absoluteSource)) return portableArtifacts.get(absoluteSource);
+
+  const artifactsDir = path.join(reportDir, HTML_ARTIFACTS_DIR);
+  const ext = path.extname(absoluteSource);
+  const baseName = path.basename(absoluteSource, ext) || 'attachment';
+  let destinationPath = path.join(artifactsDir, `${baseName}${ext}`);
+  let index = 1;
+
+  while (Array.from(portableArtifacts.values()).includes(getRelativeArtifactPath(reportDir, destinationPath))) {
+    destinationPath = path.join(artifactsDir, `${baseName}-${index}${ext}`);
+    index += 1;
+  }
+
+  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+  fs.copyFileSync(absoluteSource, destinationPath);
+
+  const relativePath = getRelativeArtifactPath(reportDir, destinationPath);
+  portableArtifacts.set(absoluteSource, relativePath);
+  return relativePath;
+}
+
+function getLocalArtifactPath(raw, url = parseUrl(raw)) {
+  if (path.isAbsolute(raw)) return raw;
+  if (isRemoteUrl(url)) return null;
+
+  if (url?.protocol === 'file:') {
+    try {
+      return fileURLToPath(url);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  if (url) return null;
+  return path.resolve(process.cwd(), raw);
+}
+
+function getArtifactBaseName({ raw, url, fsPath, artifact }) {
+  if (fsPath) return path.basename(fsPath);
+  if (url?.pathname) return path.basename(url.pathname) || artifact.name || artifact.title || 'attachment';
+  return artifact.name || artifact.title || path.basename(raw) || 'attachment';
+}
+
+function parseUrl(value) {
+  try {
+    return new URL(String(value));
+  } catch (_) {
+    return null;
+  }
+}
+
+function isRemoteUrl(url) {
+  return url?.protocol === 'http:' || url?.protocol === 'https:';
+}
+
+function getRelativeArtifactPath(reportDir, artifactPath) {
+  return `./${String(path.relative(reportDir, artifactPath)).split(path.sep).join('/')}`;
+}
+
 /**
  * Loads trace files from test.files and converts them to base64 data URLs
  * @param {object} test - Test object with files array