feat(core): add merge action to report-tool CLI (#2497)

* feat(core): add merge action to report-tool CLI

Add a `merge` action to the generic `report-tool` command so multiple
HTML reports produced by separate CLI invocations can be combined into
a single report without writing custom scripts. Expose the matching
`mergeReportFiles` helper from `@midscene/core` as a JS SDK so the
same workflow is reachable in code.

- `report-tool --action merge` accepts `--htmlPaths` (JSON array or
  comma-separated list) plus optional `--outputDir`, `--outputName`,
  and `--overwrite`. Source paths may be HTML files or directories
  containing `index.html`.
- `ReportMergingTool.mergeReports` now accepts an optional `outputDir`
  override; default behavior (write under `midscene_run/report`) is
  unchanged, so existing callers (Playwright reporter, etc.) are not
  affected.
- The CLI auto-derives `testTitle` / `testDescription` from each
  source report's `groupName` / `groupDescription`, so users do not
  have to supply per-report metadata.
- Update EN/ZH `consume-report-file` docs with CLI and SDK examples.

* refactor(shared): accumulate repeated CLI flags into arrays

Repeated `--key value` (or `--key=value`) flags now collect into a
string array via `parseCliArgs`, so command schemas can opt into
yargs-style multi-value inputs without ad-hoc CSV/JSON splitting.

* refactor(core): switch report-tool merge to repeated --htmlReport flag

Replace the JSON/CSV `--htmlPaths` argument with the more idiomatic
`--htmlReport` flag, accumulating repeated occurrences into an array
via the shared `parseCliArgs` helper. The handler also accepts a
single string value, and the merge action now reads from `htmlReport`.

Adds an end-to-end test that drives the merge action through
`runToolsCLI` argv to exercise parsing + schema validation + handler
in one path.

* docs(site): document repeated --htmlReport flag for report-tool merge

Update the bilingual report-file consumption guide to show the new
yargs-style invocation with one `--htmlReport` per source report.

* docs(site): remove summary paragraph from report parsing docs (#2536)

---------

Co-authored-by: yuyutaotao <167746126+yuyutaotao@users.noreply.github.com>

Author: quanru

apps/site/docs/en/consume-report-file.md

@@ -61,12 +61,27 @@ Convert the report file into Markdown and write the result into the `output-mark
 npx @midscene/web report-tool --action to-markdown --htmlPath ./midscene_run/report/puppeteer-2026/index.html --outputDir ./output-markdown
 ```
 
+Merge multiple report files into a single combined report:
+
+```shell
+npx @midscene/web report-tool --action merge-html \
+  --htmlReport ./midscene_run/report/case-a/index.html \
+  --htmlReport ./midscene_run/report/case-b.html \
+  --outputDir ./merged --outputName all-cases
+```
+
+Repeat `--htmlReport` once per source report. `--outputDir` and `--outputName` are optional; when omitted, the merged file is written to the default Midscene report directory with an auto-generated name. Pass `--overwrite` to replace an existing merged file.
+
 ## Parse With The JavaScript SDK
 
-If you prefer to control report parsing in code, use `splitReportFile` and `reportFileToMarkdown` from `@midscene/core`.
+If you prefer to control report parsing in code, use `splitReportFile`, `reportFileToMarkdown`, and `mergeReportFiles` from `@midscene/core`.
 
 ```ts
-import { reportFileToMarkdown, splitReportFile } from '@midscene/core';
+import {
+  mergeReportFiles,
+  reportFileToMarkdown,
+  splitReportFile,
+} from '@midscene/core';
 
 const splitResult = splitReportFile({
   htmlPath: './midscene_run/report/puppeteer-2026/index.html',
@@ -79,14 +94,24 @@ const markdownResult = await reportFileToMarkdown({
   outputDir: './output-markdown',
 });
 console.log(markdownResult.markdownFiles);
+
+const mergedResult = mergeReportFiles({
+  htmlPaths: [
+    './midscene_run/report/case-a/index.html',
+    './midscene_run/report/case-b.html',
+  ],
+  outputDir: './merged',
+  outputName: 'all-cases',
+});
+console.log(mergedResult.mergedReportPath);
 ```
 
-`splitReportFile` and `reportFileToMarkdown` serve different outputs:
+`splitReportFile`, `reportFileToMarkdown`, and `mergeReportFiles` serve different outputs:
 
 - `splitReportFile` generates JSON files for the original structured objects (one `*.execution.json` per execution). The JSON keeps the raw `ReportActionDump`-style data and exports screenshots alongside it. The returned `executionJsonFiles` and `screenshotFiles` are lists of generated file paths.
 - `reportFileToMarkdown` converts the same report into human-readable Markdown and exports the screenshots referenced by that Markdown. The returned `markdownFiles` contains the generated Markdown file paths.
+- `mergeReportFiles` combines several report files into one merged HTML report. It is a thin wrapper over [`ReportMergingTool`](./api#new-reportmergingtool) that derives `testTitle`/`testDescription` from each source report's `groupName` automatically. Use it when you run multiple CLI actions or tests and want to consolidate their reports.
 
-Use `splitReportFile` when you want the most complete, programmatic raw data. Use `reportFileToMarkdown` when you want readable content for summarization or downstream content generation.
 
 ## About Fields In JSON And Markdown
 

apps/site/docs/zh/consume-report-file.md

@@ -61,12 +61,27 @@ npx @midscene/web report-tool --action split --htmlPath ./midscene_run/report/pu
 npx @midscene/web report-tool --action to-markdown --htmlPath ./midscene_run/report/puppeteer-2026/index.html --outputDir ./output-markdown
 ```
 
+将多个报告文件合并为一份汇总报告：
+
+```shell
+npx @midscene/web report-tool --action merge-html \
+  --htmlReport ./midscene_run/report/case-a/index.html \
+  --htmlReport ./midscene_run/report/case-b.html \
+  --outputDir ./merged --outputName all-cases
+```
+
+每多合并一份报告就重复一次 `--htmlReport`。`--outputDir` 和 `--outputName` 都是可选项，留空时合并后的报告会写入 Midscene 默认的报告目录、并生成自动文件名。已存在同名文件时使用 `--overwrite` 进行覆盖。
+
 ## 使用 JavaScript SDK 解析
 
-如果你希望在代码里控制报告解析，可以使用 `@midscene/core` 提供的 `splitReportFile` 和 `reportFileToMarkdown`。
+如果你希望在代码里控制报告解析，可以使用 `@midscene/core` 提供的 `splitReportFile`、`reportFileToMarkdown` 和 `mergeReportFiles`。
 
 ```ts
-import { reportFileToMarkdown, splitReportFile } from '@midscene/core';
+import {
+  mergeReportFiles,
+  reportFileToMarkdown,
+  splitReportFile,
+} from '@midscene/core';
 
 const splitResult = splitReportFile({
   htmlPath: './midscene_run/report/puppeteer-2026/index.html',
@@ -79,14 +94,24 @@ const markdownResult = await reportFileToMarkdown({
   outputDir: './output-markdown',
 });
 console.log(markdownResult.markdownFiles);
+
+const mergedResult = mergeReportFiles({
+  htmlPaths: [
+    './midscene_run/report/case-a/index.html',
+    './midscene_run/report/case-b.html',
+  ],
+  outputDir: './merged',
+  outputName: 'all-cases',
+});
+console.log(mergedResult.mergedReportPath);
 ```
 
-`splitReportFile` 和 `reportFileToMarkdown` 的用途不同：
+`splitReportFile`、`reportFileToMarkdown` 和 `mergeReportFiles` 的用途不同：
 
 - `splitReportFile` 会产出“原始对象”对应的 JSON 文件（每个 execution 一个 `*.execution.json`），内容是 `ReportActionDump` 的原始结构化数据，同时会导出截图文件。返回值中的 `executionJsonFiles` 和 `screenshotFiles` 都是生成后的文件路径列表。
 - `reportFileToMarkdown` 会把同一份报告转成更易读、便于给其他工具继续处理的 Markdown 文本，并导出 Markdown 里引用到的截图。返回值里的 `markdownFiles` 对应 Markdown 文件路径。
+- `mergeReportFiles` 会把多份报告合并成一份汇总 HTML 报告，是 [`ReportMergingTool`](./api#new-reportmergingtool) 的轻量封装：会自动从每份源报告里读取 `groupName` 作为 `testTitle`/`testDescription`，省去了手工准备 `reportAttributes` 的步骤。命令行多次调用或多个测试用例产生多份报告后，使用它进行汇总最为合适。
 
-如果你想保留最完整、可编程处理的数据，优先使用 `splitReportFile`；如果你想直接阅读、总结，或用于二次生成（例如生成视频脚本），优先使用 `reportFileToMarkdown`。
 
 ## 关于 JSON 和 Markdown 的内容字段
 

packages/core/src/index.ts

@@ -84,11 +84,14 @@ export {
   createReportCliCommands,
   reportFileToMarkdown,
   splitReportFile,
+  mergeReportFiles,
   type ConsumeReportFileAction,
   type ReportFileToMarkdownOptions,
   type ReportCliCommandDefinition,
   type ReportCliCommandEntry,
   type SplitReportFileOptions,
+  type MergeReportFilesOptions,
+  type MergeReportFilesResult,
 } from './report-cli';
 
 // ScreenshotItem

packages/core/src/report-cli.ts

@@ -8,9 +8,14 @@ import {
 import * as path from 'node:path';
 import { z } from 'zod';
 import { resolveScreenshotSource } from './dump/screenshot-store';
-import { collectDedupedExecutions, splitReportHtmlByExecution } from './report';
+import {
+  ReportMergingTool,
+  collectDedupedExecutions,
+  splitReportHtmlByExecution,
+} from './report';
 import { reportToMarkdown } from './report-markdown';
 import type { MarkdownAttachment } from './report-markdown';
+import type { ReportFileAttributes, TestStatus } from './types';
 import { ReportActionDump } from './types';
 
 type ReportCliToolResult = {
@@ -35,7 +40,7 @@ export interface ReportCliCommandEntry {
   def: ReportCliCommandDefinition;
 }
 
-export type ConsumeReportFileAction = 'split' | 'to-markdown';
+export type ConsumeReportFileAction = 'split' | 'to-markdown' | 'merge-html';
 
 export interface ConsumeReportFileOptions {
   htmlPath: string;
@@ -45,6 +50,17 @@ export interface ConsumeReportFileOptions {
 export type SplitReportFileOptions = ConsumeReportFileOptions;
 export type ReportFileToMarkdownOptions = ConsumeReportFileOptions;
 
+export interface MergeReportFilesOptions {
+  htmlPaths: string[];
+  outputDir?: string;
+  outputName?: string;
+  overwrite?: boolean;
+}
+
+export interface MergeReportFilesResult {
+  mergedReportPath: string;
+}
+
 function writeAttachmentFromReport(
   attachment: MarkdownAttachment,
   opts: {
@@ -200,42 +216,172 @@ export async function reportFileToMarkdown(
   return markdownFromReport(resolvedHtmlPath, outputDir);
 }
 
+function deriveReportAttributesFromHtml(
+  htmlPath: string,
+  index: number,
+): ReportFileAttributes {
+  const fallbackId = `${path.basename(path.dirname(htmlPath)) || path.basename(htmlPath, path.extname(htmlPath))}-${index + 1}`;
+  try {
+    const { baseDump } = collectDedupedExecutions(htmlPath);
+    return {
+      testId: fallbackId,
+      testTitle: baseDump.groupName || fallbackId,
+      testDescription: baseDump.groupDescription ?? '',
+      testDuration: 0,
+      testStatus: 'passed' as TestStatus,
+    };
+  } catch {
+    return {
+      testId: fallbackId,
+      testTitle: fallbackId,
+      testDescription: '',
+      testDuration: 0,
+      testStatus: 'passed' as TestStatus,
+    };
+  }
+}
+
+export function mergeReportFiles(
+  options: MergeReportFilesOptions,
+): MergeReportFilesResult {
+  const { htmlPaths, outputDir, outputName, overwrite = false } = options;
+  if (!htmlPaths || htmlPaths.length === 0) {
+    throw new Error('mergeReportFiles: htmlPaths is required');
+  }
+
+  const resolvedPaths = htmlPaths.map((p) => resolveReportHtmlPath(p));
+
+  const tool = new ReportMergingTool();
+  resolvedPaths.forEach((htmlPath, index) => {
+    tool.append({
+      reportFilePath: htmlPath,
+      reportAttributes: deriveReportAttributesFromHtml(htmlPath, index),
+    });
+  });
+
+  const mergedReportPath = tool.mergeReports(outputName ?? 'AUTO', {
+    overwrite,
+    outputDir,
+  });
+
+  if (!mergedReportPath) {
+    throw new Error('mergeReportFiles: failed to produce a merged report');
+  }
+
+  return { mergedReportPath };
+}
+
+function normalizeHtmlReportArg(raw: unknown): string[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (Array.isArray(raw)) {
+    return raw.filter(
+      (p): p is string => typeof p === 'string' && p.length > 0,
+    );
+  }
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  return undefined;
+}
+
 const reportCommandDefinition: ReportCliCommandDefinition = {
   name: 'report-tool',
   description:
-    'Transform Midscene report artifacts, including splitting executions and converting to markdown.',
+    'Transform Midscene report artifacts, including splitting executions, converting to markdown, and merging multiple reports.',
   schema: {
     action: z
-      .enum(['split', 'to-markdown'])
+      .enum(['split', 'to-markdown', 'merge-html'])
       .optional()
       .describe(
-        'Report action to run. Supports: split, to-markdown. Defaults to split.',
+        'Report action to run. Supports: split, to-markdown, merge-html. Defaults to split.',
       ),
     htmlPath: z
       .string()
       .optional()
-      .describe('Input report HTML path (e.g. ./report/index.html)'),
+      .describe(
+        'Input report HTML path (e.g. ./report/index.html). Used by split and to-markdown.',
+      ),
+    htmlReport: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .describe(
+        'Input report HTML path for the merge action. Repeat the flag to merge multiple reports (e.g. --htmlReport ./a/index.html --htmlReport ./b.html).',
+      ),
     outputDir: z
       .string()
       .optional()
-      .describe('Output directory for generated report artifacts'),
+      .describe(
+        'Output directory for generated report artifacts. For merge, defaults to the Midscene report directory.',
+      ),
+    outputName: z
+      .string()
+      .optional()
+      .describe(
+        'Output report file/directory name (without .html) for the merge action. Defaults to an auto-generated name.',
+      ),
+    overwrite: z
+      .union([z.boolean(), z.string()])
+      .optional()
+      .describe(
+        'Overwrite the existing merged report file if present (merge action only).',
+      ),
   },
   handler: async (args) => {
     const {
       action = 'split',
       htmlPath,
+      htmlReport,
       outputDir,
+      outputName,
+      overwrite,
     } = args as {
       action?: string;
       htmlPath?: string;
+      htmlReport?: unknown;
       outputDir?: string;
+      outputName?: string;
+      overwrite?: unknown;
     };
-    if (action !== 'split' && action !== 'to-markdown') {
+    if (
+      action !== 'split' &&
+      action !== 'to-markdown' &&
+      action !== 'merge-html'
+    ) {
       throw new Error(
-        `report-tool: unsupported --action value "${action}". Currently supported: split, to-markdown`,
+        `report-tool: unsupported --action value "${action}". Currently supported: split, to-markdown, merge-html`,
       );
     }
 
+    if (action === 'merge-html') {
+      const paths = normalizeHtmlReportArg(htmlReport);
+      if (!paths || paths.length === 0) {
+        throw new Error(
+          'report-tool: --htmlReport is required for action "merge-html". Repeat --htmlReport for each report (e.g. --htmlReport ./a/index.html --htmlReport ./b.html).',
+        );
+      }
+
+      const overwriteFlag =
+        overwrite === true || overwrite === 'true' || overwrite === '1';
+
+      const result = mergeReportFiles({
+        htmlPaths: paths,
+        outputDir,
+        outputName,
+        overwrite: overwriteFlag,
+      });
+
+      return {
+        isError: false,
+        content: [
+          {
+            type: 'text',
+            text: `Merged ${paths.length} report(s) into ${result.mergedReportPath}`,
+          },
+        ],
+      };
+    }
+
     if (!htmlPath) {
       throw new Error('report-tool: --htmlPath is required');
     }

packages/core/src/report.ts

@@ -142,16 +142,26 @@ export class ReportMergingTool {
     opts?: {
       rmOriginalReports?: boolean;
       overwrite?: boolean;
+      outputDir?: string;
     },
   ): string | null {
-    const { rmOriginalReports = false, overwrite = false } = opts ?? {};
+    const {
+      rmOriginalReports = false,
+      overwrite = false,
+      outputDir,
+    } = opts ?? {};
 
     if (this.reportInfos.length === 0) {
       logMsg('No reports to merge');
       return null;
     }
 
-    const targetDir = getMidsceneRunSubDir('report');
+    const targetDir = outputDir
+      ? path.resolve(outputDir)
+      : getMidsceneRunSubDir('report');
+    if (outputDir) {
+      mkdirSync(targetDir, { recursive: true });
+    }
 
     // Check if any source report is directory mode
     const hasDirectoryModeReport = this.reportInfos.some((info) => {