@testomatio/reporter 2.19.0 → 2.21.0

package/lib/bin/cli.js

@@ -13,6 +13,7 @@ const xmlReader_js_1 = __importDefault(require("../xmlReader.js"));
 const allureReader_js_1 = __importDefault(require("../allureReader.js"));
 const constants_js_1 = require("../constants.js");
 const utils_js_1 = require("../utils/utils.js");
+const detectRunner_js_1 = require("../utils/detectRunner.js");
 const config_js_1 = require("../config.js");
 const utils_js_2 = require("../utils/utils.js");
 const picocolors_1 = __importDefault(require("picocolors"));
@@ -23,6 +24,8 @@ const log_js_1 = require("../utils/log.js");
 const pipe_utils_js_1 = require("../utils/pipe_utils.js");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const testruns_js_1 = require("../fetch/testruns.js");
+const report_js_1 = require("../fetch/report.js");
 const debug = (0, debug_1.default)('@testomatio/reporter:cli');
 const version = (0, utils_js_1.getPackageVersion)();
 const program = new commander_1.Command();
@@ -43,8 +46,13 @@ 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
@@ -61,9 +69,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) => {
     (0, utils_js_1.cleanLatestRunId)();
+    opts.warn ||= (0, utils_js_1.transformEnvVarToBoolean)(process.env.TESTOMATIO_WARN);
     log_js_1.log.info('Starting a new Run on Testomat.io...');
     const apiKey = process.env['INPUT_TESTOMATIO-KEY'] || config_js_1.config.TESTOMATIO;
     const client = new client_js_1.default({ apiKey });
@@ -118,38 +127,58 @@ program
         process.exit(0);
     });
 });
-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')
-    .option('--limit <number>', `Max number of runs to return (max ${FETCH_RUNS_MAX_LIMIT})`, String(FETCH_RUNS_DEFAULT_LIMIT))
+    // no default value: fetch parses --limit for its subcommands too, see createRunFetcher
+    .option('--limit <number>', `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_js_1.config.TESTOMATIO;
     if (!apiKey) {
         log_js_1.log.error(picocolors_1.default.red('⚠️  TESTOMATIO API key required'));
         process.exit(1);
     }
-    const project = opts.project || process.env.TESTOMATIO_PROJECT;
+    let page = {};
+    if (pageUrl) {
+        page = (0, pipe_utils_js_1.parseRunsUrl)(pageUrl);
+        if (!page) {
+            log_js_1.log.error(picocolors_1.default.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_js_1.log.error(picocolors_1.default.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();
     if (!response.ok) {
@@ -158,6 +187,141 @@ program
     }
     console.log((0, pipe_utils_js_1.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_js_1.config.TESTOMATIO;
+    if (!apiKey) {
+        log_js_1.log.error(picocolors_1.default.red('⚠️  TESTOMATIO API key required'));
+        process.exit(1);
+    }
+    try {
+        return new testruns_js_1.RunFetcher({ ...(0, testruns_js_1.resolveRunTarget)(runArg, opts), apiKey });
+    }
+    catch (err) {
+        log_js_1.log.error(picocolors_1.default.red(`⚠️  ${err.message}`));
+        process.exit(1);
+    }
+}
+/**
+ * @param {{only?: string, onlyFailed?: boolean}} opts
+ * @returns {string[]}
+ */
+function getStatusFilter(opts) {
+    try {
+        return (0, testruns_js_1.parseStatuses)(opts);
+    }
+    catch (err) {
+        log_js_1.log.error(picocolors_1.default.red(`⚠️  ${err.message}`));
+        process.exit(1);
+    }
+}
+/**
+ * @param {Error} err
+ * @returns {never}
+ */
+function exitOnFetchError(err) {
+    log_js_1.log.error(picocolors_1.default.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 (${testruns_js_1.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(testruns_js_1.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_js_1.TESTRUNS_DEFAULT_LIMIT}, max ${testruns_js_1.TESTRUNS_MAX_LIMIT})`)
+    .action(async (runArg, _opts, command) => {
+    const opts = command.optsWithGlobals();
+    const fetcher = createRunFetcher(runArg, opts);
+    const statuses = getStatusFilter(opts);
+    const { limit, capped } = (0, testruns_js_1.parseTestrunsLimit)(opts.limit);
+    if (capped)
+        log_js_1.log.warn(picocolors_1.default.yellow(`⚠️  --limit is capped at ${testruns_js_1.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_js_1.log.error(picocolors_1.default.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_js_1.log.warn(picocolors_1.default.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_js_1.log.warn(picocolors_1.default.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 || (0, testruns_js_1.defaultArtifactsDir)(run, fetcher.runId);
+        const artifactsCount = testruns.reduce((sum, testrun) => sum + (testrun.artifacts?.length || 0), 0);
+        log_js_1.log.info(`Downloading ${artifactsCount} artifacts to ${outDir}`);
+        testruns = await (0, testruns_js_1.downloadArtifacts)(testruns, outDir, (url, err) => {
+            log_js_1.log.warn(picocolors_1.default.yellow(`⚠️  Failed to download ${url}: ${err.message}`));
+        });
+    }
+    else {
+        testruns = testruns.map(({ artifacts, ...testrun }) => testrun);
+    }
+    process.stdout.write((0, report_js_1.renderRunReport)({ run, runUrl: fetcher.runUrl, summary, testruns, matched: list.total, statuses }));
+});
 program
     .command('run')
     .alias('test')
@@ -169,8 +333,9 @@ program
     .option('--kind <type>', 'Specify run type: automated, manual, mixed, or detect')
     .option('--remote <profile>', 'Trigger run on the named Testomat.io CI profile instead of executing locally')
     .option('--remote-param <kv>', 'key=value pair forwarded to the CI profile config (repeat for multiple)', (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 ||= (0, utils_js_1.transformEnvVarToBoolean)(process.env.TESTOMATIO_WARN);
     if (opts.remote) {
         if (opts.filterList) {
             log_js_1.log.warn(picocolors_1.default.red('⚠️  --filter-list cannot be combined with --remote'));
@@ -184,6 +349,7 @@ program
     const apiKey = process.env['INPUT_TESTOMATIO-KEY'] || config_js_1.config.TESTOMATIO;
     const title = process.env.TESTOMATIO_TITLE;
     const client = new client_js_1.default({ apiKey, title });
+    let filterApplied = false;
     if (opts.filter || opts.filterList) {
         log_js_1.log.info('Filtering tests...');
         // Example of use: npx @testomatio/reporter run "npx jest" --filter "testomatio:tag-name=frontend"
@@ -218,6 +384,7 @@ program
             }
             if (command && command.split && !opts.remote) {
                 command = (0, utils_js_1.applyFilter)(command, tests);
+                filterApplied = true;
             }
         }
         catch (err) {
@@ -291,6 +458,13 @@ program
         }
         return process.exit(0);
     }
+    if ((0, detectRunner_js_1.isPlaceholderCommand)(command)) {
+        log_js_1.log.error(picocolors_1.default.red(`⚠️  The command "${command}" looks like a placeholder.`));
+        log_js_1.log.error('The example command from Testomat.io must be edited:');
+        log_js_1.log.error('replace the placeholder with your actual test runner command.');
+        log_js_1.log.error((0, detectRunner_js_1.runnerHint)());
+        process.exit(1);
+    }
     log_js_1.log.info(`🚀 Running`, picocolors_1.default.green(command));
     const runTests = async () => {
         const testCmds = command.split(' ');
@@ -298,9 +472,28 @@ program
             stdio: 'inherit',
             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_js_1.log.error(picocolors_1.default.red(`🔴 Command not found: ${picocolors_1.default.bold(testCmds[0])}`));
+                log_js_1.log.error((0, detectRunner_js_1.runnerHint)());
+            }
+            else {
+                log_js_1.log.error(picocolors_1.default.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_js_1.log.info(emoji, `Runner exited with ${picocolors_1.default.bold(code)}`);
+            if (code !== 0 && filterApplied) {
+                (0, detectRunner_js_1.buildFilterWarning)(command).forEach(line => log_js_1.log.warn(line));
+            }
             if (apiKey) {
                 const status = code === 0 ? 'passed' : 'failed';
                 await client.updateRunStatus(status);

package/lib/client.d.ts

@@ -15,6 +15,7 @@ export class Client {
     pipeStore: {};
     runId: string;
     queue: Promise<void>;
+    adapterName: any;
     version: any;
     executionList: Promise<void>;
     uploader: S3Uploader;

package/lib/client.js

@@ -37,6 +37,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 pathToPackageJSON = path_1.default.join(__dirname, '../package.json');
         try {
@@ -214,7 +216,9 @@ class Client {
         const uploadedFiles = [];
         const stackArtifactsEnabled = (0, utils_js_1.transformEnvVarToBoolean)(process.env.TESTOMATIO_STACK_ARTIFACTS);
         const { time = 0, example = null, filesBuffers = [], code = null, file, suite_id, test_id, timestamp, links, 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);
             files = files.filter(f => !isStepArtifact(f));
@@ -229,6 +233,11 @@ class Client {
                 acc[key] = value;
             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 = '';
         if (error) {
@@ -335,8 +344,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) {
                 debug('\n', constants_js_1.APP_PREFIX, `🗄️ ${this.uploader.successfulUploads.length} artifacts uploaded to S3 bucket`);

package/lib/data-storage.js

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

package/lib/fetch/report.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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}
+ */
+export function renderRunReport({ run, runUrl, summary, testruns, matched, statuses }: {
+    run: object;
+    runUrl: string;
+    summary: {
+        total: number;
+        byStatus: Record<string, number>;
+    };
+    testruns: object[];
+    matched: number;
+    statuses: string[];
+}): string;
+/**
+ * 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}
+ */
+export function toReportTest(testrun: object): object;

package/lib/fetch/report.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderRunReport = renderRunReport;
+exports.toReportTest = toReportTest;
+const markdown_js_1 = require("../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((0, markdown_js_1.renderTests)(testruns.map(toReportTest)));
+    return `${sections.join('\n\n')}\n`;
+}
+
+module.exports.renderRunReport = renderRunReport;
+
+module.exports.toReportTest = toReportTest;

package/lib/fetch/testruns.d.ts

@@ -0,0 +1,133 @@
+export const TESTRUNS_DEFAULT_LIMIT: 50;
+export const TESTRUNS_MAX_LIMIT: 100;
+export const TESTRUN_STATUSES: string[];
+/**
+ * Read-only client for a single run and its testruns in API v2.
+ */
+export class RunFetcher {
+    /**
+     * @param {{baseUrl: string, project: string, runId: string, apiKey: string}} params
+     */
+    constructor({ baseUrl, project, runId, apiKey }: {
+        baseUrl: string;
+        project: string;
+        runId: string;
+        apiKey: string;
+    });
+    baseUrl: string;
+    project: string;
+    runId: string;
+    apiKey: string;
+    get runUrl(): string;
+    get(apiPath: any, params?: any[]): Promise<any>;
+    fetchRun(): Promise<any>;
+    /**
+     * @param {string[]} statuses
+     * @returns {string[][]}
+     */
+    testrunParams(statuses?: string[]): string[][];
+    /**
+     * @param {string[]} [statuses]
+     * @returns {Promise<number>}
+     */
+    countTestruns(statuses?: string[]): Promise<number>;
+    /**
+     * @returns {Promise<{total: number, byStatus: Record<string, number>}>}
+     */
+    countTestrunsByStatus(): Promise<{
+        total: number;
+        byStatus: Record<string, number>;
+    }>;
+    /**
+     * Testruns with failures first; the list has no stack and no artifacts.
+     *
+     * @param {{statuses?: string[], limit: number}} params
+     * @returns {Promise<{testruns: object[], total: number}>}
+     */
+    listTestruns({ statuses, limit }: {
+        statuses?: string[];
+        limit: number;
+    }): Promise<{
+        testruns: object[];
+        total: number;
+    }>;
+    /**
+     * 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
+     */
+    addTestrunDetails(testruns: object[], onError: (testrun: object, err: Error) => void): Promise<any[]>;
+    /**
+     * 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
+     */
+    applySharedS3Credentials(run: {
+        status?: string;
+        kind?: string;
+    }): Promise<boolean>;
+}
+/**
+ * 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}}
+ */
+export function resolveRunTarget(runArg: string, opts: {
+    project?: string;
+}): {
+    baseUrl: string;
+    project: string;
+    runId: string;
+};
+/**
+ * Collect the statuses passed with --only and --only-failed.
+ *
+ * @param {{only?: string, onlyFailed?: boolean}} opts
+ * @returns {string[]}
+ */
+export function parseStatuses(opts: {
+    only?: string;
+    onlyFailed?: boolean;
+}): string[];
+/**
+ * @param {string} [value] - Value of the CLI --limit option.
+ * @returns {{limit: number, capped: boolean}}
+ */
+export function parseTestrunsLimit(value?: string): {
+    limit: number;
+    capped: boolean;
+};
+/**
+ * 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[]>}
+ */
+export function mapWithLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+/**
+ * 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
+ */
+export function downloadArtifacts(testruns: object[], outDir: string, onError: (url: string, err: Error) => void): Promise<any[]>;
+/**
+ * @param {{title?: string}} run
+ * @param {string} runId
+ * @returns {string}
+ */
+export function defaultArtifactsDir(run: {
+    title?: string;
+}, runId: string): string;