Code coverage for your AWK programs

December 2022

Update: The author of this feature, Volodymyr Gubarkov, has written his own article about GoAWK’s code coverage reporting, how he came up with the idea, and how it works.

Despite being the author of GoAWK, I don’t personally use AWK for multi-line scripts. I tend to use Python for scripting, and AWK for one-liners in the terminal.

However, some people do write longer programs using AWK, from the useful to the magnificent:

Gron.awk and Makesure are written by Volodymyr Gubarkov, a Ukranian developer who also created intellij-awk, “The missing IntelliJ IDEA language support plugin for AWK”.

A few months ago Volodymyr opened an issue in the GoAWK repo saying that he was adding a code coverage feature to GoAWK, “similar to the one built into Golang itself”. It’s not every day that I get interesting submissions like that, plus, Volodymyr had already submitted several quality bug reports to the project, so I trusted his ability.

I also thought that it would be cool to be able to say that GoAWK is the only AWK implementation we know with code coverage support.

Thanks to Volodymyr’s efforts, GoAWK version 1.21.0 includes the code coverage feature. There was some refactoring that needed to happen before the main code change – thanks again, Volodymyr, for having the patience to see this through.

If you’re writing and testing larger AWK programs, you may find this useful! For some details on how to use the feature and how it works, I’ll quote from the coverage docs:

Here is a screenshot using GoAWK’s coverage feature on a simple AWK program (prog.awk):

Example code coverage screenshot

Basic usage

The simplest way to generate a coverage report is to run your AWK program with the -coverprofile option. To run the program in the default coverage mode and write the coverage report to cover.out, run the following:

$ goawk -f prog.awk -coverprofile cover.out
will always run
should run

This generates a file cover.out with coverage profile data for the execution of prog.awk.

We rely on the Go toolchain to visualize the coverage report, specifically the go tool cover command. This command renders a coverage report to HTML. If you don’t have Go installed, install it now.

To write the HTML coverage report (like the one shown in the screenshot above) to a temporary file and open a web browser displaying it, run the following:

$ go tool cover -html=cover.out

To write the HTML file to a specified file instead of launching a web browser, use -o:

$ go tool cover -html=cover.out -o cover.html

If you want to see coverage-annotated source code, use the -d option in addition to -covermode. This might be useful for debugging, or to see how GoAWK’s coverage feature works under the hood:

$ goawk -f prog.awk -covermode set -d
BEGIN {
    __COVER["3"] = 1
    print "will always run"
    if ((1 + 1) == 2) {
        __COVER["1"] = 1
        print "should run"
    } else {
        __COVER["2"] = 1
        print "won't run"
    }
}

All command-line options

Enjoy! Please report any bugs using GitHub issues.

I’d love it if you sponsored me on GitHub – it will motivate me to work on my open source projects and write more good content. Thanks!