merge(#34): feat!: add templating to the script

feat!: add templating to the script
403-html · Nov 18, 2023 · a7a8b95 · a7a8b95
2 parents c441b10 + ea937d6
commit a7a8b95
Show file tree

Hide file tree

Showing 5 changed files with 354 additions and 487 deletions.
diff --git a/README.md b/README.md
@@ -1,40 +1,141 @@
 # mochawesome-json-to-md
 
-## Why is this project useful?
+[![GitHub license](https://img.shields.io/github/license/403-html/mochawesome-json-to-md)](https://github.com/403-html/mochawesome-json-to-md/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/403-html/mochawesome-json-to-md)](https://github.com/403-html/mochawesome-json-to-md/issues)
+[![GitHub stars](https://img.shields.io/github/stars/403-html/mochawesome-json-to-md)](https://github.com/403-html/mochawesome-json-to-md/stargazers)
+
+## Overview
+
+<div align="center">
+
+This tool converts JSON reports generated by [mochawesome](https://www.npmjs.com/package/mochawesome) (including reports merged by [mochawesome-merge](https://www.npmjs.com/package/mochawesome-merge)) into editable markdown format. It provides flexibility by allowing users to create and customize their own markdown templates.
+
+</div>
+
+## Table of Contents
+
+- [mochawesome-json-to-md](#mochawesome-json-to-md)
+  - [Overview](#overview)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [How do I get started?](#how-do-i-get-started)
+  - [Script arguments](#script-arguments)
+  - [Templating, tags and customization](#templating-tags-and-customization)
+    - [How to create a template?](#how-to-create-a-template)
+    - [Singular tags](#singular-tags)
+    - [Block tags](#block-tags)
+      - [Boolean tags](#boolean-tags)
+      - [Loop tags](#loop-tags)
+      - [Test tags](#test-tags)
+  - [Where can I get more help, if I need it?](#where-can-i-get-more-help-if-i-need-it)
+  - [How I can contribute to the project?](#how-i-can-contribute-to-the-project)
+  - [Plans and achievements for this project](#plans-and-achievements-for-this-project)
+  - [License](#license)
+  - [Author](#author)
+
+## Features
+
+- Convert mochawesome JSON reports to markdown format.
+- Customize the output using templates.
 
-It let's you to convert your JSON reports generated by [mochawesome](https://www.npmjs.com/package/mochawesome) (and even merged by [mochawesome-merge](https://www.npmjs.com/package/mochawesome-merge)) to simple editable markdown.
 
 ## How do I get started?
 
 Install package
 
-```
+```sh
 npm install -g mochawesome-json-to-md
 ```
 
 run the script
 
-```
-mochawesome-json-to-md -p ./your/file/path.json -o ./generated.md [args]
+```sh
+mochawesome-json-to-md -p ./your/file/path.json -o ./generated.md
 ```
 
 that's it! You've successfuly converted json report to _slick_ md report.
 
-## Options
-
-| Command        | Type    | Default                  | Description                                                                                              | Example                                                                                                 |
-| -------------- | ------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| -p, --path     | string  | **required**             | define path to the json report                                                                           | `mochawesome-json-to-md --path ./reports/file.json`                                                     |
-| -o, --output   | string  | `./md-reports/output.md` | define path for the output md file                                                                       | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md`                           |
-| --showEmoji    | boolean | `true`                   | defines whether there should be emoji in the final markdown file                                         | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --emoji=false`             |
-| --reportTitle  | string  | `Test report`            | define report title in the final md file                                                                 | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --reportTitle="New title"` |
-| --showDate     | boolean | `true`                   | defines whether there should be visible test date in the final markdown file                             | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showDate=true`           |
-| --showDuration | boolean | `true`                   | defines whether there should be visible duration of the test in the final markdown file                  | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showDuration=true`       |
-| --showStats    | boolean | `true`                   | defines whether there should be visible high level stats of the test in the final markdown file          | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showStats=true`          |
-| --showPassed   | boolean | `false`                  | defines whether there should be visible section with passed tests in the final markdown file             | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showPassed=false`        |
-| --showFailed   | boolean | `true`                   | defines whether there should be visible section with failed tests in the final markdown file             | `mochawesme-json-to-md --path ./reports/file.json --output ./output/file.md --showFailed=true`          |
-| --showSkipped  | boolean | `true`                   | defines whether there should be visible section with skipped by user tests in the final markdown file    | `mchawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showSkipped=true`         |
-| --showCypress  | boolean | `true`                   | defines whether there should be visible section with skipped by Cypress tests in the final markdown file | `mochawesome-json-to-md --path ./reports/file.json --output ./output/file.md --showCypress=true`        |
+## Script arguments
+
+| **Option** | **Alias** | **Description** | **Required** | **Default** |
+|------------|-----------|-----------------|--------------|-------------|
+| `--path` | `-p` | Path to the JSON report | Yes | |
+| `--output` | `-o` | Path to the output markdown file | No | ./md-reports/output.md |
+| `--template` | `-t` | Path to the markdown template file | No | ./sample-template.md |
+| `--title` | `-T` | Title for the report | No | Test Report |
+
+## Templating, tags and customization
+
+### How to create a template?
+
+You can create a template by yourself. It's just a markdown file with some tags. You can use [sample-template.md](./sample-template.md) as a reference. But feel free to create your own template. Below you can find all the tags and how to use them.
+
+### Singular tags
+
+Singular tags will be replaced with the value of the tag.
+
+| **Tag** | **Description** |
+|---------|-----------------|
+| `{{title}}` | Title of the report |
+| `{{startDate}}` | Start date of the test run |
+| `{{duration}}` | Duration of the test run in seconds |
+| `{{totalTests}}` | Total number of tests |
+| `{{passedTestsCount}}` | Number of passed tests |
+| `{{failedTestsCount}}` | Number of failed tests |
+| `{{skippedTestsCount}}` | Number of skipped tests |
+| `{{skippedCypressTestsCount}}` | Number of skipped tests by Cypress |
+| `{{otherTestsCount}}` | Number of other tests |
+
+### Block tags
+
+#### Boolean tags
+
+Boolean tags will be replaced with the content between the tags if the condition is met.
+
+| **Open tag** | **Closing tag** | **Description** |
+|--------------|-----------------|-----------------|
+| `{{#passedExists}}` | `{{/passedExists}}` | If there are any passed tests, then everything between these tags will be included in the report |
+| `{{#failedExists}}` | `{{/failedExists}}` | If there are any failed tests, then everything between these tags will be included in the report |
+| `{{#skippedExists}}` | `{{/skippedExists}}`  | If there are any skipped tests, then everything between these tags will be included in the report |
+| `{{#skippedCypressExists}}` | `{{/skippedCypressExists}}` | If there are any skipped tests by Cypress, then everything between these tags will be included in the report |
+
+#### Loop tags
+
+Loop tags will be replaced with the content between the tags for each test with given status.
+
+| **Open tag** | **Closing tag** | **Description** |
+|--------------|-----------------|-----------------|
+| `{{#passedTests}}` | `{{/passedTests}}` | Everything between these tags will be included in the report for each passed test |
+| `{{#failedTests}}` | `{{/failedTests}}` | Everything between these tags will be included in the report for each failed test |
+| `{{#skippedTests}}` | `{{/skippedTests}}` | Everything between these tags will be included in the report for each skipped test |
+| `{{#skippedCypressTests}}` | `{{/skippedCypressTests}}` | Everything between these tags will be included in the report for each skipped test by Cypress |
+
+#### Test tags
+
+Test tags will be replaced with the value of the tag for each test with given status.
+
+| **Tag** | **Description** |
+|---------|-----------------|
+| `{{path}}` | Path to the test |
+| `{{title}}` | Title of the test |
+| `{{fullTitle}}` | Full title of the test |
+| `{{timedOut}}` | If the test timed out |
+| `{{duration}}` | Duration of the test in milliseconds |
+| `{{state}}` | State of the test |
+| `{{speed}}` | Speed of the test |
+| `{{pass}}` | If the test passed |
+| `{{fail}}` | If the test failed |
+| `{{pending}}` | If the test is pending |
+| `{{context}}` | Context of the test |
+| `{{code}}` | Code of the test (**alert**: it's a long string) |
+| `{{err}}` | Object with error information (**alert**: it's an object, call properties instead)|
+| `{{err.message}}` | Error message |
+| `{{err.estack}}` | Error stack |
+| `{{err.diff}}` | Error diff |
+| `{{uuid}}` | UUID of the test |
+| `{{parentUUID}}` | UUID of the parent test |
+| `{{isHook}}` | If the test is a hook |
+| `{{skipped}}` | If the test is skipped |
 
 ## Where can I get more help, if I need it?
 
@@ -54,15 +155,15 @@ But first, please, read the [Contributing](./CONTRIBUTING.md#Contributing) file.
 - [x] <s> Grab all needed information </s>
 - [x] <s> Grab all possible tests by type and store them together by type (recurrence) </s>
 - [x] <s> Save markdown with created "semi-dynamic" markdown template and return there only informations passed as arguments </s>
-- [ ] Create fully customizable markdown template with tags
-- [ ] Remove need of all arguments and depends only on customizable markdown template with tags
-- [ ] Remove need of `lodash` package
-- [ ] Remove/find substitute for `yargs` package
+- [x] <s> Create fully customizable markdown template with tags </s>
+- [x] <s> Remove need of all arguments and depends only on customizable markdown template with tags </s>
+- [x] <s> Remove need of `lodash` package </s>
+- [x] <s> Remove/find substitute for `yargs` package </s>
 - [ ] Add support for TypeScript
 - [ ] Add few samples of markdown templates to choose from
 - [ ] Add unit tests (topic started in [this issue](https://github.com/403-html/mochawesome-json-to-md/issues/5))
-- [ ] Rewrite and add more documentation
-  - [ ] Readme
+- [x] <s> Rewrite and add more documentation </s>
+  - [x] <s> Readme </s>
   - [x] <s> Contributing guidelines </s>
   - [ ] Code of conduct
 - [x] <s> Add workflow for automated semantic versioning </s>