1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
# GoAWK's code coverage feature
GoAWK implements code coverage functionality, similar to the [code coverage built into Go](https://go.dev/blog/cover). This feature was implemented by Volodymyr Gubarkov ([xonixx](https://github.com/xonixx)), primarily in [PR #154](https://github.com/benhoyt/goawk/pull/154).
Here is a screenshot using GoAWK's coverage feature on a simple AWK program (`prog.awk`):
## 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](https://go.dev/doc/install).
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
- `-coverprofile fn`: set the coverage report filename to `fn`. If this option is specified but `-covermode` is not, the coverage mode defaults to `set`.
- `-covermode mode`: set the coverage mode to `mode`, which can be one of:
- `set`: did each statement run?
- `count`: how many times did each statement run? (produces a heat map report)
- `-coverappend`: append to coverage profile instead of overwriting it. This allows you to accumulate coverage data across several different runs of the program.
## Future work
- Add a way to support per-function coverage reporting, similar to `go tool cover -func=cover.out`.
- More complete handling for coverage of `if`/`else` (see [details](https://github.com/benhoyt/goawk/pull/154#discussion_r996465307)).
## Feedback
Please [open an issue](https://github.com/benhoyt/goawk/issues) if you have bug reports or feature requests for GoAWK's code coverage support.
|
