@testomatio/reporter 2.19.0 → 2.21.0

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';
@@ -16,9 +17,21 @@ import { filesize as prettyBytes } from 'filesize';
 import dotenv from 'dotenv';
 import Replay from '../replay.js';
 import { log } from '../utils/log.js';
-import { formatFilterListIds, formatRunOutput, formatFetchRunsOutput } from '../utils/pipe_utils.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,44 +145,63 @@ 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')
   .option('--project <slug>', 'Project slug (or set TESTOMATIO_PROJECT)')
+  .option('--run <id>', 'Fetch a single run by its id')
   .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(
     '--format <format>',
     'Machine-readable output: run ids, one per line (--format id) or run details (--format json)',
   )
-  .action(async opts => {
+  .action(async (pageUrl, opts) => {
     const apiKey = process.env['INPUT_TESTOMATIO-KEY'] || config.TESTOMATIO;
     if (!apiKey) {
       log.error(pc.red('⚠️  TESTOMATIO API key required'));
       process.exit(1);
     }
 
-    const project = opts.project || process.env.TESTOMATIO_PROJECT;
+    let page = {};
+    if (pageUrl) {
+      page = parseRunsUrl(pageUrl);
+      if (!page) {
+        log.error(pc.red(`⚠️  Not a Testomat.io run or runs page URL: ${pageUrl}`));
+        process.exit(1);
+      }
+    }
+
+    const project = opts.project || page.project || process.env.TESTOMATIO_PROJECT;
     if (!project) {
       log.error(pc.red('⚠️  --project (or TESTOMATIO_PROJECT) is required'));
       process.exit(1);
     }
 
-    const baseUrl = process.env.TESTOMATIO_URL || 'https://app.testomat.io';
-    const url = new URL(`/api/v2/${project}/runs`, baseUrl);
-    if (opts.title) url.searchParams.set('search', opts.title);
-    if (opts.tql) url.searchParams.set('tql', opts.tql);
-    if (opts.rungroup) url.searchParams.set('groupId', opts.rungroup);
-    const requestedLimit = opts.latest ? 1 : parseInt(opts.limit, 10) || FETCH_RUNS_DEFAULT_LIMIT;
-    const limit = Math.min(Math.max(requestedLimit, 1), FETCH_RUNS_MAX_LIMIT);
-    url.searchParams.set('per_page', String(limit));
+    const baseUrl = page.baseUrl || process.env.TESTOMATIO_URL || 'https://app.testomat.io';
+    const runId = opts.run || page.runId;
+    let url;
+
+    if (runId) {
+      url = new URL(`/api/v2/${project}/runs/${runId}`, baseUrl);
+    } else {
+      url = new URL(`/api/v2/${project}/runs`, baseUrl);
+      for (const [key, value] of page.params || []) url.searchParams.append(key, value);
+      if (opts.title) url.searchParams.set('search', opts.title);
+      if (opts.tql) url.searchParams.set('tql', opts.tql);
+      if (opts.rungroup) url.searchParams.set('groupId', opts.rungroup);
+      const requestedLimit = opts.latest ? 1 : parseInt(opts.limit, 10) || FETCH_RUNS_DEFAULT_LIMIT;
+      const limit = Math.min(Math.max(requestedLimit, 1), FETCH_RUNS_MAX_LIMIT);
+      url.searchParams.set('per_page', String(limit));
+    }
 
     const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
     const body = await response.json();
@@ -177,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')
@@ -196,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'));
@@ -213,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"
@@ -250,6 +450,7 @@ program
 
         if (command && command.split && !opts.remote) {
           command = applyFilter(command, tests);
+          filterApplied = true;
         }
       }
       catch (err) {
@@ -326,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 () => {
@@ -335,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/client.js

@@ -36,6 +36,8 @@ class Client {
     this.pipeStore = {};
     this.runId = '';
     this.queue = Promise.resolve();
+    // adapter name is set by the adapter module itself on load (global.TESTOMATIO_ADAPTER)
+    this.adapterName = params.adapter || global.TESTOMATIO_ADAPTER;
 
     // @ts-ignore this line will be removed in compiled code, because __dirname is defined in commonjs
     const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -244,7 +246,9 @@ class Client {
       overwrite,
       tags,
     } = testData;
-    let { files = [], manuallyAttachedArtifacts, message = '', meta = {} } = testData;
+    let { files = [], manuallyAttachedArtifacts, message = '' } = testData;
+    /** @type {Record<string, any>} */
+    let meta = testData.meta || {};
 
     if (stepArtifactPaths.size) {
       const isStepArtifact = item => stepArtifactPaths.has(typeof item === 'object' ? item?.path : item);
@@ -261,6 +265,10 @@ class Client {
         return acc;
       }, {});
 
+    // meta must always include reporter version and adapter used
+    if (this.version) meta.reporterVersion = this.version;
+    if (this.adapterName) meta.adapter = this.adapterName;
+
     const testContext = suite_title ? `${suite_title} ${title}` : title;
 
     let errorFormatted = '';
@@ -389,8 +397,8 @@ class Client {
     this.queue = this.queue
       .then(() => Promise.all(this.pipes.map(p => p.finishRun(runParams))))
       .then(() => {
-        if (!this.uploader.isEnabled) return;
-
+        // no early return when uploading is disabled:
+        // skipped artifacts (e.g. no S3 credentials obtained) must still be reported to the user
         const filesizeStrMaxLength = 7;
 
         if (this.uploader.successfulUploads.length) {

package/src/data-storage.js

@@ -190,9 +190,10 @@ class DataStorage {
 }
 
 function stringToMD5Hash(str) {
-  const md5 = crypto.createHash('md5');
-  md5.update(str);
-  const hash = md5.digest('hex');
+  // sha256 instead of md5 for FIPS-enabled hosts compatibility
+  const sha256 = crypto.createHash('sha256');
+  sha256.update(str);
+  const hash = sha256.digest('hex');
   return `${process.env.runId || 'run'}_${hash}`;
 }
 

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 };