testomatio-reporter-cli 2.20.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testomatio-reporter-cli",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Yarn Berry compatible standalone CLI for @testomatio/reporter",
   "type": "module",
   "bin": {

package/src/adapter/codecept.js

@@ -20,7 +20,7 @@ if (!global.codeceptjs) {
 }
 
 // @ts-ignore
-const { event, recorder, codecept, output } = global.codeceptjs;
+const { event, recorder, codecept, output, container } = global.codeceptjs;
 
 const [, MAJOR_VERSION, MINOR_VERSION] = codecept
   .version()
@@ -59,6 +59,7 @@ function CodeceptReporter(config) {
   let isRunFinalized = false;
 
   const testTimeMap = {};
+  const failedUrls = new Map();
   const clientConfig = buildCodeceptClientConfig(config);
   const client = new TestomatClient(clientConfig);
 
@@ -243,6 +244,22 @@ function CodeceptReporter(config) {
     }, true);
   });
 
+  event.dispatcher.on(event.test.failed, (test, _err, hookName) => {
+    // no browser in suite hooks
+    if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') return;
+    const helper = Object.values(container.helpers()).find(h => typeof h.grabCurrentUrl === 'function');
+    if (!helper) return;
+
+    recorder.add('url of failed test', async () => {
+      try {
+        const url = await helper.grabCurrentUrl();
+        if (url) failedUrls.set(test.uid, url);
+      } catch (err) {
+        debug('Failed to grab url of failed test', err?.message || err);
+      }
+    }, true);
+  });
+
   event.dispatcher.on(event.test.skipped, test => {
     const { uid, tags, title } = test.simplify();
 
@@ -274,6 +291,9 @@ function CodeceptReporter(config) {
     const keyValues = services.keyValues.get(test.fullTitle());
     const links = services.links.get(test.fullTitle());
     const screenshotOnFailPath = artifacts.screenshot || null;
+    const meta = { ...keyValues, ...test.meta };
+    if (test.state === STATUS.FAILED && failedUrls.has(uid)) meta.failedUrl = failedUrls.get(uid);
+    failedUrls.delete(uid);
 
     // Build step hierarchy with screenshot from screenshotOnFail
     const stepHierarchy = buildUnifiedStepHierarchy(
@@ -297,7 +317,7 @@ function CodeceptReporter(config) {
       logs,
       links,
       manuallyAttachedArtifacts,
-      meta: { ...keyValues, ...test.meta },
+      meta,
     });
     reportTestPromises.push(reportTestPromise);
 

package/src/adapter/e2e.js

@@ -94,6 +94,8 @@ export function toTestData(result, groups, artifactsRoot) {
   if (result.repeat) meta.repeat = result.repeat;
   if (attempts.length > 1) meta.retryCount = attempts.length - 1;
   if (result.status === 'flaky') meta.isFlaky = true;
+  const status = testStatus(result.status);
+  if (status === STATUS.FAILED && final?.failure?.url) meta.failedUrl = final.failure.url;
 
   const filesById = new Map();
   for (const artifact of final?.artifacts || []) {
@@ -128,7 +130,7 @@ export function toTestData(result, groups, artifactsRoot) {
     meta,
   };
 
-  return { status: testStatus(result.status), data };
+  return { status, data };
 }
 
 /** Attempts of a result; a serial member keeps its part of the group's attempts. */
@@ -140,6 +142,7 @@ function attemptsOf(result, groups) {
     return {
       status: member?.status || attempt.status,
       error: member?.error || attempt.error,
+      failure: member?.failure || attempt.failure,
       steps: member?.steps || [],
       appLog: member?.appLog || [],
       skip: member?.skip,

package/src/adapter/playwright.js

@@ -110,7 +110,11 @@ class PlaywrightReporter {
       if (result.status === 'passed') status = 'failed';
     }
 
-    const reportTestPromise = this.client.addTestRun(checkStatus(status), {
+    const testStatus = checkStatus(status);
+    let failedUrl;
+    if (testStatus === Status.FAILED) failedUrl = lastNavigatedUrl(result.steps, test.parent.project().use.baseURL);
+
+    const reportTestPromise = this.client.addTestRun(testStatus, {
       rid: `${rid}-${project.name}`,
       error,
       test_id: getTestomatIdFromTestTitle(`${title} ${tags.join(' ')}`),
@@ -128,6 +132,7 @@ class PlaywrightReporter {
         isMobile: project.isMobile,
         project: project.name,
         projectDependencies: project.dependencies?.length ? project.dependencies : null,
+        failedUrl,
         ...testMeta,
         ...meta,
         ...project.metadata, // metadata has any type (in playwright), but we will stringify it in client.js
@@ -244,6 +249,31 @@ function isScreenshotArtifact(attachment) {
   return attachment?.contentType === 'image/png' && attachment?.name === 'screenshot';
 }
 
+/**
+ * Last url the test navigated to; the reporter has no access to the page itself.
+ * @returns {string|undefined}
+ */
+function lastNavigatedUrl(steps, baseURL) {
+  const url = findLastNavigation(steps);
+  if (!url) return;
+  try {
+    return new URL(url, baseURL).href;
+  } catch {
+    return url;
+  }
+}
+
+function findLastNavigation(steps = []) {
+  let url;
+  for (const step of steps) {
+    // 'Navigate to "url"' since Playwright 1.53, 'page.goto(url)' before
+    const match = step.title.match(/^Navigate to "(.+)"$/) || step.title.match(/^page\.goto\((.+)\)$/);
+    if (step.category === 'pw:api' && match) url = match[1];
+    url = findLastNavigation(step.steps) || url;
+  }
+  return url;
+}
+
 function appendStep(step, shift = 0) {
   // nesting too deep, ignore those steps
   if (shift >= 10) return;

package/src/adapter/vitest.js

@@ -398,7 +398,10 @@ function normalizeVitestTest(test) {
       file,
       suiteTitle,
       logs: '',
-      meta: typeof test.meta === 'function' ? test.meta() : {},
+      meta: {
+        ...(test.task?.meta || {}),
+        ...(typeof test.meta === 'function' ? test.meta() : test.meta || {}),
+      },
     };
   }
 

package/src/adapter/webdriver.js

@@ -4,6 +4,9 @@ import { getTestomatIdFromTestTitle, fileSystem } from '../utils/utils.js';
 import { services } from '../services/index.js';
 import { TESTOMAT_TMP_STORAGE_DIR } from '../constants.js';
 import { stringToMD5Hash } from '../data-storage.js';
+import createDebugMessages from 'debug';
+
+const debug = createDebugMessages('@testomatio/reporter:adapter:webdriver');
 
 global.TESTOMATIO_ADAPTER = 'webdriverio';
 
@@ -122,7 +125,8 @@ class WebdriverReporter extends WDIOReporter {
   async addTest(test) {
     if (!this.client) return;
 
-    const { title, _duration: duration, state, error, output, links, artifacts, meta, logs } = test;
+    const { title, _duration: duration, state, error, output, links, artifacts, logs } = test;
+    let { meta } = test;
 
     const testId = getTestomatIdFromTestTitle(title);
 
@@ -133,6 +137,11 @@ class WebdriverReporter extends WDIOReporter {
 
     const rid = stringToMD5Hash(test.fullTitle);
 
+    if (state === 'failed') {
+      const failedUrl = (await grabCurrentUrl()) || lastNavigatedUrl(output);
+      if (failedUrl) meta = { ...meta, failedUrl };
+    }
+
     await this.client.addTestRun(state, {
       rid,
       manuallyAttachedArtifacts: test.artifacts,
@@ -150,7 +159,7 @@ class WebdriverReporter extends WDIOReporter {
   /**
    * @param {import('../../types/types.js').WebdriverIOScenario} scenario
    */
-  addBddScenario(scenario) {
+  async addBddScenario(scenario) {
     if (!this.client) return;
 
     const { title, _duration: duration } = scenario;
@@ -169,6 +178,12 @@ class WebdriverReporter extends WDIOReporter {
 
     const tags = scenario.tags.map(tag => tag.name);
 
+    let meta;
+    if (scenarioState === 'failed') {
+      const failedUrl = await grabCurrentUrl();
+      if (failedUrl) meta = { failedUrl };
+    }
+
     return this.client.addTestRun(scenarioState, {
       error: error ? Error(error) : null,
       title,
@@ -176,11 +191,38 @@ class WebdriverReporter extends WDIOReporter {
       time: duration,
       tags,
       file: scenario.file,
+      meta,
       // filesBuffers: screenshotsBuffers,
     });
   }
 }
 
+/**
+ * Current url of the browser in this worker; reporters run in the worker process.
+ * @returns {Promise<string|undefined>}
+ */
+async function grabCurrentUrl() {
+  // @ts-ignore
+  const browser = globalThis.browser;
+  if (typeof browser?.getUrl !== 'function') return;
+  try {
+    const url = await browser.getUrl();
+    // multiremote returns a url per browser
+    if (typeof url === 'string') return url;
+  } catch (err) {
+    debug('Failed to grab url of failed test', err?.message || err);
+  }
+}
+
+/**
+ * Last url opened by the test, taken from its command log.
+ * @returns {string|undefined}
+ */
+function lastNavigatedUrl(output = []) {
+  const navigations = output.filter(el => el.endpoint === '/session/:sessionId/url' && el.body?.url);
+  return navigations.at(-1)?.body.url;
+}
+
 /**
  *
  * @param {*} fullTestTitle

package/src/bin/cli.js

@@ -9,6 +9,7 @@ import XmlReader from '../xmlReader.js';
 import AllureReader from '../allureReader.js';
 import { APP_PREFIX, STATUS, DEBUG_FILE, BATCH_MODE } from '../constants.js';
 import { cleanLatestRunId, getPackageVersion, applyFilter, transformEnvVarToBoolean } from '../utils/utils.js';
+import { isPlaceholderCommand, runnerHint, buildFilterWarning } from '../utils/detectRunner.js';
 import { config } from '../config.js';
 import { readLatestRunId } from '../utils/utils.js';
 import pc from 'picocolors';
@@ -19,6 +20,18 @@ import { log } from '../utils/log.js';
 import { formatFilterListIds, formatRunOutput, formatFetchRunsOutput, parseRunsUrl } from '../utils/pipe_utils.js';
 import fs from 'fs';
 import path from 'path';
+import {
+  RunFetcher,
+  resolveRunTarget,
+  parseStatuses,
+  parseTestrunsLimit,
+  downloadArtifacts,
+  defaultArtifactsDir,
+  TESTRUNS_DEFAULT_LIMIT,
+  TESTRUNS_MAX_LIMIT,
+  TESTRUN_STATUSES,
+} from '../fetch/testruns.js';
+import { renderRunReport } from '../fetch/report.js';
 
 const debug = createDebugMessages('@testomatio/reporter:cli');
 const version = getPackageVersion();
@@ -42,8 +55,12 @@ program
     // remaining output to stderr, skip the banner, and silence info-level logs so
     // stdout stays clean for capture (e.g. RUN_ID=$(... start --format id)).
     // Set TESTOMATIO_LOG_LEVEL=INFO to re-enable progress logs for debugging.
-    const subOpts = actionCommand.opts();
-    if (subOpts.filterList || subOpts.format) {
+    const subOpts = actionCommand.optsWithGlobals();
+    // fetch status|count|report print their result on stdout, so the rest goes to stderr too
+    const isFetchSubcommand = actionCommand.parent?.name() === 'fetch';
+    if (isFetchSubcommand && !subOpts.format) {
+      process.env.TESTOMATIO_LOG_STDERR = '1';
+    } else if (subOpts.filterList || subOpts.format) {
       process.env.TESTOMATIO_LOG_STDERR = '1';
       process.env.TESTOMATIO_LOG_LEVEL ||= 'WARN';
       // with --format json the logs are machine-readable too: one JSON object per line on stderr
@@ -59,9 +76,10 @@ program
   .option('--kind <type>', 'Specify run type: automated, manual, mixed, or detect')
   .option('--filter <filter>', 'Scope the prepared run to tests matching the filter (no execution)')
   .option('--format <format>', 'Machine-readable output: the run id (--format id) or run details (--format json)')
-  .option('--warn', 'Exit 0 instead of 1 when the filter matches no tests (warn only)')
+  .option('--warn', 'Exit 0 instead of 1 when the filter matches no tests (warn only); env: TESTOMATIO_WARN')
   .action(async opts => {
     cleanLatestRunId();
+    opts.warn ||= transformEnvVarToBoolean(process.env.TESTOMATIO_WARN);
 
     log.info('Starting a new Run on Testomat.io...');
     const apiKey = process.env['INPUT_TESTOMATIO-KEY'] || config.TESTOMATIO;
@@ -127,7 +145,7 @@ program
     });
   });
 
-program
+const fetchCommand = program
   .command('fetch')
   .description('Fetch runs from Testomat.io API v2')
   .argument('[url]', 'URL of a run or of a (filtered) runs page in Testomat.io')
@@ -136,10 +154,10 @@ program
   .option('--title <text>', 'Filter by run title')
   .option('--tql <query>', 'Filter using Testomat Query Language')
   .option('--rungroup <uid>', 'Filter by rungroup id')
+  // no default value: fetch parses --limit for its subcommands too, see createRunFetcher
   .option(
     '--limit <number>',
-    `Max number of runs to return (max ${FETCH_RUNS_MAX_LIMIT})`,
-    String(FETCH_RUNS_DEFAULT_LIMIT),
+    `Max number of runs to return (default ${FETCH_RUNS_DEFAULT_LIMIT}, max ${FETCH_RUNS_MAX_LIMIT})`,
   )
   .option('--latest', 'Only fetch the most recent run (shorthand for --limit 1)')
   .option(
@@ -196,6 +214,166 @@ program
     console.log(formatFetchRunsOutput(body, opts.format));
   });
 
+// fetch parses the options it shares with its subcommands (--project, --format, --limit) wherever they are placed,
+// so subcommands declare them only for help and read them with optsWithGlobals()
+
+/**
+ * Build a RunFetcher for the run argument of fetch status|count|report, or exit with an error.
+ *
+ * @param {string} runArg
+ * @param {{project?: string}} opts
+ * @returns {RunFetcher}
+ */
+function createRunFetcher(runArg, opts) {
+  const apiKey = process.env['INPUT_TESTOMATIO-KEY'] || config.TESTOMATIO;
+  if (!apiKey) {
+    log.error(pc.red('⚠️  TESTOMATIO API key required'));
+    process.exit(1);
+  }
+
+  try {
+    return new RunFetcher({ ...resolveRunTarget(runArg, opts), apiKey });
+  } catch (err) {
+    log.error(pc.red(`⚠️  ${err.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * @param {{only?: string, onlyFailed?: boolean}} opts
+ * @returns {string[]}
+ */
+function getStatusFilter(opts) {
+  try {
+    return parseStatuses(opts);
+  } catch (err) {
+    log.error(pc.red(`⚠️  ${err.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * @param {Error} err
+ * @returns {never}
+ */
+function exitOnFetchError(err) {
+  log.error(pc.red(`⚠️  Failed to fetch: ${err.message}`));
+  process.exit(1);
+}
+
+const RUN_ARGUMENT_DESCRIPTION = 'Run id, or URL of a run in Testomat.io';
+const STATUS_FILTER_DESCRIPTION = `Only testruns with these statuses, comma-separated (${TESTRUN_STATUSES.join(', ')})`;
+
+fetchCommand
+  .command('status')
+  .description('Show a run with the number of its testruns by status')
+  .argument('<run>', RUN_ARGUMENT_DESCRIPTION)
+  .option('--project <slug>', 'Project slug (or set TESTOMATIO_PROJECT)')
+  .option('--format <format>', 'Machine-readable output: run status and counts as JSON (--format json)')
+  .action(async (runArg, _opts, command) => {
+    const opts = command.optsWithGlobals();
+    const fetcher = createRunFetcher(runArg, opts);
+
+    const [run, summary] = await Promise.all([fetcher.fetchRun(), fetcher.countTestrunsByStatus()]).catch(
+      exitOnFetchError,
+    );
+    const counts = Object.fromEntries(TESTRUN_STATUSES.map(status => [status, summary.byStatus[status] || 0]));
+
+    if (opts.format === 'json') {
+      const data = { id: run.id, title: run.title, status: run.status, url: fetcher.runUrl, total: summary.total };
+      console.log(JSON.stringify({ ...data, ...counts }, null, 2));
+      return;
+    }
+
+    const lines = [`run: ${run.title}`, `status: ${run.status}`, `url: ${fetcher.runUrl}`, `total: ${summary.total}`];
+    for (const [status, count] of Object.entries(counts)) lines.push(`${status}: ${count}`);
+    console.log(lines.join('\n'));
+  });
+
+fetchCommand
+  .command('count')
+  .description('Print the number of testruns of a run, to pick --limit and filters for fetch report')
+  .argument('<run>', RUN_ARGUMENT_DESCRIPTION)
+  .option('--project <slug>', 'Project slug (or set TESTOMATIO_PROJECT)')
+  .option('--only <statuses>', STATUS_FILTER_DESCRIPTION)
+  .option('--only-failed', 'Only failed testruns (shorthand for --only failed)')
+  .action(async (runArg, _opts, command) => {
+    const opts = command.optsWithGlobals();
+    const fetcher = createRunFetcher(runArg, opts);
+    const statuses = getStatusFilter(opts);
+
+    const total = await fetcher.countTestruns(statuses).catch(exitOnFetchError);
+    console.log(total);
+  });
+
+fetchCommand
+  .command('report')
+  .description('Print a run with its testruns as a Markdown report')
+  .argument('<run>', RUN_ARGUMENT_DESCRIPTION)
+  .option('--project <slug>', 'Project slug (or set TESTOMATIO_PROJECT)')
+  .option('--only <statuses>', STATUS_FILTER_DESCRIPTION)
+  .option('--only-failed', 'Only failed testruns (shorthand for --only failed)')
+  .option('--stack', 'Include stack traces')
+  .option('--artifacts', 'Download artifacts to --out and link them from the report')
+  .option('--out <dir>', 'Directory for downloaded artifacts (default: ./<run-title>-<run-id>)')
+  .option(
+    '--limit <number>',
+    `Max number of testruns, failed first (default ${TESTRUNS_DEFAULT_LIMIT}, max ${TESTRUNS_MAX_LIMIT})`,
+  )
+  .action(async (runArg, _opts, command) => {
+    const opts = command.optsWithGlobals();
+    const fetcher = createRunFetcher(runArg, opts);
+    const statuses = getStatusFilter(opts);
+    const { limit, capped } = parseTestrunsLimit(opts.limit);
+    if (capped) log.warn(pc.yellow(`⚠️  --limit is capped at ${TESTRUNS_MAX_LIMIT}`));
+
+    const run = await fetcher.fetchRun().catch(exitOnFetchError);
+
+    if (opts.artifacts) {
+      const hasSharedCredentials = await fetcher.applySharedS3Credentials(run);
+      if (!hasSharedCredentials && !process.env.S3_BUCKET) {
+        log.error(pc.red('⚠️  --artifacts needs S3 access: share S3 credentials in project settings or set S3_BUCKET'));
+        process.exit(1);
+      }
+    }
+
+    const [summary, list] = await Promise.all([
+      fetcher.countTestrunsByStatus(),
+      fetcher.listTestruns({ statuses, limit }),
+    ]).catch(exitOnFetchError);
+
+    let { testruns } = list;
+    if (list.total > testruns.length) {
+      log.warn(
+        pc.yellow(
+          `⚠️  Showing ${testruns.length} of ${list.total} testruns. Use --limit or --only-failed to narrow it.`,
+        ),
+      );
+    }
+
+    if (opts.stack || opts.artifacts) {
+      testruns = await fetcher.addTestrunDetails(testruns, (testrun, err) => {
+        log.warn(pc.yellow(`⚠️  Failed to fetch details of testrun ${testrun.id}: ${err.message}`));
+      });
+      if (!opts.stack) testruns = testruns.map(({ stack, ...testrun }) => testrun);
+    }
+
+    if (opts.artifacts) {
+      const outDir = opts.out || defaultArtifactsDir(run, fetcher.runId);
+      const artifactsCount = testruns.reduce((sum, testrun) => sum + (testrun.artifacts?.length || 0), 0);
+      log.info(`Downloading ${artifactsCount} artifacts to ${outDir}`);
+      testruns = await downloadArtifacts(testruns, outDir, (url, err) => {
+        log.warn(pc.yellow(`⚠️  Failed to download ${url}: ${err.message}`));
+      });
+    } else {
+      testruns = testruns.map(({ artifacts, ...testrun }) => testrun);
+    }
+
+    process.stdout.write(
+      renderRunReport({ run, runUrl: fetcher.runUrl, summary, testruns, matched: list.total, statuses }),
+    );
+  });
+
 program
   .command('run')
   .alias('test')
@@ -215,8 +393,9 @@ program
     (value, prev) => prev.concat([value]),
     [],
   )
-  .option('--warn', 'Exit 0 instead of 1 when the filter matches no tests (warn only)')
+  .option('--warn', 'Exit 0 instead of 1 when the filter matches no tests (warn only); env: TESTOMATIO_WARN')
   .action(async (command, opts) => {
+    opts.warn ||= transformEnvVarToBoolean(process.env.TESTOMATIO_WARN);
     if (opts.remote) {
       if (opts.filterList) {
         log.warn(pc.red('⚠️  --filter-list cannot be combined with --remote'));
@@ -232,6 +411,8 @@ program
     const title = process.env.TESTOMATIO_TITLE;
     const client = new TestomatClient({ apiKey, title });
 
+    let filterApplied = false;
+
     if (opts.filter || opts.filterList) {
       log.info('Filtering tests...');
       // Example of use: npx @testomatio/reporter run "npx jest" --filter "testomatio:tag-name=frontend"
@@ -269,6 +450,7 @@ program
 
         if (command && command.split && !opts.remote) {
           command = applyFilter(command, tests);
+          filterApplied = true;
         }
       }
       catch (err) {
@@ -345,6 +527,14 @@ program
       return process.exit(0);
     }
 
+    if (isPlaceholderCommand(command)) {
+      log.error(pc.red(`⚠️  The command "${command}" looks like a placeholder.`));
+      log.error('The example command from Testomat.io must be edited:');
+      log.error('replace the placeholder with your actual test runner command.');
+      log.error(runnerHint());
+      process.exit(1);
+    }
+
     log.info( `🚀 Running`, pc.green(command));
 
     const runTests = async () => {
@@ -354,9 +544,28 @@ program
         env: { ...process.env, TESTOMATIO_PROCEED: 'true', runId: client.runId, TESTOMATIO_RUN: client.runId },
       });
 
+      let errored = false;
+
+      cmd.on('error', err => {
+        errored = true;
+        const spawnError = /** @type {NodeJS.ErrnoException} */ (err);
+        if (spawnError.code === 'ENOENT') {
+          log.error(pc.red(`🔴 Command not found: ${pc.bold(testCmds[0])}`));
+          log.error(runnerHint());
+        } else {
+          log.error(pc.red(`🔴 Failed to start command: ${spawnError.message}`));
+        }
+        const finish = apiKey ? client.updateRunStatus('failed').catch(() => {}) : Promise.resolve();
+        finish.then(() => process.exit(1));
+      });
+
       cmd.on('close', async code => {
+        if (errored) return;
         const emoji = code === 0 ? '🟢' : '🔴';
         log.info( emoji, `Runner exited with ${pc.bold(code)}`);
+        if (code !== 0 && filterApplied) {
+          buildFilterWarning(command).forEach(line => log.warn(line));
+        }
         if (apiKey) {
           const status = code === 0 ? 'passed' : 'failed';
           await client.updateRunStatus(status);

package/src/fetch/report.js

@@ -0,0 +1,86 @@
+import { renderTests } from '../pipe/markdown.js';
+
+const TITLE_SEPARATOR = ' ⇒ ';
+
+/**
+ * Map a testrun of API v2 to the test shape of the Markdown pipe.
+ * Without a suite, the API returns the title as "<suite> ⇒ <title>".
+ *
+ * @param {object} testrun
+ * @returns {object}
+ */
+function toReportTest(testrun) {
+  let title = String(testrun.test_title || '').trim();
+  let suite = testrun.suiteTitle;
+
+  if (!suite && title.includes(TITLE_SEPARATOR)) {
+    const [suitePart, ...titleParts] = title.split(TITLE_SEPARATOR);
+    suite = suitePart.trim();
+    title = titleParts.join(TITLE_SEPARATOR).trim();
+  }
+
+  return {
+    title,
+    suite_title: suite,
+    status: testrun.status,
+    run_time: testrun.run_time,
+    test_id: testrun.testId,
+    message: testrun.message,
+    stack: testrun.stack,
+    artifacts: testrun.artifacts,
+  };
+}
+
+/**
+ * Render a fetched run with its testruns as a Markdown report.
+ *
+ * @param {object} params
+ * @param {object} params.run - Run from GET /api/v2/:project/runs/:id
+ * @param {string} params.runUrl
+ * @param {{total: number, byStatus: Record<string, number>}} params.summary - Counts of all testruns of the run
+ * @param {object[]} params.testruns
+ * @param {number} params.matched - Number of testruns matching the filter
+ * @param {string[]} params.statuses - Status filter, empty for all testruns
+ * @returns {string}
+ */
+function renderRunReport({ run, runUrl, summary, testruns, matched, statuses }) {
+  const status = String(run.status || 'unknown');
+  const sections = [`# ${run.title || run.id} — ${status.toUpperCase()}`];
+
+  const rows = [
+    ['Run ID', `\`${run.id}\``],
+    ['Run URL', `<${runUrl}>`],
+    ['Status', status],
+  ];
+  if (run.env) rows.push(['Environment', run.env]);
+  if (run.launched_at) rows.push(['Started', run.launched_at]);
+  if (run.finished_at) rows.push(['Finished', run.finished_at]);
+
+  let shown = `${testruns.length} of ${matched} shown`;
+  if (statuses.length) shown += ` (only: ${statuses.join(', ')})`;
+  rows.push(['Testruns', shown]);
+
+  sections.push(
+    ['| Key | Value |', '| --- | ----- |', ...rows.map(([key, value]) => `| ${key} | ${value} |`)].join('\n'),
+  );
+
+  if (run.description?.trim()) sections.push(`## Description\n\n${run.description.trim()}`);
+
+  const counts = Object.entries(summary.byStatus).sort(([, a], [, b]) => b - a);
+  sections.push(
+    [
+      '## Summary',
+      '',
+      '| Status | Count |',
+      '| ------ | ----- |',
+      ...counts.map(([name, count]) => `| ${name} | ${count} |`),
+      `| total | ${summary.total} |`,
+    ].join('\n'),
+  );
+
+  sections.push(renderTests(testruns.map(toReportTest)));
+
+  return `${sections.join('\n\n')}\n`;
+}
+
+export { renderRunReport, toReportTest };

package/src/fetch/testruns.js

@@ -0,0 +1,283 @@
+import createDebugMessages from 'debug';
+import path from 'path';
+import { parseRunsUrl, setS3Credentials } from '../utils/pipe_utils.js';
+import { S3Uploader } from '../uploader.js';
+
+const debug = createDebugMessages('@testomatio/reporter:fetch');
+
+const TESTRUNS_DEFAULT_LIMIT = 50;
+const TESTRUNS_MAX_LIMIT = 100;
+const TESTRUN_STATUSES = ['passed', 'failed', 'skipped', 'pending'];
+const PARALLEL_REQUESTS = 5;
+
+/**
+ * Resolve the run argument of `fetch status|count|report`: a run id or a run URL.
+ * A URL also sets the server and the project.
+ *
+ * @param {string} runArg
+ * @param {{project?: string}} opts
+ * @returns {{baseUrl: string, project: string, runId: string}}
+ */
+function resolveRunTarget(runArg, opts) {
+  if (/^https?:\/\//i.test(runArg)) {
+    const page = parseRunsUrl(runArg);
+    if (!page?.runId) throw new Error(`Not a Testomat.io run URL: ${runArg}`);
+    return { baseUrl: page.baseUrl, project: opts.project || page.project, runId: page.runId };
+  }
+
+  const project = opts.project || process.env.TESTOMATIO_PROJECT;
+  if (!project) throw new Error('--project (or TESTOMATIO_PROJECT) is required');
+
+  return { baseUrl: process.env.TESTOMATIO_URL || 'https://app.testomat.io', project, runId: runArg };
+}
+
+/**
+ * Collect the statuses passed with --only and --only-failed.
+ *
+ * @param {{only?: string, onlyFailed?: boolean}} opts
+ * @returns {string[]}
+ */
+function parseStatuses(opts) {
+  const statuses = String(opts.only || '')
+    .split(',')
+    .map(status => status.trim().toLowerCase())
+    .filter(Boolean);
+  if (opts.onlyFailed) statuses.push('failed');
+
+  const unknown = statuses.filter(status => !TESTRUN_STATUSES.includes(status));
+  if (unknown.length) {
+    throw new Error(`Unknown status: ${unknown.join(', ')}. Use one of: ${TESTRUN_STATUSES.join(', ')}`);
+  }
+
+  return [...new Set(statuses)];
+}
+
+/**
+ * @param {string} [value] - Value of the CLI --limit option.
+ * @returns {{limit: number, capped: boolean}}
+ */
+function parseTestrunsLimit(value) {
+  const requested = Math.max(parseInt(value, 10) || TESTRUNS_DEFAULT_LIMIT, 1);
+  return { limit: Math.min(requested, TESTRUNS_MAX_LIMIT), capped: requested > TESTRUNS_MAX_LIMIT };
+}
+
+/**
+ * Run `fn` over `items` with at most `limit` calls in flight; results keep the order of `items`.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T) => Promise<R>} fn
+ * @returns {Promise<R[]>}
+ */
+async function mapWithLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+/**
+ * Read-only client for a single run and its testruns in API v2.
+ */
+class RunFetcher {
+  /**
+   * @param {{baseUrl: string, project: string, runId: string, apiKey: string}} params
+   */
+  constructor({ baseUrl, project, runId, apiKey }) {
+    this.baseUrl = baseUrl;
+    this.project = project;
+    this.runId = runId;
+    this.apiKey = apiKey;
+  }
+
+  get runUrl() {
+    return new URL(`/projects/${this.project}/runs/${this.runId}`, this.baseUrl).toString();
+  }
+
+  async get(apiPath, params = []) {
+    const url = new URL(`/api/v2/${this.project}${apiPath}`, this.baseUrl);
+    for (const [key, value] of params) url.searchParams.append(key, value);
+    debug('GET', url.toString());
+
+    const response = await fetch(url, { headers: { Authorization: `Bearer ${this.apiKey}` } });
+    const body = await response.json().catch(() => ({}));
+    if (response.status === 404 && apiPath === `/runs/${this.runId}`) {
+      throw new Error(`Run ${this.runId} not found in project ${this.project}`);
+    }
+    if (!response.ok) throw new Error(`${response.status} ${body.error || response.statusText}`);
+    return body;
+  }
+
+  async fetchRun() {
+    const body = await this.get(`/runs/${this.runId}`);
+    return body.data;
+  }
+
+  /**
+   * @param {string[]} statuses
+   * @returns {string[][]}
+   */
+  testrunParams(statuses = []) {
+    const params = [['run_id', this.runId]];
+    for (const status of statuses) params.push(['filter[status][]', status]);
+    return params;
+  }
+
+  /**
+   * @param {string[]} [statuses]
+   * @returns {Promise<number>}
+   */
+  async countTestruns(statuses = []) {
+    const body = await this.get('/testruns', [...this.testrunParams(statuses), ['count', 'true']]);
+    return body.meta?.total || 0;
+  }
+
+  /**
+   * @returns {Promise<{total: number, byStatus: Record<string, number>}>}
+   */
+  async countTestrunsByStatus() {
+    const body = await this.get('/testruns', [...this.testrunParams(), ['count', 'true'], ['group_by', 'status']]);
+    return { total: body.meta?.total || 0, byStatus: body.meta?.group_by || {} };
+  }
+
+  /**
+   * Testruns with failures first; the list has no stack and no artifacts.
+   *
+   * @param {{statuses?: string[], limit: number}} params
+   * @returns {Promise<{testruns: object[], total: number}>}
+   */
+  async listTestruns({ statuses = [], limit }) {
+    const body = await this.get('/testruns', [
+      ...this.testrunParams(statuses),
+      ['sort', 'failure'],
+      ['order', 'desc'],
+      ['per_page', String(limit)],
+    ]);
+    return { testruns: body.data || [], total: body.meta?.total || 0 };
+  }
+
+  /**
+   * Add `stack` and `artifacts` to each testrun; a testrun that fails to load is kept as is.
+   *
+   * @param {object[]} testruns
+   * @param {(testrun: object, err: Error) => void} onError
+   */
+  async addTestrunDetails(testruns, onError) {
+    return mapWithLimit(testruns, PARALLEL_REQUESTS, async testrun => {
+      try {
+        const body = await this.get(`/testruns/${testrun.id}`);
+        return { ...testrun, stack: body.data?.stack, artifacts: body.data?.artifacts || [] };
+      } catch (err) {
+        onError(testrun, err);
+        return testrun;
+      }
+    });
+  }
+
+  /**
+   * Shared S3 credentials of the project, returned by an empty update of the run.
+   * Skipped for scheduled runs (the update launches them) and mixed runs (it marks automated tests as started).
+   *
+   * @param {{status?: string, kind?: string}} run
+   * @returns {Promise<boolean>} whether credentials were applied
+   */
+  async applySharedS3Credentials(run) {
+    if (run.status === 'scheduled' || run.kind === 'mixed') {
+      debug(`Shared S3 credentials are not requested for a ${run.status} ${run.kind} run`);
+      return false;
+    }
+
+    const url = new URL(`/api/reporter/${this.runId}`, this.baseUrl);
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ api_key: this.apiKey }),
+    });
+    if (!response.ok) {
+      debug('Failed to get shared S3 credentials:', response.status);
+      return false;
+    }
+
+    const { artifacts } = await response.json();
+    if (!artifacts || !Object.keys(artifacts).length) return false;
+    setS3Credentials(artifacts);
+    return true;
+  }
+}
+
+/**
+ * Download the artifacts of each testrun to `<outDir>/<testrun id>/<file name>`.
+ * Each artifact becomes `{name, href}`, where `href` is the local path relative to the current directory,
+ * or the remote URL when the download failed.
+ *
+ * @param {object[]} testruns
+ * @param {string} outDir
+ * @param {(url: string, err: Error) => void} onError
+ */
+async function downloadArtifacts(testruns, outDir, onError) {
+  const uploader = new S3Uploader();
+  const jobs = [];
+
+  // the file name is parsed inside mapWithLimit, so a malformed artifact URL only skips that artifact
+  for (const testrun of testruns) {
+    const usedNames = new Set();
+    for (const url of testrun.artifacts || []) {
+      jobs.push({ testrun, url, outDir, usedNames });
+    }
+  }
+
+  const downloaded = await mapWithLimit(jobs, PARALLEL_REQUESTS, async job => {
+    let name = 'artifact';
+    try {
+      name = decodeURIComponent(path.basename(new URL(job.url).pathname)) || 'artifact';
+      if (job.usedNames.has(name)) name = `${job.usedNames.size}-${name}`;
+      job.usedNames.add(name);
+      const filePath = path.join(job.outDir, String(job.testrun.id), name);
+      await uploader.downloadFile(job.url, filePath);
+      const href = `./${path.relative(process.cwd(), filePath).split(path.sep).join('/')}`;
+      return { testrun: job.testrun, href, name };
+    } catch (err) {
+      onError(job.url, err);
+      return { testrun: job.testrun, href: job.url, name: `${name} (not downloaded)` };
+    }
+  });
+
+  return testruns.map(testrun => ({
+    ...testrun,
+    artifacts: downloaded.filter(job => job.testrun === testrun).map(({ name, href }) => ({ name, href })),
+  }));
+}
+
+/**
+ * @param {{title?: string}} run
+ * @param {string} runId
+ * @returns {string}
+ */
+function defaultArtifactsDir(run, runId) {
+  const slug = String(run.title || 'run')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return `./${slug || 'run'}-${runId}`;
+}
+
+export {
+  TESTRUNS_DEFAULT_LIMIT,
+  TESTRUNS_MAX_LIMIT,
+  TESTRUN_STATUSES,
+  RunFetcher,
+  resolveRunTarget,
+  parseStatuses,
+  parseTestrunsLimit,
+  mapWithLimit,
+  downloadArtifacts,
+  defaultArtifactsDir,
+};

package/src/pipe/markdown.js

@@ -521,6 +521,11 @@ function normalizeArtifact(raw) {
     return { name: path.basename(abs), href, isImage: looksLikeImage(abs) };
   }
 
+  // already resolved link, e.g. a downloaded artifact relative to the report
+  if (typeof raw.href === 'string' && raw.href) {
+    return { name: raw.name || path.basename(raw.href), href: raw.href, isImage: looksLikeImage(raw.href) };
+  }
+
   const rawPath = raw.path || raw.link || raw.url;
   if (!rawPath || typeof rawPath !== 'string') return null;
 
@@ -750,4 +755,6 @@ function aggregateTestRetries(tests) {
   return aggregated;
 }
 
+export { renderTests };
+
 export default MarkdownPipe;

package/src/reporter-functions.js

@@ -1,8 +1,11 @@
+import { createRequire } from 'module';
 import { playwrightLogsMarkers } from './adapter/utils/playwright.js';
 import { isPlaywright } from './helpers.js';
 import { services } from './services/index.js';
 import pc from 'picocolors';
 
+const requireModule = createRequire(`${process.cwd()}/package.json`);
+
 /**
  * Stores path to file as artifact and uploads it to the S3 storage
  * @param {string | {path: string, type: string, name: string}} data - path to file or object with path, type and name
@@ -44,6 +47,36 @@ function addStep(message, logs) {
   else services.logger.step(message, logs);
 }
 
+/**
+ * Returns the currently running Vitest test task, so `meta()` (and similar
+ * functions) can attach data to it. The task `.meta` object is serialized by
+ * Vitest back to the reporter (works across all pools: threads, forks, vmThreads).
+ *
+ * Resolution order matters:
+ * 1. `globalThis.__vitest_worker__.current` — set by Vitest in every worker and
+ *    independent of module resolution, so it works even when the reporter is the
+ *    externalized package and `@vitest/runner` is deduped to a different instance
+ *    (monorepos, pnpm, hoisting). This is also populated inside hooks (afterEach),
+ *    pointing at the test that the hook belongs to.
+ * 2. `@vitest/runner` `getCurrentTest()` — fallback for setups/versions where the
+ *    worker global is not exposed.
+ *
+ * @returns {any | null} Vitest test task or null when no test is active
+ */
+function getCurrentVitestTest() {
+  // @ts-ignore - injected by Vitest into the worker global scope
+  const worker = globalThis.__vitest_worker__;
+  const current = worker?.current;
+  if (current && (current.type === 'test' || current.type === undefined)) return current;
+
+  try {
+    const test = requireModule('@vitest/runner').getCurrentTest?.();
+    if (test) return test;
+  } catch {}
+
+  return null;
+}
+
 /**
  * Add key-value pair(s) to the test report
  * @param {{[key: string]: string} | string} keyValue - object { key: value } (multiple props allowed) OR key (string)
@@ -67,6 +100,14 @@ function setKeyValue(keyValue, value = undefined) {
     return;
   }
 
+  if (process.env.VITEST || process.env.VITEST_WORKER_ID) {
+    const vitestTest = getCurrentVitestTest();
+    if (vitestTest) {
+      Object.assign((vitestTest.meta ||= {}), keyValue);
+      return;
+    }
+  }
+
   // in this case keyValue is expected to be an object
   services.keyValues.put(keyValue);
 }

package/src/uploader.js

@@ -347,6 +347,33 @@ export class S3Uploader {
     );
   }
 
+  /**
+   * Download an artifact by its link: from the configured bucket through S3, otherwise over plain HTTP.
+   *
+   * @param {string} link
+   * @param {string} filePath
+   */
+  async downloadFile(link, filePath) {
+    const { S3_BUCKET } = this.getConfig();
+    const Key = getS3KeyFromUrl(link, S3_BUCKET);
+    let body;
+
+    if (Key) {
+      debug('Downloading from S3:', Key);
+      const s3 = new S3(this.#getS3Config());
+      const object = await s3.getObject({ Bucket: S3_BUCKET, Key });
+      body = Buffer.from(await object.Body.transformToByteArray());
+    } else {
+      debug('Downloading over HTTP:', link);
+      const response = await fetch(link);
+      if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+      body = Buffer.from(await response.arrayBuffer());
+    }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, body);
+  }
+
   async getS3LocationLink(out) {
     const response = await out.done();
 
@@ -409,3 +436,27 @@ export class S3Uploader {
     return cfg;
   }
 }
+
+/**
+ * Object key of an artifact link in the given bucket, for both virtual-hosted (bucket.host/key)
+ * and path style (host/bucket/key) links; null when the link points to another bucket.
+ *
+ * @param {string} link
+ * @param {string} [bucket]
+ * @returns {string|null}
+ */
+export function getS3KeyFromUrl(link, bucket) {
+  if (!bucket) return null;
+
+  let url;
+  try {
+    url = new URL(link);
+  } catch (e) {
+    return null;
+  }
+
+  const objectPath = decodeURIComponent(url.pathname.slice(1));
+  if (url.hostname.startsWith(`${bucket}.`)) return objectPath || null;
+  if (objectPath.startsWith(`${bucket}/`)) return objectPath.slice(bucket.length + 1) || null;
+  return null;
+}

package/src/utils/detectRunner.js

@@ -0,0 +1,151 @@
+import fs from 'fs';
+import path from 'path';
+import pc from 'picocolors';
+
+const LAUNCHER_PREFIXES = ['npx', 'npm', 'yarn', 'pnpm', 'bun', 'node', 'bunx'];
+
+const PLACEHOLDER_PHRASE_RE = /^<?-*(?:run|your|test)\s+(?:[\w-]+\s+)?(?:tests?|command|runner)>?$/i;
+
+const RUNNERS = [
+  {
+    name: 'Playwright',
+    configs: ['playwright.config.js', 'playwright.config.ts', 'playwright.config.mjs', 'playwright.config.cjs'],
+    dependencies: ['@playwright/test'],
+    command: 'npx playwright test',
+  },
+  {
+    name: 'CodeceptJS',
+    configs: ['codecept.conf.js', 'codecept.conf.ts'],
+    dependencies: ['codeceptjs'],
+    command: 'npx codeceptjs run',
+  },
+  {
+    name: 'WebdriverIO',
+    configs: ['wdio.conf.js', 'wdio.conf.ts'],
+    dependencies: ['@wdio/cli'],
+    dependencyPrefix: '@wdio/',
+    command: 'npx wdio run ./wdio.conf.js',
+  },
+  {
+    name: 'Cypress',
+    configs: ['cypress.config.js', 'cypress.config.ts'],
+    dependencies: ['cypress'],
+    command: 'npx cypress run',
+  },
+  {
+    name: 'Jest',
+    configs: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs', 'jest.config.cjs', 'jest.config.json'],
+    dependencies: ['jest'],
+    command: 'npx jest',
+  },
+  {
+    name: 'Vitest',
+    configs: ['vitest.config.js', 'vitest.config.ts', 'vitest.config.mjs'],
+    dependencies: ['vitest'],
+    command: 'npx vitest run',
+  },
+  {
+    name: 'Mocha',
+    configs: ['.mocharc.js', '.mocharc.cjs', '.mocharc.json', '.mocharc.yml', '.mocharc.yaml'],
+    dependencies: ['mocha'],
+    command: 'npx mocha',
+  },
+  {
+    name: 'Cucumber',
+    configs: ['cucumber.js', 'cucumber.cjs'],
+    dependencies: ['@cucumber/cucumber'],
+    command: 'npx cucumber-js',
+  },
+];
+
+/**
+ * @param {string} command
+ * @returns {boolean}
+ */
+function isPlaceholderCommand(command) {
+  const cmd = (command || '').trim();
+  if (!cmd) return false;
+
+  if (cmd.includes('<') || cmd.includes('>')) return true;
+
+  const firstToken = cmd.split(/\s+/)[0].toLowerCase();
+  if (LAUNCHER_PREFIXES.includes(firstToken)) return false;
+
+  return PLACEHOLDER_PHRASE_RE.test(cmd);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, string>}
+ */
+function readPackageDependencies(cwd) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {{ name: string, command: string } | null}
+ */
+function detectRunner(cwd = process.cwd()) {
+  const dependencies = readPackageDependencies(cwd);
+
+  for (const runner of RUNNERS) {
+    const config = runner.configs.find(file => fs.existsSync(path.join(cwd, file)));
+
+    const hasDependency = runner.dependencies?.some(dep => dependencies[dep])
+      || (runner.dependencyPrefix && Object.keys(dependencies).some(dep => dep.startsWith(runner.dependencyPrefix)));
+
+    if (!config && !hasDependency) continue;
+
+    let command = runner.command;
+    if (runner.name === 'WebdriverIO') {
+      command = `npx wdio run ./${config || 'wdio.conf.js'}`;
+    }
+
+    return { name: runner.name, command };
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+function runnerHint(cwd = process.cwd()) {
+  const runner = detectRunner(cwd);
+  if (runner) {
+    return `💡 Looks like this project uses ${runner.name}. Try: ${pc.green(runner.command)}`;
+  }
+  return `💡 Replace the placeholder with your test runner command, e.g. ${pc.green('npx playwright test')}`;
+}
+
+/**
+ * @param {string} command
+ * @returns {string[]}
+ */
+function buildFilterWarning(command) {
+  return [
+    '⚠️  The runner exited with a non-zero code while a Testomat.io filter was applied.',
+    'Your command was modified to run only tests matching Testomat IDs:',
+    `  ${pc.bold(command)}`,
+    'This usually means no local tests matched the filter:',
+    '  - tests are not annotated with the matching @Txxxxxx IDs in their titles',
+    '  - the filter selected tests from another repository or branch',
+    '  - the test runner does not support the appended --grep / --testNamePattern option',
+    '💡 Hint: run the printed command without the appended filter option to see all your tests,',
+    'then annotate them with Testomat IDs.',
+  ];
+}
+
+export {
+  isPlaceholderCommand,
+  detectRunner,
+  runnerHint,
+  buildFilterWarning,
+};