class Coverage (Ruby 4.1 リファレンスマニュアル)

要約

カバレッジを測定する機能を提供するクラスです。

実験的な機能のため、APIは将来変更になる可能性があります。

特異メソッド

line_stub(file) -> ArrayRuby 2.6.0 から[permalink][rdoc][edit]

行カバレッジの配列のスタブを返します。

測定対象となる行の要素は 0, 空行やコメントなどにより測定対象外となる行の要素は nil となります。

foo.rb

s = 0
10.times do |x|
  s += x
end

if s == 45
  p :ok
else
  p :ng
end

このファイルに対して line_stub を実行すると、次のようになります。

require "coverage"
p Coverage.line_stub("foo.rb")  # => [0, 0, 0, nil, nil, 0, 0, nil, 0, nil]

この例において、空行, else, end の行は測定対象外であるため、nil となっています。

[PARAM] file:: ファイル名を表す文字列

peek_result -> HashRuby 2.3.0 から[permalink][rdoc][edit]

測定を止めることなく、測定中のその時の結果をハッシュで返します。測定結果の詳細は、coverage ライブラリを参照してください。

これは、Coverage.result(stop: false, clear: false) と同じです。

[RETURN]: 測定途中結果を表すハッシュ
[EXCEPTION] RuntimeError:: Coverage.start を実行する前に実行された場合に発生します。

bool.rb

def bool(obj)
  if obj
    true
  else
    false
  end
end

require "coverage"

Coverage.start

load "bool.rb"
p Coverage.peek_result  # => {"bool.rb"=>[1, 0, 0, nil, 0, nil, nil]}

bool(true)
p Coverage.peek_result  # => {"bool.rb"=>[1, 1, 1, nil, 0, nil, nil]}

bool(false)
p Coverage.peek_result  # => {"bool.rb"=>[1, 2, 1, nil, 1, nil, nil]}

[SEE_ALSO] Coverage.result

result(stop: true, clear: true) -> HashRuby 1.9.3 から[permalink][rdoc][edit]

対象ファイル名をキー、測定結果を値したハッシュを返します。測定結果の詳細は、coverage ライブラリを参照してください。

[PARAM] stop:: true であれば、カバレッジの測定を終了します。
[PARAM] clear:: true であれば、測定記録をクリアします。
[RETURN]: 測定結果を表すハッシュ
[EXCEPTION] RuntimeError:: Coverage.start を実行する前に実行された場合に発生します。

bool.rb

def bool(obj)
  if obj
    true
  else
    false
  end
end

require "coverage"
Coverage.start
load "bool.rb"
p Coverage.result  # => {"bool.rb"=>[1, 0, 0, nil, 0, nil, nil]}
bool(0)
p Coverage.result  # coverage measurement is not enabled (RuntimeError)

Ruby 2.6 以降では、オプションを指定できます。 Coverage.result(clear: true, stop: false) と指定することで、続けて新しく実行された行だけを記録できます。

require "coverage"
Coverage.start(oneshot_lines: true)
load "bool.rb"
p Coverage.result(clear: true, stop: false)  # => {"bool.rb"=>{:oneshot_lines=>[1]}}
bool(0)
p Coverage.result(clear: true, stop: false)  # => {"bool.rb"=>{:oneshot_lines=>[2, 3]}}
bool(nil)
p Coverage.result(clear: true, stop: false)  # => {"bool.rb"=>{:oneshot_lines=>[5]}}

上記のコード例で、bool(0) で実行された2行目の条件式は、測定記録がクリアされたあと bool(nil) で実行されても新しく記録されません。測定記録をクリアしても、記録を開始してから実行されたことまでリセットされているわけではないことに注意して下さい。

[SEE_ALSO] Coverage.peek_result

resume -> nilRuby 3.1 から[permalink][rdoc][edit]

カバレッジの測定を開始、または再開します。

事前に Coverage.setup で測定の準備をしておく必要があります。

現在のところプロセス全体のカバレッジしか測定できません。スレッドごとのカバレッジは測定できないため、複数のスレッドを持つプロセスで Coverage.resume と Coverage.suspend を使って特定のコードブロックの実行だけをカバレッジ測定の対象にしようとすると、意図しない結果になることがあります。

[EXCEPTION] RuntimeError:: Coverage.setup を実行する前に実行した場合、または既に測定中の場合に発生します。

require "coverage"
Coverage.setup
Coverage.resume
p Coverage.state  # => :running

[SEE_ALSO] Coverage.setup, Coverage.suspend

running? -> boolRuby 2.5.0 から[permalink][rdoc][edit]

カバレッジ測定中かどうかを返します。カバレッジの測定中とは、Coverage.start の呼び出し後から Coverage.result の呼び出し前です。

require 'coverage'
p Coverage.running?    # => false
Coverage.start
p Coverage.running?    # => true
p Coverage.peek_result # => {}
p Coverage.running?    # => true
p Coverage.result      # => {}
p Coverage.running?    # => false

setup(mode = nil) -> nilRuby 3.1 から[permalink][rdoc][edit]

setup(lines: nil, branches: nil, methods: nil, eval: nil, oneshot_lines: nil) -> nil

カバレッジの測定の準備をします。

このメソッド自体は測定を開始しません。測定を開始するには Coverage.resume を使います。準備と開始を同時に行いたい場合は Coverage.start を使ってください。

[PARAM] mode:: :all を指定すると、lines、branches、methods、eval の全てを計測対象にします。省略した場合は行カバレッジのみが対象になります。
[PARAM] lines:: 真を指定すると行カバレッジを計測対象にします。
[PARAM] branches:: 真を指定すると分岐カバレッジを計測対象にします。
[PARAM] methods:: 真を指定するとメソッドカバレッジを計測対象にします。
[PARAM] eval:: 真を指定すると eval カバレッジを計測対象にします。(Ruby 3.2 で追加されたキーワード引数です)
[PARAM] oneshot_lines:: 真を指定すると、行カバレッジを 1 度でも実行されたかどうかだけを記録するモード(coverage ライブラリ参照)で計測対象にします。lines と同時には指定できません。
[EXCEPTION] RuntimeError:: 既に Coverage.setup 済みの状態で、対象とするモードが異なる引数で呼び出した場合に発生します。

require "coverage"
Coverage.setup(lines: true)
p Coverage.state  # => :suspended
Coverage.resume

[SEE_ALSO] Coverage.resume, Coverage.start

start(option = {}) -> nilRuby 1.9.3 から[permalink][rdoc][edit]

カバレッジの測定を開始します。既に実行されていた場合には何も起こりません。ただし、カバレッジ計測中に測定対象を変更しようとした場合は、RuntimeError となります。

[PARAM] option:: カバレッジの計測モードを指定します。 :all か "all" を指定すると、全ての種類を計測します。個別に指定する場合は、ハッシュを渡します。詳細は、coverage ライブラリを参照してください。

bool.rb

def bool(obj)
  if obj
    true
  else
    false
  end
end

require "coverage"

Coverage.start(:all)
load "bool.rb"
bool(0)
pp Coverage.result
# {"bool.rb"=>
#   {:lines=>[1, 1, 1, nil, 0, nil, nil],
#    :branches=>
#     {[:if, 0, 2, 2, 6, 5]=>
#       {[:then, 1, 3, 4, 3, 8]=>1, [:else, 2, 5, 4, 5, 9]=>0}},
#    :methods=>{[Object, :bool, 1, 0, 7, 3]=>1}}}

Coverage.start(methods: true)
load "bool.rb"
bool(0)
pp Coverage.result  # => {"bool.rb"=>{:methods=>{[Object, :bool, 1, 0, 7, 3]=>1}}}

state -> SymbolRuby 3.1 から[permalink][rdoc][edit]

カバレッジの測定の状態を返します。

:idle(Coverage.setup も Coverage.start も行われていない状態)、:suspended(測定の準備はできているが一時停止中の状態)、:running(測定中の状態)のいずれかを返します。

require "coverage"
p Coverage.state  # => :idle
Coverage.setup
p Coverage.state  # => :suspended
Coverage.resume
p Coverage.state  # => :running

supported?(mode) -> boolRuby 3.2 から[permalink][rdoc][edit]

指定したモードのカバレッジ測定がサポートされているかどうかを返します。

[PARAM] mode:: :lines、:oneshot_lines、:branches、:methods、:eval のいずれかをシンボルで指定します。

require "coverage"
p Coverage.supported?(:lines)  # => true
p Coverage.supported?(:all)    # => false

suspend -> nilRuby 3.1 から[permalink][rdoc][edit]

カバレッジの測定を一時停止します。

再開するには Coverage.resume を使います。

[EXCEPTION] RuntimeError:: 測定中でない場合に発生します。

require "coverage"
Coverage.start
Coverage.suspend
p Coverage.state  # => :suspended

[SEE_ALSO] Coverage.resume

要約

目次

特異メソッド