coverage

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).

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

-gomod         # path to a go.work file or a comma-delimited list of go.mod paths (default "go.mod")
-coverprofile  # path to the coverage profile file
-outdir        # path where HTML files will be written

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

The program then renders an index.html file to the specified path which provides a navigable view of the source rendered as a directory tree 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 a child iframe positioned to the right of the directory tree.

The rendered HTML files can be viewed in a browser, either directly via the file:// scheme, or via an HTTP server using the http:// scheme.

When served via HTTP and JavaScript is enabled, buttons are available to:

•  toggle between a fully-collapsed and fully-expanded source tree
•  toggle between showing or hiding a column of line numbers along the left side of the source code
•  toggle between showing or hiding the bodies of all top-level functions and methods in the source code
•  toggle between light and dark themes

See also and

---

User Interface

demo.webm

light theme:

dark theme:

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

---

CLI Usage

$ go get github.com/jbunds/coverage

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

  -coverprofile string
    	path to the coverage profile file
  -gomod string
    	path to a go.work file or a comma-delimited list of go.mod paths (default "go.mod")
  -n	suppress opening the browser (overrides -s)
  -order value
    	per-file coverage stdout rows sort order
  -outdir string
    	path where HTML files will be written
  -s	serve the generated HTML via a Python HTTP server

---

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-outdir. For example:

   - uses: jbunds/coverage@v1
     with:
       go-mod:                 'go.mod'           # optional; default is 'go.mod'
       test-pkgs:              './...'            # optional; default is './...'
       cover-pkg:              './...'            # optional; default is './...'
       coverage-threshold:     '50'               # optional; default is '0'
       coverage-report-outdir: 'coverage_report'  # optional; default is 'coverage_report'
   

   The go-mod, test-pkgs, cover-pkg, coverage-threshold, and coverage-report-outdir parameters are all 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.

   See jbunds/progress/.github/workflows/test-go.yml for a working example.

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

   - uses: jbunds/coverage/.github/workflows/pages.yml@v1
     permissions:
       contents: write  # required by gwatts/go-coverage-action to execute `git push origin refs/notes/gocoverage`
       pages:    write  # required by actions/deploy-pages
       id-token: write  # required by actions/deploy-pages
     with:
       go-mod:                 'go.mod'           # optional; default is 'go.mod'
       test-pkgs:              './...'            # optional; default is './...'
       cover-pkg:              './...'            # optional; default is './...'
       coverage-threshold:     '50'               # optional; default is '0'
       coverage-report-outdir: 'coverage_report'  # optional; default is 'coverage_report'
   

   See jbunds/progress/.github/workflows/pages.yml for a working example.

   See jbunds.github.io/coverage/ (multi-module) or jbunds.github.io/progress/ (single-module) for example HTML reports uploaded to Pages.

---

But Why?

The motivation behind the coverage module was to provide a richer UI than that produced by go tool cover -html, with minimal JavaScript (71 lines in total as of this writing, most of which is either trivial button event-listener boilerplate used to toggle CSS selectors, or theme and line numbers user preference persistence).

r's opinion

Prior Art

The CSS code (347 lines in total as of this writing) was inspired by and adapted from github.com/psnet/simple-tree, and it could probably benefit from further refinement. But I am not a CSS expert, and it fulfills the required behavior as-is.

go-better-html-coverage is similar but provides a much richer UI afforded by its extensive use of JavaScript. I couldn't get it to work with the Kubernetes codebase.