monocart-reporter 2.7.0 → 2.8.0

package/README.md

@@ -74,7 +74,7 @@ module.exports = {
         ['list'],
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html'
+            outputFile: './monocart-report/index.html'
         }]
     ]
 };
@@ -89,86 +89,13 @@ Playwright Docs [https://playwright.dev/docs/test-reporters](https://playwright.
 ## Output
 - path-to/your-filename.html  
 Single HTML file (data compressed), easy to transfer/deploy or open directly anywhere   
-> Note: Test attachments (screenshots images/videos) are not included but linked with relative path in report. All attachments will be found in [playwrightConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir)
-```js
-// playwright.config.js
-// attachments outputDir and report outputFile used same folder
-const date = new Date().toISOString().slice(0, 10); //2022-10-10
-const outputDir = `./test-results/${date}`;
-module.exports = {
-    outputDir: outputDir,
-    reporter: [
-        ['monocart-reporter', {  
-            name: `My Test Report ${date}`,
-            outputFile: `${outputDir}/index.html`
-        }]
-    ]
-};
-// deploy the folder to your report site and easy checking online
-// http://your.report.site/test-results/2022-10-10
-```
+> Note: All attachments (screenshots images/videos) will be linked with relative path in report.
 - path-to/your-filename.json  
-Separated metadata file (Already included in the above HTML and compressed, it can be deleted). Can be used for debugging or custom data collection.
+Separated data file which can be used for debugging or data provider (It's included in the above HTML and compressed).
 
 ## Reporter Options
-```js
-{
-    // the report name
-    name: '',
-
-    // the output file path (relative process.cwd)
-    outputFile: './test-results/report.html',
-
-    // attachment path handler
-    attachmentPath: null,
-    // attachmentPath: (currentPath, extras) => `https://another-path/${currentPath}`,
-
-    traceViewerUrl: 'https://trace.playwright.dev/?trace={traceUrl}',
-
-    // logging levels: off, error, info, debug
-    logging: 'info',
-
-    // timezone offset in minutes, GMT+0800 = -480
-    timezoneOffset: 0,
-
-    // global coverage settings for addCoverageReport API
-    coverage: null,
-    // coverage: {
-    //     entryFilter: (entry) => true,
-    //     sourceFilter: (sourcePath) => sourcePath.search(/src\/.+/) !== -1,
-    // },
-
-    // trend data handler
-    trend: null,
-    // trend: () => './test-results/report.json',
-
-    // custom tags style
-    tags: null,
-    // tags: {
-    //     smoke: {
-    //         'background': '#6F9913'
-    //     },
-    //     sanity: {
-    //         'background': '#178F43'
-    //     }
-    // },
-
-    // columns data handler
-    columns: null,
-    // columns: (defaultColumns) => {},
-
-    // rows data handler (suite, case and step)
-    visitor: null,
-    // visitor: (data, metadata) => {},
-
-    // enable/disable custom fields in comments. Defaults to true.
-    customFieldsInComments: true,
-
-    // onEnd hook
-    onEnd: null
-    // onEnd: async (reportData, helper) => {}
-}
-```
+- Default options: [lib/default/options.js](./lib/default/options.js)
+- Options declaration see `MonocartReporterOptions` [lib/index.d.ts](./lib/index.d.ts)
 
 ## View Trace Online 
 > The [Trace Viewer](https://trace.playwright.dev/) requires that the trace file must be loaded over the http:// or https:// protocols without [CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS) issue.
@@ -185,7 +112,7 @@ The server add the http header `Access-Control-Allow-Origin: *` to [allow reques
 ```sh
 npx monocart show-report <path-to-report> --ssl <path-to-key,path-to-cert>
 ```
-For example: `npx monocart show-report test-results/index.html --ssl ssl/key.pem,ssl/cert.pem`
+For example: `npx monocart show-report monocart-report/index.html --ssl ssl/key.pem,ssl/cert.pem`
 
 You can create and install local CA with [mkcert](https://mkcert.dev)
 - Using your own trace viewer url with option `traceViewerUrl`:
@@ -193,7 +120,7 @@ You can create and install local CA with [mkcert](https://mkcert.dev)
 // reporter options
 {
     name: "My Test Report",
-    outputFile: './test-results/report.html',
+    outputFile: './monocart-report/index.html',
     // defaults to 'https://trace.playwright.dev/?trace={traceUrl}'
     traceViewerUrl: 'https://your-own-trace-viewer-url/?trace={traceUrl}'
 }
@@ -228,7 +155,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
 
             // custom columns
             columns: (defaultColumns) => {
@@ -270,7 +197,7 @@ module.exports = {
      reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             columns: (defaultColumns) => {
 
                 // duration formatter
@@ -308,7 +235,7 @@ module.exports = {
      reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             columns: (defaultColumns) => {
                 const locationColumn = defaultColumns.find((column) => column.id === 'location');
                 locationColumn.searchable = true;
@@ -413,7 +340,7 @@ module.exports = {
      reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             mermaid: {
                 // mermaid script url, using mermaid CDN: https://www.jsdelivr.com/package/npm/mermaid
                 scriptSrc: 'https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js',
@@ -494,7 +421,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             visitor: (data, metadata) => {
                 // [MCR-123] collect data from the title
                 const matchResult = metadata.title.match(/\[(.+)\]/);
@@ -524,7 +451,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             visitor: (data, metadata) => {
                 // collect data from the annotations
                 if (metadata.annotations) {
@@ -547,7 +474,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             visitor: (data, metadata) => {
                 const mySecrets = [process.env.PASSWORD, process.env.TOKEN];
                 mySecrets.forEach((secret) => {
@@ -588,7 +515,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             tags: {
                 smoke: {
                     style: {
@@ -612,7 +539,7 @@ module.exports = {
         ['list'],
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             tags: {
                 // ...
             },
@@ -656,7 +583,7 @@ module.exports = {
      reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html'
+            outputFile: './monocart-report/index.html'
         }]
     ]
 };
@@ -723,9 +650,9 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             // connect previous report data for trend chart
-            trend: './test-results/report.json'
+            trend: './monocart-report/index.json'
         }]
     ]
 };
@@ -741,7 +668,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             // connect previous report data for trend chart
             trend: async () => {
                 const previousReportData = await readDataFromSomeWhere("path-to/report.json");
@@ -778,7 +705,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             // global coverage report options
             coverage: {
                 entryFilter: (entry) => true,
@@ -992,7 +919,7 @@ module.exports = {
         ['list'],
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             state: {
                 data: {
                     count: 0
@@ -1060,7 +987,7 @@ module.exports = {
         ['list'],
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             state: {
                 onReceive: function(message) {
                     const test = this.getTest(message.testId);
@@ -1086,7 +1013,9 @@ npx playwright test --shard=1/3
 npx playwright test --shard=2/3
 npx playwright test --shard=3/3
 ```
-There are 3 reports will be generated. Using `merge(reportDataList, options)` API to merge all reports into one.
+There are 3 reports will be generated. 
+
+### Using `merge` API to merge all reports into one
 > Note: One more suite level "shard" will be added, its title will be the machine hostname, and the summary will be restated. All attachments will be copied to the merged output directory.
 ```js
 import { merge } from 'monocart-reporter';
@@ -1106,8 +1035,6 @@ await merge(reportDataList, {
     }
 });
 ```
-see example [merge.js](https://github.com/cenfun/monocart-reporter-examples/blob/main/scripts/merge.js)
-
 > Note: The coverage reports will be merged automatically if we specify the `raw` report in coverage options:
 ```js
 // global coverage options
@@ -1118,6 +1045,19 @@ coverage: {
     ]
 }
 ```
+see example [merge.js](https://github.com/cenfun/monocart-reporter-examples/blob/main/scripts/merge.js)
+
+### Using `merge` CLI
+```sh
+npx monocart merge <glob-patterns>
+
+# -o --outputFile
+npx monocart merge path-to/shard*/index.json -o merged-reports/index.html
+
+# -c --config
+npx monocart merge path-to/shard*/index.json -c mr.config.js
+```
+
 
 ## onEnd Hook
 The `onEnd` function will be executed after report generated. Arguments:
@@ -1149,7 +1089,7 @@ module.exports = {
     reporter: [
         ['monocart-reporter', {  
             name: "My Test Report",
-            outputFile: './test-results/report.html',
+            outputFile: './monocart-report/index.html',
             // async hook after report data generated
             onEnd: async (reportData, helper) => {
                 // console.log(reportData.summary);

package/lib/cli.js

@@ -6,15 +6,27 @@ const http = require('http');
 const https = require('https');
 const net = require('net');
 const os = require('os');
+const { pathToFileURL } = require('url');
 const EC = require('eight-colors');
 const KSR = require('koa-static-resolver');
 const Koa = require('koa');
 const CG = require('console-grid');
 
-const { program, open } = require('./packages/monocart-reporter-vendor.js');
+const Util = require('./utils/util.js');
+const {
+    program, open, glob, findUpSync, supportsColor
+} = require('./packages/monocart-reporter-vendor.js');
 const getDefaultOptions = require('./default/options.js');
+const merge = require('./merge-data.js');
 const version = require('../package.json').version;
 
+// https://github.com/chalk/supports-color
+// disabled color if Terminal stdout does not support color
+if (!supportsColor.stdout) {
+    EC.disabled = true;
+}
+
+
 const getInternalIps = () => {
     const n = os.networkInterfaces();
     // console.log(n);
@@ -153,6 +165,93 @@ const serveReport = async (p, options) => {
 
 };
 
+const findUpConfig = (customConfigFile) => {
+    if (customConfigFile) {
+        if (fs.existsSync(customConfigFile)) {
+            return customConfigFile;
+        }
+        // custom config not found
+        return;
+    }
+
+    const defaultConfigList = [
+        'mr.config.js',
+        'mr.config.cjs',
+        'mr.config.mjs',
+        'mr.config.json',
+        'mr.config.ts'
+    ];
+
+    const configPath = findUpSync(defaultConfigList);
+    if (configPath) {
+        return configPath;
+    }
+
+    // default config not found
+};
+
+const resolveConfigOptions = async (configPath) => {
+    // json format
+    const ext = path.extname(configPath);
+    if (ext === '.json' || configPath.slice(-2) === 'rc') {
+        return JSON.parse(Util.readFileSync(configPath));
+    }
+
+    let configOptions;
+    let err;
+    try {
+        configOptions = await import(pathToFileURL(configPath));
+    } catch (ee) {
+        err = ee;
+    }
+
+    if (err) {
+        Util.logError(`ERROR: failed to load config "${configPath}": ${err && err.message} `);
+        return;
+    }
+
+    // could be multiple level default
+    while (configOptions && configOptions.default) {
+        configOptions = configOptions.default;
+    }
+
+    return configOptions;
+};
+
+const mergeReports = async (str, cliOptions) => {
+
+    const customConfig = cliOptions.config;
+    const configPath = findUpConfig(customConfig);
+
+    let configOptions = {};
+    if (configPath) {
+        configOptions = await resolveConfigOptions(configPath);
+    } else {
+        if (customConfig) {
+            Util.logError(`ERROR: not found config file: ${customConfig}`);
+            return;
+        }
+    }
+
+    const options = {
+        ... getDefaultOptions(),
+        ... configOptions,
+        ... cliOptions
+    };
+
+    Util.initLoggingLevel(options.logging);
+
+    const files = await glob(str);
+    if (!Util.isList(files)) {
+        Util.logError(`ERROR: no files found with glob: ${str}`);
+        return;
+    }
+    // console.log(files, options);
+
+    await merge(files, options);
+
+};
+
 program
     .name('monocart')
     .description('CLI to serve monocart reporter')
@@ -177,6 +276,19 @@ program.command('serve-report')
         serveReport(str, options);
     });
 
+program.command('merge-reports')
+    .alias('merge')
+    .description('Merge reports')
+    .argument('<path>', 'path to report dirs')
+    .option('-c, --config <path>', 'config file')
+
+    .option('-n, --name <name>', 'report name for title')
+    .option('-o, --outputFile <path>', 'output file')
+
+    .action((str, options) => {
+        mergeReports(str, options);
+    });
+
 program.addHelpText('after', `
 Starts ${EC.cyan('https')} with option --ssl:
     npx monocart show-report <path-to-report> ${EC.cyan('--ssl <path-to-key,path-to-cert>')}

package/lib/default/options.js

@@ -1,19 +1,24 @@
 module.exports = () => ({
+    // logging levels: off, error, info, debug
+    logging: 'info',
+
     // the report name
     name: '',
 
-    // the output file path (relative process.cwd)
-    outputFile: './test-results/report.html',
+    // the output html file path (relative process.cwd)
+    outputFile: './monocart-report/index.html',
+
+    // whether to copy attachments to the reporter output dir, defaults to true
+    // it is useful when there are multiple html reports being output.
+    copyAttachments: true,
 
     // attachment path handler
     attachmentPath: null,
     // attachmentPath: (currentPath, extras) => `https://cenfun.github.io/monocart-reporter/${currentPath}`,
 
+    // custom trace viewer url
     traceViewerUrl: 'https://trace.playwright.dev/?trace={traceUrl}',
 
-    // logging levels: off, error, info, debug
-    logging: 'info',
-
     // timezone offset in minutes, GMT+0800 = -480
     timezoneOffset: 0,
 
@@ -24,11 +29,12 @@ module.exports = () => ({
     //     sourceFilter: (sourcePath) => sourcePath.search(/src\/.+/) !== -1,
     // },
 
+    // Global State Management
     state: null,
 
     // trend data handler
     trend: null,
-    // trend: () => './test-results/report.json',
+    // trend: () => './monocart-report/index.json',
 
     // custom tags style
     tags: null,

package/lib/generate-data.js

@@ -76,21 +76,11 @@ const generateData = async (results) => {
         trends
     } = results;
 
-    // console.log(config);
-    const cwd = Util.formatPath(process.cwd());
-
-    const outputFile = await Util.resolveOutputFile(options.outputFile);
-    // init outputDir
-    const outputDir = path.dirname(outputFile);
-    if (!fs.existsSync(outputDir)) {
-        fs.mkdirSync(outputDir, {
-            recursive: true
-        });
-    }
-    // for visitor relative path of attachments
-    options.cwd = cwd;
-    options.outputDir = outputDir;
+    const {
+        cwd, outputFile, outputDir
+    } = options;
 
+    // console.log(config);
     const visitor = new Visitor(root, options);
     await visitor.start();
 

package/lib/generate-report.js

@@ -183,8 +183,17 @@ const onEndHandler = async (reportData, options) => {
     await onEnd(reportData, helper);
 };
 
+const onDataHandler = async (reportData, options, rawData) => {
+    // onData callback
+    const onData = options.onData;
+    if (typeof onData !== 'function') {
+        return;
+    }
+    await onData(reportData, rawData);
+};
 
-const generateReport = async (reportData, options) => {
+
+const generateReport = async (reportData, options, rawData) => {
 
     Util.logInfo('generating test report ...');
 
@@ -197,7 +206,9 @@ const generateReport = async (reportData, options) => {
             const g = report.global ? `${EC.magenta('(global)')}` : '';
             Util.logInfo(`${report.type}: ${EC.cyan(report.path)} ${report.name} ${g}`);
             // convert path to relative reporter
-            report.path = Util.relativePath(report.path, outputDir);
+            if (report.path) {
+                report.path = Util.relativePath(report.path, outputDir);
+            }
         });
 
         reportData.summary.artifacts = {
@@ -207,6 +218,8 @@ const generateReport = async (reportData, options) => {
 
     }
 
+    await onDataHandler(reportData, options, rawData);
+
     // console.log(reportData);
     const htmlFile = path.basename(outputFile);