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 foo2:   :foo3: end4:5: def bar6:   :bar7: end

The following program measures line coverage with oneshot mode:

require"coverage"# Start the measurement of line coverage with oneshot modeCoverage.start(oneshot_lines:true)# Load the target fileload"test-cov.rb"# Get all executed lines so far:pCoverage.peek_result#=> {"/.../test-cov.rb"=>{:oneshot_lines=>[1, 5]}}# This means that Lines 1 (def foo) and 5 (def bar) were executed# Clear the countersCoverage.clear# Run one of the target functions:foo()# Get newly executed lines:pCoverage.peek_result#=> {"/.../test-cov.rb"=>{:oneshot_lines=>[2]}}# This means Line 2 (the body of foo) was newly executed# Clear the countersCoverage.clear# Run the other target function:bar()# Get newly executed lines:pCoverage.peek_result#=> {"/.../test-cov.rb"=>{:oneshot_lines=>[6]}}# This means Line 6 (the body of foo) was newly executed# Clear the countersCoverage.clear# Again, run the target functions:foo()bar()# Get newly executed lines:pCoverage.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 andresult 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.clearp 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.clearp 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 testend

The same result can be get by subtraction between twopeek_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.

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 runoptcarrot with the three modes.

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.