monocart-reporter 1.6.19 → 1.6.21

package/README.md

@@ -17,16 +17,17 @@
 * [Install](#install)
 * [Playwright Config](#playwright-config)
 * [Examples](#examples)
-* [Output](#output) HTML file and JSON file
-* [Viewing Trace Online](#viewing-trace-online)
+* [Output](#output) HTML and JSON
+* [View Trace Online](#view-trace-online)
 * [Reporter Options](#reporter-options)
-* [Custom Columns](#custom-columns) (extra properties for suite/case/step)
+* [Custom Columns](#custom-columns) (Extra properties for suite/case/step)
     - [Custom Formatter](#custom-formatter)
     - [Searchable Fields](#searchable-fields)
-* [Data Collection Visitor](#data-collection-visitor) (extra data collection for suite/case/step)
-    - [Adding Comments to Your Tests](#adding-comments-to-your-tests)
-    - [Removing Secrets and Sensitive Data from Report](#removing-secrets-and-sensitive-data-from-report)
-Support
+* [Custom Data Visitor](#custom-data-visitor) (Extra data collection for suite/case/step)
+    - [Collect Data from the Title](#collect-data-from-the-title)
+    - [Collect Data from the Annotations](#collect-data-from-the-annotations)
+    - [Collect Data from the Comments](#collect-data-from-the-comments) (Recommended)
+    - [Remove Secrets and Sensitive Data](#remove-secrets-and-sensitive-data)
 * [Style Tags](#style-tags)
 * [Metadata](#metadata)
 * [Trend Chart](#trend-chart)
@@ -77,14 +78,12 @@ module.exports = {
 Playwright Docs [https://playwright.dev/docs/test-reporters](https://playwright.dev/docs/test-reporters)
 
 ## Examples
-- [tests/playwright.config.js](/tests/playwright.config.js)
-- [tests/example/example.spec.js](/tests/example/example.spec.js)
-- [tests/home-page/home-page.spec.js](/tests/home-page/home-page.spec.js)
-
+- [tests](/tests/)
+- [more](https://github.com/cenfun/monocart-reporter-test/tree/main/tests) 
 ## 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)
+> 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
@@ -105,7 +104,7 @@ module.exports = {
 - 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.
 
-## Viewing Trace Online 
+## 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, try following start a local web server:
 ```sh
 npx monocart show-report <your-outputFile-path>
@@ -122,7 +121,7 @@ npx monocart show-report <your-outputFile-path>
 
     // attachment path handler
     attachmentPath: null,
-    // attachmentPath: (currentPath, extras) => `https://cenfun.github.io/monocart-reporter/${currentPath}`,
+    // attachmentPath: (currentPath, extras) => `https://another-path/${currentPath}`,
 
     // trend data handler
     trend: null,
@@ -209,7 +208,7 @@ module.exports = {
 };
 ```
 ### Custom Formatter
-> Note: the `formatter` function will be serialized into string via JSON, so closures, contexts, etc. will not work!
+> Note: The `formatter` function will be serialized into string via JSON, so closures, contexts, etc. will not work!
 ```js
 // playwright.config.js
 module.exports = {
@@ -264,14 +263,74 @@ module.exports = {
 };
 ```
 
-## Data Collection Visitor
+## Custom Data Visitor
 The `visitor` function will be executed for each row item (suite, case and step). Arguments:
-- `data` data item (suite/case/step) for reporter, you can override some of its properties or add more
+- `data` data item (suite/case/step) for reporter, you can rewrite some of its properties or add more
 - `metadata` original data object from Playwright test, could be one of [Suite](https://playwright.dev/docs/api/class-suite), [TestCase](https://playwright.dev/docs/api/class-testcase) or [TestStep](https://playwright.dev/docs/api/class-teststep)
-- `collect` only one self collection for now: `collect.comments(parserOptions)` and parser options following:
-    - empty for normal CommonJs syntax by default
-    - `{ sourceType: 'module', plugins: ['typescript'] }` for typescript syntax
-    - more [https://babeljs.io/docs/babel-parser](https://babeljs.io/docs/babel-parser)
+- `collect` see [collect data from the comments](#collect-data-from-the-comments)
+
+### Collect Data from the Title
+For example, we want to parse out the jira key from the title:
+```js
+test('[MCR-123] collect data from the title', () => {
+
+});
+```
+You can simply use regular expressions to parse and get jira key:
+```js
+// playwright.config.js
+module.exports = {
+    reporter: [
+        ['monocart-reporter', {  
+            name: "My Test Report",
+            outputFile: './test-results/report.html',
+            visitor: (data, metadata, collect) => {
+                // [MCR-123] collect data from the title
+                const matchResult = metadata.title.match(/\[(.+)\]/);
+                if (matchResult && matchResult[1]) {
+                    data.jira = matchResult[1];
+                }
+            }
+        }]
+    ]
+};
+```
+
+### Collect Data from the Annotations
+It should be easier than getting from title. see [custom annotations](https://playwright.dev/docs/test-annotations#custom-annotations) via `test.info().annotations`
+```js
+test('collect data from the annotations', () => {
+    test.info().annotations.push({
+        type: "jira",
+        description: "MCR-123"
+    })
+});
+```
+```js
+// playwright.config.js
+module.exports = {
+    reporter: [
+        ['monocart-reporter', {  
+            name: "My Test Report",
+            outputFile: './test-results/report.html',
+            visitor: (data, metadata, collect) => {
+                // collect data from the annotations
+                if (metadata.annotations) {
+                    const jiraItem = metadata.annotations.find((item) => item.type === 'jira');
+                    if (jiraItem && jiraItem.description) {
+                        data.jira = jiraItem.description;
+                    }
+                }
+            }
+        }]
+    ]
+};
+```
+
+### Collect Data from the Comments
+> The code comments are good enough to provide extra information without breaking existing code, and no dependencies, clean, easy to read, etc. 
+- First, add the collection of comments in the visitor. 
+> Note: If there are any parsing error messages in red lines, try other parser options like `sourceType: 'module'` or `plugins: ['typescript']` according to your situation.
 ```js
 // playwright.config.js
 module.exports = {
@@ -281,30 +340,37 @@ module.exports = {
             outputFile: './test-results/report.html',
             // additional custom visitor for columns
             visitor: (data, metadata, collect) => {
-                // auto collect data from comments
+                
+                // auto collect data from the comments
                 const parserOptions = {
                     // Indicate the mode the code should be parsed in.
                     // Can be one of "script", "module", or "unambiguous". Defaults to "script".
                     // sourceType: 'module',
 
-                    // enable typescript syntax. more https://babeljs.io/docs/babel-parser
+                    // enable typescript syntax.
                     // plugins: ['typescript']
+
+                    // more https://babeljs.io/docs/babel-parser
                 };
                 const comments = collect.comments(parserOptions);
                 if (comments) {
+                    // Append all collected comments data to report data
                     Object.assign(data, comments);
                 }
+
             }
         }]
     ]
 };
 ```
-### Adding Comments to Your Tests
-> Compared with importing external library, code comments are good enough to provide extra information without breaking existing code, and no dependencies, clean, easy to read, etc. Each comment info starts with `@` which is similar to JSDoc.
-* Case
+
+- Then, add comments to your tests
+> Note: Each comment item must start with `@` which is similar to [JSDoc](https://jsdoc.app/).
+
+For example, we want to add `owner` and `jira` or others for the cases, steps, and suites, or rewrite the step `title`
 ```js
 /**
- * add extra information for case
+ * for case
  * @owner Kevin
  * @jira MCR-16888
  */
@@ -323,23 +389,11 @@ test('case description', () => {
 });
 
 ```
-* Describe
-```js
-/**
- * add extra information for describe
- * @owner Mark
- * @jira MCR-16900
- */
-test.describe('suite title', () => {
-
-});
-```
-* Step
 ```js
 test('case title', ({ browserName }, testInfo) => {
 
     /**
-     * override assert step title "expect.toBe" to
+     * rewrite assert step title "expect.toBe" to
      * @title my custom assert step title
      * @annotations important
      */
@@ -351,11 +405,9 @@ test('case title', ({ browserName }, testInfo) => {
     });
 
 });
-```
-* Hooks
-```js
+
 /**
- * override "beforeAll hook" title to
+ * rewrite "beforeAll hook" title to
  * @title do something before all
  */
 test.beforeAll(() => { 
@@ -363,37 +415,45 @@ test.beforeAll(() => {
 });
 
 /**
- * override "beforeEach hook" title to
+ * rewrite "beforeEach hook" title to
  * @title do something before each
  */
 test.beforeEach(() => { 
     
 });
 ```
-* File
 ```js
 /**
- * add extra information for file in the first line 
+ * for describe
+ * @owner Mark
+ * @jira MCR-16900
+ */
+test.describe('suite title', () => {
+
+});
+```
+```js
+/**
+ * for file (comment file in the first line)
  * @owner FO
  */
 const { test, expect } = require('@playwright/test');
 ```
-* Project (Can't use comments but use project `metadata`)
 ```js
+// for project (Can't use comments but use project level `metadata`)
 // playwright.config.js
 module.exports = {
-    projects: [
-        {
-            name: 'Desktop Chromium',
-            metadata: {
-                owner: 'PO'
-            }
+    projects: [{
+        name: 'Desktop Chromium',
+        metadata: {
+            owner: 'PO'
         }
-    ]
+    }]
 };  
 ```
-### Removing Secrets and Sensitive Data from Report
-> The report may hosted outside of the organization’s internal boundaries, security becomes a big issue. Any secrets or sensitive data, such as usernames, passwords, tokens and API keys, should be handled with extreme care. The following example is removing the password and token from the step title with the string replacement in `visitor` function.
+
+### Remove Secrets and Sensitive Data
+> The report may hosted outside of the organization’s internal boundaries, security becomes a big issue. Any secrets or sensitive data, such as usernames, passwords, tokens and API keys, should be handled with extreme care. The following example is removing the password and token from the report data with the string replacement in `visitor` function.
 ```js
 // playwright.config.js
 module.exports = {
@@ -464,9 +524,7 @@ module.exports = {
         executor: 'Mono',
         
         // test home page object model
-        url: 'https://www.npmjs.org/package/monocart-reporter',
-        // test addInitScript
-        clientPath: 'tests/common/client.js'
+        url: 'https://www.npmjs.org/package/monocart-reporter'
     },
      reporter: [
         ['monocart-reporter', {  
@@ -490,7 +548,7 @@ export default async (config) => {
 ```
 
 ## Trend Chart
-> Note: the trend chart requires historical data generally stored in the server database. There is a serverless solution which is connecting and collecting historical trend data from previous report data before test every time.
+> Note: The trend chart requires historical data generally stored in the server database. There is a serverless solution which is connecting and collecting historical trend data from previous report data before test every time.
 - If a report is generated in the same place every time, you can simply connect the data with the report JSON path (the data is not 100% safe if there is any runtime error, the previous output dir will be empty by Playwright but the reporter processing not finish)
 ```js
 // playwright.config.js
@@ -558,6 +616,7 @@ test('attach lighthouse audit report', async () => {
 });
 
 ```
+Preview [Audit HTML Report](https://cenfun.github.io/monocart-reporter/audit-78a0a1cc4420ee9da113/index.html)
 
 ## Attach Code Coverage Report
 Attach a code coverage report with API `attachCoverageReport(data, testInfo, options)`. Arguments:
@@ -709,7 +768,7 @@ test.describe('attach network report 1', () => {
     });
 });
 ```
-Generate har with [playwright-har](https://github.com/janzaremski/playwright-har)
+Generate HAR with [playwright-har](https://github.com/janzaremski/playwright-har)
 ```js
 import { test } from '@playwright/test';
 import { attachNetworkReport } from 'monocart-reporter';
@@ -738,6 +797,7 @@ test('finally, attach HAR', async () => {
     await attachNetworkReport(harPath, test.info());
 });
 ```
+Preview [Network HTML Report](https://cenfun.github.io/monocart-reporter/network-1a18723ee59b36867898/index.html)
 
 ## Merge Shard Reports
 There will be multiple reports to be generated if Playwright test executes in sharding mode. for example:
@@ -747,7 +807,7 @@ 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.
-> Note: one more suite level "shard" will be added, its title will be the machine hostname, and the summary will be restated. You may need to transfer the attachments by yourself and update the path of the attachments with `attachmentPath` API.
+> Note: One more suite level "shard" will be added, its title will be the machine hostname, and the summary will be restated. You may need to transfer the attachments by yourself and update the path of the attachments with `attachmentPath` API.
 ```js
 import { merge } from 'monocart-reporter';
 

package/lib/generate-report.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const EC = require('eight-colors');
 const CG = require('console-grid');
-const { compress } = require('lz-utils');
+const { deflateSync } = require('lz-utils');
 const { nodemailer } = require('./runtime/monocart-vendor.js');
 const Util = require('./utils/util.js');
 const emailHelper = require('./helper/email.js');
@@ -28,7 +28,7 @@ const generateHtml = (outputDir, filename, reportData) => {
         EC.logRed(errMsg);
     }
 
-    const reportDataStr = compress(JSON.stringify(reportData));
+    const reportDataStr = deflateSync(JSON.stringify(reportData));
     const content = `<script>\nwindow.reportData = '${reportDataStr}';\n${reportJs}\n</script>`;
 
     // replace template

package/lib/helper/audit.js

@@ -103,6 +103,7 @@ const attachAuditReport = async (runnerResult, testInfo, options = {}) => {
         path: path.resolve(htmlDir, 'index.html')
     });
 
+    return report;
 };
 
 

package/lib/helper/network.js

@@ -155,6 +155,7 @@ const attachNetworkReport = async (har, testInfo, options = {}) => {
         path: path.resolve(htmlDir, 'index.html')
     });
 
+    return report;
 };
 
 

package/lib/merge-data.js

@@ -155,7 +155,7 @@ const mergeDataList = async (dataList, options) => {
         rows
     });
 
-    // tag style can be override with new options tags
+    // tag style can be rewrite with new options tags
     options.tags = options.tags || mergedData.tags;
     calculateSummary(mergedData, options);