This article will cover how to get visibility of your test coverage in Go. If you’re not comfortable with the basics of testing in Go, please checkout my earlier article aimed at beginners.

Test coverage

Test coverage gives you a high-level overview you how much of your production code was invoked in your tests (e.g. as a percentage), but it can also give you a lower-level view of exactly which lines are invoked or missed. Before we dive deeper into the ‘how’, let’s make sure we understand why we care about test coverage. Test coverage is a terrible metric for evaluating the quality of your tests. Repeat after me:

High test coverage does not imply high-quality tests.

So what’s the purpose of test coverage then?

In my opinion, test coverage serves two purposes:

Firstly, it lets you quickly identify which lines have not been hit by tests. This could indicate that your tests aren’t comprehensive enough: “Oops, this if statement wasn’t tested, but it should have been. Let’s add another test”. However, it could also identify impossible paths in your code: “We’ve already validated this value elsewhere so this can never happen”.

Moreover, paired with a good Continuous Integration setup, you can identify if a change will remove tests prematurely, by warning you when the coverage of your pull request is lower than the base branch.

How to report test coverage in Go

The go tool supplies us with all the tools we need; no third-party solution required:

# Write a "coverprofile" to a filed called coverage.out
go test -coverprofile=coverage.out

# Invoke the 'cover' go tool, and ask it to render the coverprofile file as HTML.
# This should open your default web browser.
go tool cover -html=coverage.out

This shows you exactly how much of each production file was covered, and renders your source code in green if the particular line was covered by the tests, and red otherwise. Type definitions, comments, and other “non-runnable” code are greyed out, as it doesn’t make sense to count these lines as part of our coverage.

Screenshot of coverage rendered as HTML

You can also see a report of your coverage report on a per-function basis:

# Running coverage against and requesting
# per-function output
$ go test -coverprofile=coverage.out && go tool cover -func=coverage.out
ok    0.159s    coverage: 87.5% of statements  validURL                  100.0%  populateDefaults          100.0%  validate                  100.0% makeRuntimeConstants      54.5%        Serialize                 60.0%        Deserialize               55.6%        val                       100.0%       WithBreadcrumb            100.0%       makeBreadcrumbs           100.0%       WithUser                  100.0%       WithBugsnagContext        100.0%       WithMetadatum             100.0%       WithMetadata              100.0%       Metadata                  100.0%       initializeMetadataTab     100.0%       updateFromCtx             38.9%       getAttachedContextData    100.0%          Error                     100.0%          Unwrap                    66.7%          Wrap                      100.0%          Wrap                      100.0%          makeStacktrace            100.0%         makeModulePath            66.7%       New                       85.7%       Close                     100.0%       Notify                    75.0%      loop                      100.0%      shutdown                  70.0%      makeReport                100.0%      sendErrorReport           85.7%      makeUnhandled             100.0%      makeSeverity              83.3%      severityReasonType        100.0%      makeExceptions            82.4%      makeJSONApp               100.0%      makeJSONDevice            75.0%      memStats                  84.6%      osVersion                 66.7%      makeNotifier              100.0%      extractLowestBugsnagError 100.0%      guard                     100.0%        StartSession              100.0%        flushSessions             100.0%        publishSessions           82.4%       makeJSONSession           100.0%       makeJSONSessionReport     100.0%       uuidv4                    100.0%
total:                                           (statements)              87.5%

A note on covermode and concurrent programs

go test has a parameter called covermode which tweaks how the Go tool should think about “covering a line”. Basically your options are “lines are either missed or hit” or “let’s count how many times a line is hit”. The former is used by default, and is the least expensive. You can get more of a ‘heatmap’ feature (in the rendered HTML) by setting the -covermode=count, however I recommend taking things a step further to avoid headaches. Namely, use -covermode=atomic to ensure that the lines hit are counted accurately even in concurrent programs.

$ go test -coverprofile=coverage.out -covermode=atomic

This is significantly more expensive, but for most project the additional compute resource is surely negligible.