Feature #15022
closed
Oneshot coverage
Description
I'd like to introduce a new feature to the coverage library, namely, "oneshot coverage".
Synopsis¶
The following is a sample target program "test-cov.rb":
1: def foo
2: :foo
3: end
4:
5: def bar
6: :bar
7: end
The following program measures line coverage with oneshot mode:
require "coverage"
# Start the measurement of line coverage with oneshot mode
Coverage.start(oneshot_lines: true)
# Load the target file
load "test-cov.rb"
# Get all executed lines so far:
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[1, 5]}}
# This means that Lines 1 (def foo) and 5 (def bar) were executed
# Clear the counters
Coverage.clear
# Run one of the target functions:
foo()
# Get newly executed lines:
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[2]}}
# This means Line 2 (the body of foo) was newly executed
# Clear the counters
Coverage.clear
# Run the other target function:
bar()
# Get newly executed lines:
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[6]}}
# This means Line 6 (the body of foo) was newly executed
# Clear the counters
Coverage.clear
# Again, run the target functions:
foo()
bar()
# Get newly executed lines:
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[]}}
# This means that no new lines were executed
What this is¶
Traditional coverage tells us "how many times each line was executed". However, it is often enough just to know "whether each line was executed at least once, or not". In this case, the counting just bring unneeded overhead.
Oneshot coverage records only the first execution of each line, and returns line numbers of newly executed lines. It contains less information than traditional coverage, but still useful in many use cases. The hook for each line is executed just once, so after it was fired, the program can run with zero-overhead.
Why this is needed¶
I expect two use cases:
coverage measurement in production¶
In Ruby, it is difficult to determine if some code is a dead code or not. To check this, some people insert a logging code to the possibly-dead code, run it in production for a while, and check if the log is not emitted.
Oneshot coverage can be used to make this process automatic, comprehensive, and non-invasive.
CPU-intensive programs¶
It is known that traditional coverage measurement brings about 20x overhead at worst. It does not matter when testing IO-intensive programs (like Rails application), however, it sometimes matters for CPU-intensive programs.
Oneshot coverage brings the same (or a bit worse) overhead when each line is first executed, but brings no overhead for second and later executions.
Proposal¶
Oneshot coverage consists of three parts of APIs.
API 1: Coverage.start(oneshot_lines: true)
This enables the measurement of line coverage with oneshot mode.
In this mode, Coverage.peek_result and result returns the following format:
{ "/path/to/file.rb" => { :oneshot_lines => [an array of executed line numbers] } }
API 2: Coverage.clear
This clears all the internal counters of coverage, but keeps the measuring target.
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[1,5]}}
foo()
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[1,5,2]}}
Coverage.clear
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[]}}
bar()
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:oneshot_lines=>[6]}}
You can also use this not only for oneshot coverage, but also for traditional one:
Coverage.start(lines: true)
load "test-cov.rb"
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:lines=>[1,0,nil,nil,1,0,nil,nil]}}
Coverage.clear
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:lines=>[0,0,nil,nil,0,0,nil,nil]}}
foo()
p Coverage.peek_result #=> {"/.../test-cov.rb"=>{:lines=>[0,1,nil,nil,0,0,nil,nil]}}
I'm not fully comfortable with this API because it returns incomplete and strange result. However, there have been some requests about restarting coverage (#4796, #9572, #12480), and I think this solves a part of the problem. Actually, it is useful to take coverage per test:
Coverage.start(lines: true)
load "target.rb"
each_test do |test|
Coverage.clear
test.run
Coverage.peek_result #=> coverage of each test
end
The same result can be get by subtraction between two peek_results, but it is faster and easier.
API 3: Coverage.line_stub(filename)
This is just a simple helper function that returns the "stub" of line coverage from a given source code:
Coverage.line_stub("test-cov.rb") #=> [0, 0, nil, nil, 0, 0, nil]
This is needed because oneshot coverage tells "which line was executed" but does not tell nothing about other lines.
We need to distinguish that other lines are just "not executed yet" or "not a measuing target (because it is non-significant lines like empty line)".
I don't like the name "line_stub". Counterproposal is welcome.
Benchmark¶
As a micro benchmark, I timed the period which it took to run a 10M-line function with three modes: no coverage measurement, oneshot_lines, and lines.
| mode | 1st call | 2nd call |
|---|---|---|
| no coverage | 0.035 sec | 0.035 sec |
| oneshot_lines | 0.618 sec | 0.034 sec |
| lines | 0.405 sec | 0.425 sec |
The first call under oneshot_lines is slow, but the second call is as fast as no coverage measurement. On the other hand, lines mode is always slow.
As a relatively bigger CPU-intensive benchmark, I run optcarrot with the three modes.
| mode | time |
|---|---|
| no coverage | 5.5 sec |
| oneshot_lines | 5.5 sec |
| lines | 22 sec |
Oneshot lines mode is as fast as no coverage.
Limitation¶
Currently, oneshot coverage supports only line coverage. It is theoretically possible to implement it for branch coverage. But, it was difficult for me to design the API, and I think line coverage is enough in many cases.
Due to implementation limitation, traditional line coverage and oneshot one cannot be enabled simultaneously: Coverage.start(lines: true, oneshot_lines: true) raises an exception.
Files
Updated by 
Updated by 
Updated by 
Updated by