transform go test JSON output into markdown

Installation

To install:

$ go install github.com/blugnu/test-report/

This will download and build test-report placing a copy of the binary in your $GOPATH/bin folder.

NOTE: It is recommended to add $GOPATH/bin to your path

Building From Source

test-report is entirely self-contained and can be built using the standard go build command if desired:

$ cd <source>
$ go build .

Where <source> is the folder containing the test-report source code,

Usage

To use test-report with the default settings simply pipe the output from go test -json to test-report:

$ go test -json | test-report

Without additional options, test-report will output a test-report.md file in the location from which it is executed:

test-report.md

Output Format

The markdown output produced by test-report is GFM compliant, including minimal <table> elements to ensure compatibility with github action job summaries whilst presenting information in a clear and appealing format.

Options

Additional options are available via command-line parameters:

Usage:
  test-report [command]
  test-report [options]

Available Commands:
  version     displays the version number of the test-report executable

Options:
  -f, --full                produce a full report containing both passed and failed tests
                            (by default only details of failed tests are shown)

  -o, --output <filename>   the output filename (default "test-report.md")

  -s, --summary             produce a summary report only (no details of failed tests)

  -t, --title <string>      the title text shown in the test report (default "Test Report")

  -h, --help                help for test-report

  -v, --verbose             while processing, show the (JSON) output from go test

The name of the output file can be changed by using the -o or --output option. For example, the following command will change the output to test-results.md:

$ go test -json | test-report -o test-results.md

To change the title shown in the output file:

$ go test -json | test-report -t "Test Results"

Understanding the Report

The report produced by test-report is a markdown file that contains a summary of the test results. By default, in addition to the summary, the report includes details of any failed tests; this can be changed to include all tests using the -f or --full flag.

The report can be limited to the just summary, without any failed test details, by using the -s or -summary option.

Report Title

The report title includes an icon indicating the overall result of the test report. The icon is presented in a different color according to the pass rate of the tests in the report:

icon	indicates
📕	pass rate is < 85%
📙	pass rate is >= 85% and < 95%
📒	pass rate is >= 95% and < 100%
📗	pass rate is 100%

these icons and the associated pass rate %ages are currently fixed

Report Summary Section

Following the report title, at the top of the report a summary section identifies:

• the number of packages
• the elapsed time for the complete test run
• the total number of tests
• the number of tests that failed (if any)
• the number of tests that skipped (if any)
• the percentage of tests that passed

An example of a summary section might look similar to this:

Report Details Section

Following the summary, a details section identifies any failing tests.

By default this section is omitted if there were no failed tests. To present complete details including skipped and passed tests, use the -f or --full option.

Each package containing at least one failed test is listed. For each failed test the following information is presented:

• name of the test
• source reference (file name and line number) for the failed test
• the output of the test

When reporting only failed tests (the default) additional entries are included in the details report repeating the number of tests that were skipped or passed (if any).

The report details section might appear similar to:

---

Background

This tool was created to satisfy a desire to incorporate a test report into Github action job summaries, for which the HTML produced by existing tools was not suitable.

Markdown seemed to offer a better fit for that use case, and so this tool was born.

Roadmap

If test-report proves useful, additional features may be added in the future which may include support for additional output formats.

Current top-of-mind future features include:

• link the filename and line number reference in test output to the corresponding file in the repository

If any of these would be of particular interested, consider giving the relevant issue a 👍

Contribute & Support

• Add a GitHub Star 😄
• Please consider creating an issue for any improvements you would like to see or any bugs you may find
• If you would like to contribute, please submit a pull request