|
|
Code coverage consists of a set of software metrics
that can tell you how much of the production code is covered by a given test suite.
コード カバレッジは、特定のテスト スイートによって本番環境コードのどの程度がカバーされているかを示すソフトウェア メトリックのセットから構成されます。
It's purely quantitative, and does not say anything about the quality of either the production code or the test code.
これは純粋に定量的なものであり、製品コードやテスト コードの品質については何も言及していません。
That said, the examination of code coverage reports will sometimes lead to the discovery of unreachable code which can be eliminated.
ただし、コード カバレッジ レポートを調べると、到達不能なコードが発見され、それを排除できる場合があります。
But more importantly, such reports can be used as a guide for the discovery of missing tests.
しかし、さらに重要なのは、このようなレポートは、欠落しているテストを発見するためのガイドとして使用できることです。
This is not only useful when creating tests for existing production code, but also when writing tests first, such as in the practice of
TDD (Test Driven Development).
これは、既存の製品コードのテストを作成するときだけでなく、TDD (テスト駆動開発) の実践など、最初にテストを記述するときにも役立ちます。
The coverage metric produced by the tool tells us how much of the executable code in a source file has been exercised
by tests, and also how many of the instance and static non-final fields were fully exercised by the test run.
ツールによって生成されるカバレッジ メトリックは、ソース ファイル内の実行可能コードのうちテストによって実行されたコードの数と、テスト実行によって完全に実行されたインスタンス フィールドと静的な非最終フィールドの数を示します。
Each executable line of code can be uncovered, covered, or partially covered.
実行可能な各コード行は、カバーされない、カバーされる、または部分的にカバーされる可能性があります。
The third case can happen, for example, with lines of code containing multiple logical conditions in a complex boolean expression.
3 番目のケースは、たとえば、複雑なブール式に複数の論理条件を含むコード行がある場合に発生する可能性があります。
The tool identifies all three cases, computing the coverage percentage for each executable line of code accordingly:
ツールは 3 つのケースすべてを識別し、それに応じて実行可能なコード行ごとのカバレッジ パーセンテージを計算します。
0% for an uncovered line, 100% for a covered line, or some value in between for a partially covered
line.
カバーされていないラインの場合は 0%、カバーされているラインの場合は 100%、部分的にカバーされているラインの場合はその中間の値になります。
Regarding fields, to be fully exercised, each must have the last value assigned to it read by at least one test.
フィールドに関しては、完全に実行されるためには、各フィールドに割り当てられた最後の値が少なくとも 1 つのテストによって読み取られる必要があります。
The coverage percentage for a source file is calculated as 100 * (NE + NFE) / (NS + NF), where NS is the total
number of line segments, NF the number of non-final fields, NE the number of executed segments, and
NFE the number of fully exercised fields.
ソース ファイルのカバレッジ パーセンテージは、100 * (NE + NFE) / (NS + NF) として計算されます。ここで、NS は行セグメントの合計数、NF は最終でないフィールドの数、NE は実行されたセグメントの数、NFE は完全に実行されたフィールドの数です。
The percentage for a package, in turn, is calculated from the total and covered numbers of segments and fields in the whole set
of source files belonging to the package.
パッケージのパーセンテージは、パッケージに属するソース ファイル セット全体のセグメントとフィールドの合計数とカバー数から計算されます。
Finally, the total code coverage percentage is computed by the same formula on the totals for all packages.
最後に、すべてのパッケージの合計に対して同じ式を使用して、合計コード カバレッジ パーセンテージが計算されます。
The JMockit Coverage tool can generate the following types of output:
JMockit カバレッジ ツールは、次のタイプの出力を生成できます。
.java" source files inside all directories of name "src" found directly or
indirectly under the current working directory; any intermediate sub-directories between "src" and the top-level package
directory, such as "src/java" for example, are also searched.coverage.ser" is written under the current
working directory or a specified output directory.mockit.coverage.data.CoverageData.readDataFromFile(File) method will create a new
CoverageData instance with all the coverage data available in a given serialized file.
When running a test suite with the coverage tool, there is optional "call point" information which can be gathered, as selected by the
user.
カバレッジ ツールを使用してテスト スイートを実行する場合、ユーザーが選択したオプションの「呼び出しポイント」情報を収集できます。
A call point is the point in the source test code from which a specific line of production code was exercised.
呼び出しポイントとは、ソース テスト コード内で特定の製品コード行が実行されたポイントです。
Generating coverage with this extra information takes more time and produces significantly larger output;
on the other hand, it can be useful to know which lines of test code caused a given line of production code to be executed during the
test run.
この追加情報を使用してカバレッジを生成すると、時間がかかり、出力が大幅に大きくなります。一方、テスト実行中に、どのテスト コード行が特定の製品コード行の実行を引き起こしたかを知ることは有用です。
When included in the HTML report, the list of call points appears hidden at first but can be easily viewed by clicking on each executable
line of code.
HTML レポートに含まれている場合、呼び出しポイントのリストは最初は非表示で表示されますが、実行可能なコードの各行をクリックすると簡単に表示できます。
To activate the Coverage tool in a JUnit/TestNG test run, use the -javaagent JVM initialization parameter, and specify at
least one of the "coverage-output" and "coverage-classes" system properties.
JUnit/TestNG テスト実行でカバレッジ ツールをアクティブにするには、-javaagent JVM 初期化パラメータを使用し、「coverage-output」および「coverage-classes」システム プロパティの少なくとも 1 つを指定します。
(See Running tests with JMockit for more details.)
(詳細については、「JMockit を使用したテストの実行」を参照してください。)
All aspects of the tool's behavior can be configured by setting one or more of the following properties.
次のプロパティの 1 つ以上を設定することで、ツールの動作のすべての側面を構成できます。
coverage-output: one or more comma-separated values between html,
html-cp ("cp" = "call points"), html-nocp,
serial, and serial-append, which select the kind of output to be generated
at the end of the test run.html = html-nocp).serial" or "serial-append" causes a serialized data file of name
"coverage.ser" to be generated; with "serial-append", coverage data gathered by the current test run will be
appended to the contents of a previously existing data file (if said file doesn't exist, it has the same effect as
"serial").coverage-outputDir: absolute or relative path to the output directory, to be used for writing any
"coverage.ser" or "index.html" files (plus the remaining ".html" files of the HTML report, in
automatically created sub-directories).coverage-report" sub-directory.coverage-srcDirs: comma-separated list of Java source directories to be searched when generating an HTML
report.src" directories under the current working directory are searched.index.html file is
generated.coverage-classes:
Either an OS-like regular expression (with the typical "*" and "?" wildcards), or a
java.util.regex-conformable
regular expression.some.package.*" selects all classes under some.package or any sub-package.loaded", then all classes will be considered, but only those which
get loaded by the JVM during the test run; classes that are part of the codebase but never get loaded are left out.coverage-excludes:
The same as the previous property, but for class names which should be excluded from consideration when instrumenting classes for
coverage.coverage-classes or on its own.coverage-check:
one or more semicolon-separated rules specifying minimum coverage checks to be performed at the end of a test run.
Note that you should be able to easily specify these properties inside a Maven surefire plugin configuration, or a test run
configuration for your Java IDE of choice, using either JUnit or TestNG; no JMockit-specific plugin is needed.
これらのプロパティは、Maven の surefire プラグイン構成内、または JUnit または TestNG を使用して選択した Java IDE のテスト実行構成内で簡単に指定できるはずです。JMockit 固有のプラグインは必要ありません。
When the coverage tool generates a report at the end of a test run, it always overwrites any previous report.
カバレッジ ツールがテスト実行の最後にレポートを生成すると、以前のレポートは常に上書きされます。
Normally, the coverage data from which the report is generated reflects only what was gathered during the current test run.
通常、レポートが生成されるカバレッジ データは、現在のテスト実行中に収集された内容のみを反映します。
Now suppose you have multiple test suites or test run configurations, and you want to generate a single aggregated HTML report for the
code covered by the full set of tests.
ここで、複数のテスト スイートまたはテスト実行構成があり、完全なテスト セットでカバーされるコードに対して単一の集約された HTML レポートを生成するとします。
Here is where the "coverage.ser" serialized data files come in.
ここで、「coverage.ser」シリアル化データ ファイルが登場します。
To activate the generation of these files, we simply set the coverage-output system property to a value containing
"serial" or "serial-append".
これらのファイルの生成を有効にするには、coverage-output システム プロパティを「serial」または「serial-append」を含む値に設定するだけです。
As these two values suggest, there are different ways to combine multiple coverage data files.
これら 2 つの値が示すように、複数のカバレッジ データ ファイルを結合する方法はいくつかあります。
The following sub-sections provide the details for each case.
次のサブセクションでは、各ケースの詳細を説明します。
Suppose we want to gather coverage data from multiple test runs and later generate an aggregate HTML report merging together the results
from all test runs.
複数のテスト実行からカバレッジ データを収集し、後ですべてのテスト実行の結果を結合した集計 HTML レポートを生成するとします。
Each test run needs to generate its own coverage.ser file, so that later they can be merged together in a final step which
produces the report; therefore, each test run should be configured with "coverage-output=serial".
各テスト実行では独自の coverage.ser ファイルを生成する必要があります。これにより、後でレポートを生成する最終ステップでそれらのファイルを結合できます。したがって、各テスト実行は "coverage-output=serial" で構成する必要があります。
Note that, in order to preserve the original coverage.ser output files generated by each test run, they will need to be
written or copied into different output directories.
各テスト実行によって生成された元の coverage.ser 出力ファイルを保持するには、それらを別の出力ディレクトリに書き込むかコピーする必要があることに注意してください。
Assuming that two or more coverage.ser files are available in separate directories, an aggregate report can be generated
from them by executing the mockit.coverage.CodeCoverage.main method (a regular Java "main" method).
2 つ以上の coverage.ser ファイルが別々のディレクトリにあると仮定すると、mockit.coverage.CodeCoverage.main メソッド (通常の Java "main" メソッド) を実行することによって、それらから集計レポートを生成できます。
To facilitate this, the jmockit-1.x.jar file is executable.
これを容易にするために、jmockit-1.x.jar ファイルが実行可能です。
As an example, the following Ant task could be used:
例として、次の Ant タスクを使用できます。
<java fork="yes" dir="myBaseDir" jar="jmockit-1.x.jar">
<jvmarg line="-Dcoverage-output=html"/>
<arg line="module1-outDir anotherOutDir"/>
</java>
The example above uses "myBaseDir" as the base directory where a separate JVM instance will run.
上記の例では、別の JVM インスタンスが実行されるベース ディレクトリとして「myBaseDir」を使用しています。
Two output directories containing "coverage.ser" data files are specified, as command line arguments.
「coverage.ser」データ ファイルを含む 2 つの出力ディレクトリがコマンド ライン引数として指定されます。
Other configuration parameters can be specified through the "coverage-xyz" system properties.
その他の構成パラメータは、「coverage-xyz」システム プロパティを通じて指定できます。
This separate JVM instance will read each of the "coverage.ser" data files, merge the coverage data in memory, and then
generate the aggregate HTML report before exiting.
この個別の JVM インスタンスは、各 "coverage.ser" データ ファイルを読み取り、メモリ内のカバレッジ データをマージし、終了する前に集計 HTML レポートを生成します。
Another way to obtain an aggregate coverage report from the execution of multiple test runs is to accumulate coverage data from all tests
into a single data file.
複数のテスト実行から集計カバレッジ レポートを取得する別の方法は、すべてのテストからのカバレッジ データを 1 つのデータ ファイルに蓄積することです。
This can be achieved by using the same working directory for all test runs or by pointing coverage-outputDir to a shared
directory, while having coverage-output=serial-append for each test run.
これは、すべてのテスト実行に同じ作業ディレクトリを使用するか、coverage-outputDir を共有ディレクトリにポイントし、各テスト実行に coverage-output=serial-append を設定することで実現できます。
Additionally, the last test run in the sequence should also specify html or html-nocp for the
coverage-output property, together with serial-append.
さらに、シーケンス内の最後のテスト実行では、serial-append とともに、coverage-output プロパティに html または html-nocp も指定する必要があります。
Naturally, the first test run must not read data from this file; therefore, either the file should be deleted before the first
test run, or ignored by having the first test run use coverage-output=serial.
当然、最初のテスト実行ではこのファイルからデータを読み取ってはなりません。したがって、最初のテスト実行の前にファイルを削除するか、最初のテスト実行で coverage-output=serial を使用して無視する必要があります。
So, the difference between output modes "serial" and "serial-append" is that with the first we have multiple
"coverage.ser" files (each in a different directory used by a separate test run), while with the second we share a single
data file between all test runs.
したがって、出力モード「serial」と「serial-append」の違いは、前者では複数の「coverage.ser」ファイル（それぞれが個別のテスト実行で使用される異なるディレクトリ内）があるのに対し、後者ではすべてのテスト実行間で単一のデータ ファイルを共有することです。
If desired, JMockit Coverage can check that the final coverage percentages at the end of a test run satisfy arbitrary minimum values.
必要に応じて、JMockit Coverage は、テスト実行終了時の最終的なカバレッジ パーセンテージが任意の最小値を満たしているかどうかを確認できます。
Such checks can be specified through one or more checking rules assigned to the "coverage-check" system property
(when more than one, they must be separated by ";" characters).
このようなチェックは、「coverage-check」システム プロパティに割り当てられた 1 つ以上のチェック ルールを通じて指定できます (複数の場合は、「;」文字で区切る必要があります)。
Each checking rule must be in the form "[scope:]min percentage".
各チェックルールは「[スコープ:]最小パーセンテージ」の形式にする必要があります。
There are three types of scopes:
スコープには次の 3 つの種類があります。
80" specifies that the total coverage should be at least 80%.perFile: Specifies minimum percentages that each source file must satisfy.perFile:50", meaning that each source file must have at least 50% of coverage.com.important:90" specifies that total coverage for files under "com.important"
should be at least 90%.
All checks (if any) are performed at the end of the test run (at JVM shutdown, actually).
すべてのチェック (ある場合) は、テスト実行の終了時 (実際には JVM のシャットダウン時) に実行されます。
Other forms of output (HTML report, serialized file) are not affected.
その他の形式の出力 (HTML レポート、シリアル化されたファイル) は影響を受けません。
When an individual check fails, a descriptive message is printed to standard output.
個々のチェックが失敗すると、説明メッセージが標準出力に出力されます。
If one or more checks have failed, two final actions are taken to have the fact reported: first, an empty file of name
"coverage.check.failed" is created in the current working directory; second, an error (specifically, an
AssertionError) is thrown.
1 つ以上のチェックが失敗した場合、事実を報告するために 2 つの最終アクションが実行されます。まず、現在の作業ディレクトリに「coverage.check.failed」という名前の空のファイルが作成されます。次に、エラー (具体的には AssertionError) がスローされます。
When checks are performed but they all pass, the "coverage.check.failed" file, if present in the current directory, is
deleted.
チェックが実行され、すべて合格した場合、現在のディレクトリに「coverage.check.failed」ファイルが存在する場合は削除されます。
The use of a file to mark the success or failure of coverage checks is meant to allow build tools to react accordingly, typically by
failing the build when the file is present.
カバレッジ チェックの成功または失敗をマークするためにファイルを使用すると、ビルド ツールがそれに応じて反応し、通常はファイルが存在する場合にビルドを失敗させることができます。
For example, we can do the following in a Maven pom.xml file:
たとえば、Maven pom.xml ファイルでは次の操作を実行できます。
<plugin>
<artifactId>maven-enforcer-plugin</artifactId>
<executions>
<execution>
<id>coverage.check</id>
<goals><goal>enforce</goal></goals>
<phase>test</phase>
<configuration>
<rules>
<requireFilesDontExist>
<files><file>target/coverage.check.failed</file></files>
</requireFilesDontExist>
</rules>
</configuration>
</execution>
</executions>
</plugin>
With Maven, the surefire plugin is the one usually responsible for running tests.
Maven では、通常、surefire プラグインがテストの実行を担当します。
To activate and configure the coverage tool, specify values for the appropriate "coverage-xyz" system properties.
カバレッジ ツールをアクティブ化して構成するには、適切な「coverage-xyz」システム プロパティの値を指定します。
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>
-javaagent:"${settings.localRepository}"/org/jmockit/jmockit/${jmockit.version}/jmockit-${jmockit.version}.jar
<!-- Coverage properties -->
<!-- At least one of the following needs to be set: -->
-Dcoverage-output=html <!-- or html-cp, serial, serial-append; if not set, defaults to "html" -->
-Dcoverage-classes=loaded <!-- or a "*" expression for class names; if not set, measures all production code classes -->
<!-- Other properties, if needed: -->
-Dcoverage-outputDir=my-dir <!-- default: target/coverage-report -->
-Dcoverage-srcDirs=sources <!-- default: all "src" directories -->
-Dcoverage-excludes=some.package.* <!-- default: empty -->
-Dcoverage-check=80 <!-- default: no checks -->
</argLine>
</configuration>
</plugin>
To have the JMockit Coverage HTML report included in the generated Maven
site documentation, the src/site/site.xml descriptor file needs to be provided, with contents similar to what's shown
below.
生成された Maven サイト ドキュメントに JMockit カバレッジ HTML レポートを含めるには、以下に示すような内容の src/site/site.xml 記述子ファイルを提供する必要があります。
<?xml version="1.0" encoding="UTF-8"?>
<project
xmlns="http://maven.apache.org/DECORATION/1.3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.3.0
http://maven.apache.org/xsd/decoration-1.3.0.xsd">
<body>
<menu ref="reports"/>
<menu>
<item name="Code Coverage Report" href="../../coverage-report/index.html"/>
</menu>
</body>
</project>
To temporarily turn coverage off for a particular test run, we can set the coverage-output system property
to an unknown output format, such as "-Dcoverage-output=none".
特定のテスト実行のカバレッジを一時的にオフにするには、coverage-output システム プロパティを「-Dcoverage-output=none」などの不明な出力形式に設定します。
The same effect will be achieved by setting "-Dcoverage-classes=none".
「-Dcoverage-classes=none」を設定することで同じ効果が得られます。
Another, more interactive, way is to manipulate the read-only attribute of the relevant output file, when one has already been
generated.
もう 1 つのよりインタラクティブな方法は、関連する出力ファイルがすでに生成されている場合に、その出力ファイルの読み取り専用属性を操作することです。
The particular file to be manipulated, always in the working directory, is "coverage.ser" for serialized output or
"coverage-report/index.html" for HTML output.
操作対象となる特定のファイルは、常に作業ディレクトリにあり、シリアル化された出力の場合は「coverage.ser」、HTML 出力の場合は「coverage-report/index.html」です。
The file attribute is checked by JMockit at startup; when marked as read-only it cannot be overwritten, so JMockit avoids the attempt
entirely.
ファイル属性は起動時に JMockit によってチェックされます。読み取り専用としてマークされている場合は上書きできないため、JMockit は上書きの試行を完全に回避します。
Note that the working directory can usually be selected separately for each test run configuration in the Java IDE.
通常、作業ディレクトリは、Java IDE の各テスト実行構成ごとに個別に選択できることに注意してください。
Also, a Java IDE usually provides an easy mechanism to toggle the read-only status of a file in the project:
また、Java IDE では通常、プロジェクト内のファイルの読み取り専用ステータスを切り替える簡単なメカニズムが提供されます。
in IntelliJ IDEA it is done by double clicking the status bar, with the desired file opened in the editor;
in Eclipse there is a "Read only" check box in the "Properties" screen (which can be opened by typing "Alt+Enter") for the text file
selected in the editor.
IntelliJ IDEA では、エディターで目的のファイルを開いた状態でステータス バーをダブルクリックすることで実行されます。Eclipse では、エディターで選択したテキスト ファイルの [プロパティ] 画面 ([Alt+Enter] と入力して開くことができます) に [読み取り専用] チェック ボックスがあります。