mochawesome-json-to-md

Quickstart

Run with npx (no install needed):

npx mochawesome-json-to-md -p ./your/report/files/path.json -o ./generated.md

If you want a pinned version (CI/teams), add it to devDependencies and use the local binary:

npm install --save-dev mochawesome-json-to-md
npx mochawesome-json-to-md -p ./your/report/files/path.json -o ./generated.md

GitHub Actions example (append report to the job summary):

npx mochawesome-json-to-md -p ./your/report/files/path.json -o ./generated.md
cat ./generated.md >> $GITHUB_STEP_SUMMARY

Overview

This tool converts JSON reports generated by mochawesome (including reports merged by mochawesome-merge) into editable markdown format. It provides flexibility by allowing users to create and customize their own markdown templates.

Table of Contents

• mochawesome-json-to-md
  • Quickstart
  • Overview
  • Table of Contents
  • Features
  • Requirements
  • Usage
  • CLI options
  • Templating, tags and customization
    • How to create a template?
    • Singular tags
    • Block tags
      • Boolean tags
      • Loop tags
      • Test tags
  • CI integration
  • Safety, linting, and conduct
  • Support
  • Contributing
  • Roadmap
  • License
  • Author

Features

• Convert mochawesome JSON reports to markdown format.
• Customize the output using templates.

Requirements

• Node.js and npm available in your environment.

Usage

Generate a markdown report from a mochawesome JSON file:

npx mochawesome-json-to-md -p ./your/report/files/path.json -o ./generated.md

CLI options

| 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 | | --verbose | -v | Verbose mode | No | false |

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 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 milliseconds | | {{durationSeconds}} | 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 | | {{skippedOtherTestsCount}} | Number of skipped tests by other tooling or runners | | {{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 | | {{#skippedOtherExists}} | {{/skippedOtherExists}} | If there are any other skipped tests, 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 | | {{#skippedOtherTests}} | {{/skippedOtherTests}} | Everything between these tags will be included in the report for each other skipped test |

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 |

CI integration

GitHub Actions can append the generated markdown to the job summary:

npx mochawesome-json-to-md -p ./your/report/files/path.json -o ./generated.md
cat ./generated.md >> "$GITHUB_STEP_SUMMARY"

See the real test-and-summary job in pr-workflow.yml.

GitLab CI does not provide a job summary file; a common pattern is to save the markdown as a job artifact or post it to MR.

Safety, linting, and conduct

• Safety rules for code contributions live in the Code of Conduct; follow them when writing or reviewing code.
• ESLint is configured with stricter rules (enforced curly braces, strict equality, explicit defaults, max function length) to surface risky patterns early. Run npm run eslint before opening a PR.
• All contributors are expected to abide by the Code of Conduct.

Support

Open an issue and include a minimal repro (JSON input + template) so it is easy to investigate.

Contributing

Read Contributing before opening a PR. Questions are welcome in Issues.

Roadmap

• [x] Read and process passed arguments
• [x] Create function for "semi-dynamic" markdown template creation
• [x] Read json report
• [x] Grab all needed information
• [x] Grab all possible tests by type and store them together by type (recurrence)
• [x] Save markdown with created "semi-dynamic" markdown template and return there only informations passed as arguments
• [x] Create fully customizable markdown template with tags
• [x] Remove need of all arguments and depends only on customizable markdown template with tags
• [x] Remove need of lodash package
• [x] Remove/find substitute for yargs package
• [ ] Add support for TypeScript
• [ ] Add few samples of markdown templates to choose from
• [x] Add unit tests (topic started in this issue)
• [x] Rewrite and add more documentation
  • [x] Readme
  • [x] Contributing guidelines
  • [x] Code of conduct
• [x] Add workflow for automated semantic versioning

License

MIT

Author

Tymoteusz 403-html Stępień