README.md

         

Simple Web UI for Go Test Coverage

Drop-in replacement for go tool cover -html.

The coverage Go module renders an HTML file for each *.go source file listed in the specified Go test coverage profile file (typically created per an invocation of go test -coverprofile <filename>).

The program expects the specification of three flags with corresponding arguments (see usage below):

-gomod         # path to the root go.mod file
-coverprofile  # path to the Go test coverage profile file
-path          # path where HTML files will be written

The generated HTML files are marked up to identify which lines are covered by tests ($\color{seagreen}{\text{green}}$), and which lines are not ($\color{red}{\text{red}}$). Each HTML file is written to the specified path (per the -path flag) following the same directory structure as the source from which the coverage profile file (per the -coverprofile flag) was created.

The program then creates a tree.html file which provides a navigable view of the source rendered as a directory tree within an iframe on the left, where each node is either a subdirectory (📁 <subdirectory>) or a source file (<source file>.go). Clicking on a subdirectory node expands its contents, and clicking on a source file node renders the marked up source in the iframe to the right of the directory tree.

Both iframes are hosted by a parent index.html file, and both HTML files can be inspected in a browser, either directly via the file:// scheme, or via an HTTP server using the http:// scheme.

When served via HTTP, buttons are available to:

• toggle between light and dark themes
• toggle between a fully-collapsed and fully-expanded directory tree

See also and

---

User Interface

demo.webm

light theme:

dark theme:

---

CLI Usage

$ go get github.com/jbunds/coverage

$ go run github.com/jbunds/coverage
coverage usage:

  -coverprofile string
    	path to Go test coverage profile file
  -gomod string
    	path to the root go.mod file
  -path string
    	path where HTML files will be written

---

GitHub Workflow Configuration

Aside from the CLI interface outlined above, there are two ways to incorporate the coverage module within GitHub workflows:

1. The jbunds/coverage@v1 reusable GitHub Action generates the test coverage report and writes the files comprising the report to coverage-report-path. For example:

- uses: jbunds/coverage@v1
  with:
    go-version:           '1.26.1'           # optional; default is '1.26.1'
    go-mod:               'go.mod'           # optional; default is 'go.mod'
    coverage-threshold:   '50'               # optional; default is '0'
    coverage-report-path: 'coverage_report'  # optional; default is 'coverage_report'

The go-version, go-mod, coverage-threshold, and coverage-report-path parameters are optional.

All outputs produced by the gwatts/go-coverage-action workflow step are available downstream via JSON decoding, e.g.:

${{ fromJson(steps.coverage_report.outputs.all).gcov-pathname    }}
${{ fromJson(steps.coverage_report.outputs.all).report-pathname  }}
${{ fromJson(steps.coverage_report.outputs.all).coverage-pct     }}
${{ fromJson(steps.coverage_report.outputs.all).coverage-pct-1dp }}
${{ fromJson(steps.coverage_report.outputs.all).meets-threshold  }}

etc...

2. The jbunds/coverage/.github/workflows/pages.yml@v1 reusable GitHub Workflow generates the test coverage report and also deploys it to GitHub Pages. For example:

- uses: jbunds/coverage/.github/workflows/pages.yml@v1
  with:
    go-version:           '1.26.1'           # optional: default is '1.26.1'
    go-mod:               'go.mod'           # optional; default is 'go.mod'
    coverage-threshold:   '50'               # optional; default is '0'
    coverage-report-path: 'coverage_report'  # optional; default is 'coverage_report'

See https://jbunds.github.io/coverage/ for an example, which is not particularly interesting since it consists of just the four Go source files which implement the module.

The well-known and relatively large (500k+ LoC) Kubernetes project was chosen for the demo to better illustrate the features and performance.

---

But Why?

The motivation for the coverage module was to create a relatively minimal alternative to the default HTML interface produced by go tool cover -html <coverage profile filename> -o <html filename>, with a simple and intuitive UI, and with minimal JavaScript (55 lines total as of this writing, to implement the functionality of the toggle buttons).

The CSS code was inspired by and adapted from github.com/psnet/simple-tree, and it clearly still needs to be polished. But I am definitely not a CSS expert, and it fulfills the required behavior as-is.