phpunit/php-code-coverageって何をしてるんだ #phperkaigi

PHPerKaigi 2024での発表資料です
https://fortee.jp/phperkaigi-2024/proposal/8543c51c-7e06-45d5-a216-cba29cb29789

Transcript

1. phpunit/php-code-coverage って何をしてるんだ PHPerKaigi 2024 Hideki Kinjyo GitHub: o0h / X: @o0h_ [発表用]
2. 自己紹介 • 金城秀樹 / きんじょうひでき • GitHub:@o0h / Twitter:@o0h_ • 好きなFWはCakePHP • アイコンは 美味しい鮭親子丼の写真です
3. このお話のねらい • 何となく耳にするし目にしたこともあるかも知れない 「カバレッジ」という概念への、なるほど！の提供 • 実際に「カバレッジを計測する」といった時に、 内部で何が起きているのか 基礎的な仕組みについて理解をする • その結果として、「なんとなく気持ちいいな！！」となる • もしかしたら何か素敵な実用方法を思いつくかも？ • (それは皆さんの心の中に── 
4. おしながき 1.おさらい！カバレッジ 〜それってそーいや何なのさ〜 2.PHPはどうやってカバレッジを出しているのか 3.応用的な話 〜coverageの仕組みを知っておくとできること〜 
5. おしながき 1.おさらい！カバレッジ 〜それってそーいや何なのさ〜 2.PHPはどうやってカバレッジを出しているのか 3.応用的な話 〜coverageの仕組みを知っておくとできること〜  (時間見つつ駆け足で)
6. 1. おさらい！カバレッジ 〜それってそーいや何なのさ〜 2. PHPはどうやってカバレッジを出しているのか 3. 応用的な話
7. よく見る(聞く)カバレッジ 
8. カバレッジ？ • 「網羅(cover)されている」割合 • 網羅する = 「実際に使われた(実行された)」状態 • コードがどのくらい網羅されている？ ➡ コードカバレッジ • テストによるコードカバレッジ ➡ テストカバレッジ 
9. 
10.  実行される
11. カバレッジの種類 • 一言で「カバレッジ」といっても、 観点によりいくつかの種類がある • PHPUnitのドキュメントでは 5種類のカバレッジに言及している • Line Coverage • Branch Coverage • Path Coverage • Function and Method Coverage • Class and Trait Coverage 7. Code Coverage — PHPUnit 11.0 Manual https://docs.phpunit.de/en/11.0/code-coverage.html 
12. カバレッジの種類 • 一言で「カバレッジ」といっても、 観点によりいくつかの種類がある • PHPUnitのドキュメントでは 5種類のカバレッジに言及している • Line Coverage • Branch Coverage • Path Coverage • Function and Method Coverage • Class and Trait Coverage 7. Code Coverage — PHPUnit 11.0 Manual https://docs.phpunit.de/en/11.0/code-coverage.html  ココだけ おさらい してみましょう
13. Line Coverage 行単位で通ったコード(の割合)  実行される
14. Branch Coverage 「分岐」単位で通ったコード(の割合)  実行される 実行されない
15. Branch Coverage 「分岐」単位で通ったコード(の割合)  実行される 実行される
16. Path Coverage 「経路」単位で通ったコード(の割合)  4つのパス(=分岐の組み合わせ)が生まれる
17. 比較すると？  Line Coverageを100%にするのは、どれでもOK OR OR OR
18. Branch Coverageを100%にするのは、$cの判定まで行く必要がある それさえあればOK 比較すると？  OR
19. Path Coverageを100%にするのは、すべて必要 (※1番下って必要？については説明しません！) 比較すると？  AND AND AND
20. ※興味のある人向けの情報(説明しない)
21. 1. おさらい！カバレッジ 2. PHPはどうやってカバレッジを出しているのか 3. 応用的な話
22. PHPでよく出会うカバレッジの出し方  計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行 • 色々な仕組みでリレーをしていく
23. PHPでよく出会うカバレッジの出し方  計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行 PHPUnitとか
24. PHPでよく出会うカバレッジの出し方  計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行 Xdebugとか pcovとか phpdbgとか
25. PHPでよく出会うカバレッジの出し方  計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行 Xdebugとか pcovとか phpdbgとか
26. PHPでよく出会うカバレッジの出し方  計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行 phpunit/ php-code-coverage
27. カバレッジデータの収集〜出力 計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行
28. 簡単な例 • Xdebugを利用し、カバレッジデータを収集する例を簡単に紹介します 
29. こんなコードがあったとします 
30. 足しました 
31. 注目すべき点 
32.  注目すべき点 xdebug_start_code_coverage() コールされた箇所からカバレッジ データの収集を開始 xdebug_get_code_coverage() 収集したカバレッジデータを取得 ※ 他に、 収集を停止する xdebug_stop_code_coverage()も
33. 実行します (Xdebugを「カバレッジモード」に指定します) 
34. でました 
35.  ファイル名 行番号 実行されたら`1` 実行されていない行はデータなし
36. Line Coverageのデータは・・・ • 単純に、ファイル名と行番号ごとにフラグを立てている • とっても単純！！ 
37. 少し踏み込んだ例 • より便利なデータを収集することもできます 
38. こんなコードがあったとします 
39. 足しました 
40. フラグ 
41.  フラグ XDEBUG_CC_UNUSED カバレッジデータに 未実行の行を含める XDEBUG_CC_DEAD_CODE カバレッジデータに 到達不能な行(デッドコード)を含める
42. 実行します (実行方法は同じ) 
43. でました 
44.  1度も実行されていない行は`-1` 到達不能な行は `-2`
45. ブランチカバレッジの例 • ブランチカバレッジのデータは どうやって取るのでしょうか？どうなっているでしょうか？ 
46. こんなコードがあったとします 
47. 足しました 
48.  新しいフラグ
49.  新しいフラグ XDEBUG_CC_BRANCH_CHECK ブランチごとの実行状態を収集する 単独では利用できず、 他のフラグと合わせて指定する
50. 実行します (実行方法は同じ) 
51. でました  ！？
52. 全体の骨格 
53. 全体の骨格  ファイルごとのkeyになるのは コレまでと同じ
54. 全体の骨格  ファイルごとのkeyになるのは コレまでと同じ `lines` `functions` に分かれる `lines` は行ごとのデータ。 ここまでに見てきたモノが そのまま格納される
55. 全体の骨格  今から注目するのはココ
56.  このコードは 3つのブランチからなると解釈される
57. ブランチってどういう風に作られるの？ ところで！
58. ブランチってなんだっけ • ブランチ = 分岐 • コードを上から処理して行って、 「共通して通る箇所」「条件によって分岐するところ」で分ける • 分けて出来上がったのがブランチ 
59.  このコードで言えば・・ ① 引数$xに値をセットする ② 引数$yに値をセットする ③ $xをチェックして、 真ならJUMP→⑤へ ④ $yをチェックする ⑤ おしまい！ 細 か い ス テ プ に 分 解
60.  このコードで言えば・・ ① 引数$xに値をセットする ② 引数$yに値をセットする ③ $xをチェックして、 真ならJUMP→⑤へ ④ $yをチェックする ⑤ おしまい！ ブランチその1 細 か い ス テ プ に 分 解
61.  このコードで言えば・・ ① 引数$xに値をセットする ② 引数$yに値をセットする ③ $xをチェックして、 真ならJUMP→⑤へ ④ $yをチェックする ⑤ おしまい！ ブランチその2 細 か い ス テ プ に 分 解
62.  このコードで言えば・・ ① 引数$xに値をセットする ② 引数$yに値をセットする ③ $xをチェックして、 真ならJUMP→⑤へ ④ $yをチェックする ⑤ おしまい！ ブランチその3 細 か い ス テ プ に 分 解
63. それ、OpCode見れば分かるよ • PHPのソースコードをさらに分解して、 単純化された命令の組み合わせに変換したのが「OpCode」 • CPUが実行可能なくらい単純、というイメージをしてもらえれば • ブランチやパスの分析には、OpCodeの情報を利用している 
64.  PHPコード 実際のOpCode 1. 引数$xに値をセットする 2. 引数$yに値をセットする 3. $xをチェックして、 真ならJUMP→⑤へ 4. $yをチェックする 5. おしまい！ 見比べてみておくれ 見比べてみておくれ
65. それ、OpCode見れば分かるよ ・・・という話をしていると、うまく20分にまとまらなかったので！！ 別の資料を展開します！！ (個人的には1番面白い部分だったので、ぜひ・・！ https://speakerdeck.com/o0h/phperkaigi-2024-omake 
66. Xdebugで分析するとブランチも教えてくれる • 簡単に言うと、 「OpCodeでいうと、ここからここまでが1つのブランチ」 の情報が出てくる
67. Source -> OpCode  実際のOpCode コレ自体は PHPの機能 (Xdebugの機能ではない) お役立ち: opcodeダンプするのにvldもphpdbgも要らなくなってた #PHP - Qiita https://qiita.com/hnw/items/352c5030d6729343a49e
68. OpCode -> Branch  1つのブランチ
69. Xdebugで分析するとブランチも教えてくれる • 簡単に言うと、 「OpCodeでいうと、ここからここまでが1つのブランチ」 の情報が出てくる • 「『ラベル1〜10で1つのブランチ』で、このブランチは『ブランチ3， 6，11のどれかにジャンプします』」という感じ
70. Branch(op_start / out) 
71. 再:カバレッジデータの収集〜出力 計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行
72. ブランチごとの到達(実行)回数 hit: ブランチに到達した回数 
73. 未到達の場合も記録されている ブランチに到達しなかった例 
74. パスカバレッジの例 • パスカバレッジのデータは どうやって取るのでしょうか？どうなっているでしょうか？ 
75. とりかたは同じ 
76. 全体の骨格 
77. 全体の骨格  今から注目するのはココ
78.  このコードは 20のパスからなると解釈される
79.  通るブランチの番号 (=op_start)の列挙
80.  ブランチとパスのデータ(一部、フォーマット済み) 0を起点に、全てのoutを辿っていけば全パスを網羅できる
81. Branch(op_start / out) 
82. Branch -> path 
83. Branch -> path 
84.  hit: パスに到達した回数
85. カバレッジの集計 計測(データの収集) 収集データの出力 集計／レポート作成 プログラムの実行
86. PHPUnitのカバレッジレポート機能 PHPUnitのテスト実行時にオプションを付与する • coverage-html=$path: HTMLレポートを$pathに生成する • その他に、coverage-xml・coverage-textなどの形式 • coverage-filter: カバレッジレポートに含める対象を指定する • 通常の運用ではphpunit.xml上で指定することが多い 
87. 気になること • Xdebug等のカバレッジ収集機能、どこで管理してるの？ • テストされていないファイルや、 読み込まれていないファイルも取り扱っているよね？ 
88. 気になること • Xdebug等のカバレッジ収集機能、どこで管理してるの？ • テストされていないファイルや、 読み込まれていないファイルも取り扱っているよね？ 
89. PHPUnitの起動〜テスト実行までの流れ テストケースの実行 個別のテストケースの管理 テスト一式の管理 全体の管理 PHPUnit\TextUI\ Application::run() vendor/bin/phpunit -> phpunit.php PHPUnit\TextUI\ TestRunner::run() PHPUnit\Framework\ TestSuite::run() PHPUnit\Framework\ TestCase::run() PHPUnit\Framework\ TestRunner::run() PHPUnit\Framework\ TestCase::runBare() PHPUnit\Framework\ TestCase::runTest() PHPUnit\Framework\ TestCase::{ケース}()  `phpunit`コマンドの実行から個別のテストケースが実行されるまでは、 ざっくりとこうした流れとなる
90. PHPUnitの起動〜テスト実行までの流れ テストケースの実行 個別のテストケースの管理 テスト一式の管理 全体の管理 PHPUnit\TextUI\ Application::run() vendor/bin/phpunit -> phpunit.php PHPUnit\TextUI\ TestRunner::run() PHPUnit\Framework\ TestSuite::run() PHPUnit\Framework\ TestCase::run() PHPUnit\Framework\ TestRunner::run() PHPUnit\Framework\ TestCase::runBare() PHPUnit\Framework\ TestCase::runTest() PHPUnit\Framework\ TestCase::{ケース}()  「カバレッジ収集の初期設定」「(終了後)レポートデータの生成」を実行する
91. PHPUnit\Runner\CodeCoverage • PHPUnitの内部のクラスで、 コードカバレッジの収集・レポート生成等の機能を調整する 
92. PHPUnitの起動〜テスト実行までの流れ テストケースの実行 個別のテストケースの管理 テスト一式の管理 全体の管理 PHPUnit\TextUI\ Application::run() vendor/bin/phpunit -> phpunit.php PHPUnit\TextUI\ TestRunner::run() PHPUnit\Framework\ TestSuite::run() PHPUnit\Framework\ TestCase::run() PHPUnit\Framework\ TestRunner::run() PHPUnit\Framework\ TestCase::runBare() PHPUnit\Framework\ TestCase::runTest() PHPUnit\Framework\ TestCase::{ケース}()  「カバレッジ収集の開始」「終了」を実行する
93. PHPUnit\Runner\CodeCoverage • 具体的に計測の開始・終了の操作を担うのもCodeCoverageクラス • `start()` `stop()` Methodを介して行う 
94. SebastianBergmann\CodeCoverage\Driver • `CodeCoverage::start()`, `::stop()`メソッドは、 `SebastianBergmann\CodeCoverage\Driver` Interfaceを 内部的に利用し、PHP拡張の機能を呼び出す • `PcovDriver`,`XdebugDriver`といった具象クラスが存在 ※`phpunit/php-code-coverage` パッケージのクラス。 パッケージ名と名前空間のvendorが一致していないので少し注意 
95. SebastianBergmann\CodeCoverage\Driver • `XdebugDriver::start()`であれば、 `xdebug_start_code_coverage()` を呼び出す 
96. SebastianBergmann\CodeCoverage\Driver • `PcovDriver`であれば、 `\pcov\start()`を呼び出す 
97. という感じで、 カバレッジ収集が管理されている
98. 気になること • Xdebug等のカバレッジ収集機能、どこで管理してるの？ • テストされていないファイルや、 読み込まれていないファイルも取り扱っているよね？ 
99. 実行されていないファイル情報の取得 • XdebugやPcovのもたらす実行情報は、 「読み込まれたファイル」に関するもののみ • しかし、カバレッジレポートは 「プロジェクト全体(etc)」について出力されるのが一般的 • そこで出てくるのが、 カバレッジの「分母」に関する情報 
100. SebastianBergmann\CodeCoverage\Filter • `phpunit/php-code-coverage` のクラス • `phpunit.xml`に含まれる `source` > `include/exclude` に 相当する情報を扱う • ここで集計対象となるファイルの列 挙・管理が行われる 
101. PHPUnitの起動〜テスト実行までの流れ テストケースの実行 個別のテストケースの管理 テスト一式の管理 全体の管理 PHPUnit\TextUI\ Application::run() vendor/bin/phpunit -> phpunit.php PHPUnit\TextUI\ TestRunner::run() PHPUnit\Framework\ TestSuite::run() PHPUnit\Framework\ TestCase::run() PHPUnit\Framework\ TestRunner::run() PHPUnit\Framework\ TestCase::runBare() PHPUnit\Framework\ TestCase::runTest() PHPUnit\Framework\ TestCase::{ケース}()  タイミングとしては、ここで行われる (`CodeCoverage::instance()->init()`と同じ箇所からの起動)
102. 1. おさらい！カバレッジ 2. PHPはどうやってカバレッジを出しているのか 3. 応用的な話 〜coverageの仕組みを知っておくとできること〜
103. 「テストカバレッジ」以外の活用例 • ここまでで、 カバレッジのデータの収集・出力の仕組みが分かりました • 代表的なユースケースは やはり「テストカバレッジデータの集計」だと思います • が、それ以外にも色々ある予感がする • せっかくなので、いくつか「他の使い道」を考えてみましょう！ 
104. phpunit/phpcov
105. phpunit/phpcov • PHPUnitの作者(@sebastianbergmann)により作成されたツール • コードカバレッジの取得・レポート作成を行う • `phpunit/php-code-coverage` を使うためのUI、という位置づけ (“CLI frontend for php-code-coverage”) • 要するに、PHPUnitを抜きにして && テストではなく何でも自由にカバレッジを測れる 
106. 使い方 (execute) • `phpcov execute $PHP_SCRIPT` で、 その$PHP_SCRIPTの実行によって、 カバーされたコードを分析する • 仕組みはシンプルで、 `\SebastianBergmann\CodeCoverage\CodeCoverage::start()` を実行した後に $PHP_SCRIPTをproxy、実行後に `CodeCoverage::stop()`してレポートを生成 • Options • `—include`: 集計対象に含めるパス • `—html` `—text` `—php` `—clover` (など): 出力するレポート形式・出力先 • `—path-coverage`: パスカバレッジ分析の実行 
107. 実行サンプル ↑ CLIからの実行 ← 生成されたレポート 
108. 使い方 (merge) • `phpcov merge $DETA_DIR_PATH` で、 $DETA_DIR_PATHに含まれている 複数のカバレッジデータを合成した 解析結果レポートを出力する • 合成のものとになるのは `—php`の形式で、拡張子を`.cov`で揃えたもの • PHP形式=`SebastianBergmann\CodeCoverage\CodeCoverage`オブジェクトの serialized文字列 • Options • `—html` `—text` `—php` `—clover` (など): 出力するレポート形式・出力先 
109. 実行サンプル ← 与える入力値を変え、同一スクリプトに関して `phpcov execute`を複数回実行している。 データ出力先となるファイル名はユニークに ↓ マージしたレポートの生成を実行 
110. 使い方 (patch-coverage) • この話は移動しました • 資料の最後にあります！！(302)
111. EndToEnd、 その他の実行形式のカバレッジ計測 
112. プロダクションの「使われていないコード」検知 • Xdebugの作者が、自身のYoutubeに挙げている例 • https://www.youtube.com/watch?v=T9rwW-uySBE • 例えば、廃止した機能の安全な削除を考える際に有効 • パフォーマンスの問題と向き合いながらの活用方法になるので注意 
113. シナリオテストとの合体 • `k2tzumi/laravel-coverage-middleware` は、 シナリオテストツール runnと組み合わせて使うカバレッジ収集機構 • 「テスト」といっても単体テストだけではない • 結合テストやE2Eなど、 テストが「広く」なればなるほど コード内部との結合はゆるく出来る この後のLTで楽しみにしているやつです！！ → 
114. 他にも色々とアイディアはあるはず・・ • テストコード自体のカバレッジ • 「実は動いていないテストコード」があったら消したい • Property based testingやMutation testingとの組み合わせ • 肝要なのは、 「どうやって起動・終了させるか」「集めたデータがどんな値を持っ ているか」「それを組み立てるツールの存在と使い方」 を知ること • 基本さえ掴んでしまえば、自身のニーズに合わせて活用が効く！
115. まとめ
116. 自分の目で確かめると面白いし応用が効く！ • 今回は、「気になったから突っ込んでみた」「そしたら納得感があっ たし面白かった！！」という体験を基に、お話しました • 「カバレッジレポート」は何か派手で凄い！なイメージでしたが、 調べてみたら凄く地道で単純なデータの集合なんだなぁと知りました • 普段の開発においては知らなくてもいい話だろうな〜とも思います • でも、知っておくと・・・気持ちいいんすわ。 • 皆さんも、身の回りの「実はよく知らないかも！！」に気づいて ズブズブと足を踏み入れてみましょう！
117. おしまい！ お付き合いいただき ありがとうございました!!
118. おまけ: phpcov patch-coverage
119. 使い方 (patch-coverage) • コードの変更差分に対して、 行カバレッジの統計を出す機能 • `phpcov patch-coverage --path-prefix $INCLUDE_PATH_PREFIX $COVERAGE_DATA $PATCH`で実行 • 出力はテキスト形式のみで、高機能なレポートは提供しない • その代わり、include/exclude等の詳細なオプションを必要としない
120. 使い方 (patch-coverage) • ざっくり言うと 「patchファイルと、カバレッジデータ(.cov)を比べて」 「差分がある箇所について、カバーされている/されていない」 を出力するコマンド • patchは `git diff` とかから取ってくる！
121. 利用例 • 例えば こんなコードがあり
122. 利用例 • 利用するコードもあって • ちなみに `main3.php`とい うスクリプトです。名前は適 当
123. 利用例 • カバレッジは こんな状況になっています • ちなみに、これは `execute --text` で出しています
124. 利用例 • PHP形式で、カバレッジ データを出力しておきます
125. 利用例 • 新しいメソッドを 足しました
126. 利用例 • `git diff` の結果です • これを `main3.text` と いうファイルに保存してお きます(ファイル名は適当)
127. 利用例 • path-coverageを実行
128. • 実行可能なコードが 1行分増加している 利用例
129. • 増加したコードの内で、 0行がカバーされている (割合でいうと0.00%) 利用例
130. • 変更されたがカバーされて いない箇所の詳細 利用例
131. 例えば、の使い方 • CIとは相性良さそう • GitHub Actionsに組み込めば 「カバーされていない行にコメント」とか出来そう？ • 「diffにある指定の行に指摘をする」は、提供されているAPI経由で行える • 過去に書いた記事(情報が古い可能性があります、確認していません！！) > PHPUnitの実行結果(失敗したテスト)をProblem MatcherでPRのdiffに示す https://daisuki.nichiyoubi.land/entry/phperkaigi-2022-lt-hosoku
132. おまけ: PHPUnitで吐き出せるカバレッジ5種
133. カバレッジの種類 • 一言で「カバレッジ」といっても、 観点によりいくつかの種類がある • PHPUnitのドキュメントでは 5種類のカバレッジに言及している • Line Coverage • Branch Coverage • Path Coverage • Function and Method Coverage • Class and Trait Coverage 7. Code Coverage — PHPUnit 11.0 Manual https://docs.phpunit.de/en/11.0/code-coverage.html 
134. Line Coverage • 行単位で通ったコードの割合 • 右のスニペットは、 カバレッジが100%となる 
135. 
136. Function and Method Coverage • 関数・メソッドの内で 実行された割合 • 右のスニペットは、 カバレッジが50%となる • 定義されている関数が2つ • 実行はhoge()のみ 
137. 
138. Class and Trait Coverage • クラス・トレイトの内で 1メソッド以上実行された割合 • 自前のメソッドの実行が条件 • 継承元への転送ではダメ • コンストラクタも除く • 右のスニペットは、 カバレッジが2/3になる • クラス`C`は カバーされていないとみなされる 
139. 
140.  `C::getI()`を検証しても 「クラスCのメソッド」とは みなされないまま
141. Branch Coverage • 分岐(ブランチ)を考慮し 通ったコードの割合 • 同一行にある分岐も 区別できる • 右のスニペットは、 カバレッジが50%程度となる 
142.  $aの値に関わらず、必ず$aは評価される ($a=true || $b=true)は$aを無視しない ($a=false || $b=true)も$aを無視しない $aの値によって、$bは評価を省略される ($a=true || $b=true)は$bを通らない ($a=false || $b=true)は$bを通る
143.  1つのコードに対して、 「場合分け」をした上での カバー範囲を判定している様子
144.  「行」と「ブランチ」でカバレッジが異なる例 5行目は実行されている(カバーされている)が、 $aの短絡評価の結果により、$bの評価まで処理が行っていない(カバーされていない)
145. Path Coverage • 経路(=分岐の組み合わせ)で 通ったコードの割合 • 右のスニペットは、 カバレッジが1/8になる • boolの変数3つの組み合わせで 2^3=8通りのパスが存在 • テストできているのは1パス 
146.  ブランチの観点から カバレッジを満たしても パスではカバレッジが低いまま