DOCSEARCHbyAlgolia
Submit Docs

go-test-report

repository·master·Indexed 41 days ago

https://github.com/vakenbolt/go-test-report

A tool that transforms `go test -json` output into a single, self-contained, interactive HTML report. It provides visualization of test results through color-coded groups, filtering, and detailed output expansion. Features include customizable output filenames, report titles, and the ability to include source code locations via a JSON module list using the `--list` flag.

Tokens
2.1K
Snippets
8
Records
11
Agent score
52%

What's inside go-test-report

  1. How to navigate the HTML test report

    master

    The generated HTML report provides an interactive way to view results:

    • Test Groups: Tests are organized into color-coded squares.
      • <span style="color: green">Green</span>: All tests in the group passed.
      • <span style="color: red">Red</span>: At least one test in the group failed.
    • Filtering: Click a test group indicator to view only those tests. A selected group is marked in black.
    • Expanding Tests: Click a test title to view its output. To expand all tests in a group simultaneously, hold shift while clicking the test group indicator.

  2. Generate a test report using default settings

    master

    To generate a self-contained HTML test report, pipe the output of go test -json into go-test-report. By default, this creates a file named test_report.html in the current directory.

    $ go test -json | go-test-report

  3. Build go-test-report from source

    master

    The project uses make (or gmake on macOS after installing via Homebrew) for build automation.

    • gmake genbuild: Builds the project.
    • gmake gencode: Generates the embedded HTML and Javascript code required for the report.
    • gmake genbuild (alternative): Automatically runs gencode before building.
    • gmake dockertest: Builds the testing container.
    • gmake buildall: Builds release binaries for darwin/amd64, linux/amd64, and windows/amd64, placing them in the release_builds folder.
    # Build the project
$ gmake genbuild

# Build all release binaries
$ gmake buildall

  4. Install go-test-report

    master

    Install the go-test-report binary using go get.

    Note: To run the binary, ensure the bin folder from your Go workspace is in your shell's PATH. The default workspace is typically ~/go on Linux/macOS or %USERPROFILE%/go on Windows.

    $ go get -u github.com/vakenbolt/go-test-report/

  5. Understand the GoTestReport interaction model

    master

    The GoTestReport library provides an interactive way to explore test results through two main layers of interaction:

    1. Test Group Selection: Clicking an element within testResultsElem triggers testResultsClickHandler. This selects a group of tests, updates the visual 'selected' state, and populates the testGroupListElem with a list of individual test rows (e.g., showing which specific tests passed, failed, or were skipped within that group).

    2. Test Detail Expansion: Clicking an individual test row within testGroupListElem triggers testGroupListHandler. This toggles the visibility of the test's detailed output, including the package name, filename, line/column information, and the captured console output.

    Special Behavior:

    • Shift + Click: If you hold the Shift key while clicking a test group, the library will automatically expand the details for all test rows within that group simultaneously.
    • Single Test Groups: If a group contains only one test, clicking the group will automatically expand that single test's details without requiring a second click.

  6. Provide source code locations via a JSON module list

    master

    By default, go-test-report shows test results. If you provide a JSON module list using the --list flag, the report will include the specific file name and line/column position for each test function. This allows you to jump directly to the source code from the report.

    The --list flag expects a file containing JSON objects matching the go list -json format (specifically containing ImportPath, Dir, and TestGoFiles).

    go test -json ./... | go-test-report --list modules.json

  7. Initialize GoTestReport with DOM elements

    master

    The window.GoTestReport constructor is the main entry point for the reporting logic. It initializes event listeners on provided DOM elements to enable interactive test reporting.

    To use it, you must provide a GoTestReportElements object containing the necessary DOM nodes and the test data.

    Required Data Structures:

    • GoTestReportElements:

      • data: A TestResults array containing the test hierarchy.
      • testResultsElem: The HTMLElement that acts as the container for test result groups (receives click events).
      • testGroupListElem: The HTMLElement where individual test rows are rendered.

    • TestResults (Data Schema): An array of TestGroupData objects. Each group contains:

      • FailureIndicator: string
      • SkippedIndicator: string
      • TestResults: An array of TestStatus objects.

    • TestStatus (Individual Test Schema):

      • TestName: string
      • Package: string
      • ElapsedTime: number
      • Output: Array of strings
      • Passed: boolean
      • Skipped: boolean
      • TestFileName: string
      • TestFunctionDetail: object containing Line and Col
    // Example initialization
const elements = {
  data: testDataJson, // The parsed JSON test results
  testResultsElem: document.getElementById('test-results-container'),
  testGroupListElem: document.getElementById('test-group-list')
};

const reportController = window.GoTestReport(elements);

  8. Use go-test-report to generate HTML reports

    master

    The go-test-report CLI tool captures go test output via stdin (using the -json flag) and parses it into a single, self-contained HTML file. This allows you to visualize test results, including pass/fail status, execution time, and source code locations.

    To use it, pipe the output of go test -json into the go-test-report binary.

    go test -json ./... | go-test-report

  9. Configure go-test-report via command-line flags

    master

    You can customize the generated report using several command-line flags:

    • -o, --output <string>: Specify the HTML output filename (default: test_report.html).
    • -t, --title <string>: Set the title text shown in the report (default: go-test-report).
    • -g, --groupSize <int>: Set the number of tests per test group indicator (default: 20).
    • -s, --size <string>: Set the size of the clickable indicator for test result groups (default: 24). Supports dimensions like 48 or 32x16 pixels.
    • -v, --verbose: Show the complete output from go test while processing.
    # Example: Custom output name and title
$ go test -json | go-test-report -o my-test-report.html -t "My Test Report"

# Example: Custom group size
$ go test -json | go-test-report -g 8

# Example: Custom indicator size (width x height)
$ go test -json | go-test-report -s 32x16

  10. Configure report title, size, and output file

    master

    You can customize the appearance and destination of the report using CLI flags. For example, to set a custom title, change the indicator size to 30x30 pixels, and save the report to results.html:

    go test -json ./... | go-test-report --title "My Project Tests" --size 30x30 --output results.html

  11. Reference: go-test-report CLI flags

    master

    The following flags are available to customize the generated HTML report:

    FlagShorthandDefaultDescription
    --title-tgo-test-reportThe title text shown in the test report
    --size-s24The size (in pixels) of the clickable indicator for test result groups. Supports square values (e.g., 24) or WxH format (e.g., 20x30)
    --groupSize-g20The number of tests per test group indicator
    --list-l(empty)Path to a JSON module list file to provide source code location details
    --output-otest_report.htmlThe HTML output file name
    --verbose-vfalseWhile processing, show the complete output from go test