前提
今回使用する技術は下記を前提としています。
業務で使用しているのがPHP/Laravelのため、本投稿でも使用しますが他言語でも基本的には問題ありません。
Summary表示まで実装するので、細かい箇所は各自で調べて頂ければ幸いです。
- Github Actions
- Pandoc
- PHP/Laravel
- テストユニットはPestを使用する
CI/CDフロー設計
- 特定ブランチへのpush、PR作成で発火
- Pestでカバレッジレポートを出力
- Pandocでレポート形式を変換
- Github Artifactに成果物を保存
- Github Job Summaryでレポート内容を表示
実装
フローにおけるテスト実行までの部分は割愛します。
テスト実行、カバレッジレポートの出力
Clover XMLやXML形式のパターンが多いかと思うのですが、Pandocが対応しているのは下記フォーマットのため、レポートの出力形式は.htmlで行います。
XML version of native AST
出力されるファイルはcoverage.index.htmlとなります。
- name: Tests
run: |
./vendor/bin/pest --coverage-html coverage
マークダウン形式への変換
Pandocを用いてマークダウンへの変換を行います。
github actionsでのSummary表示のためgfmへ変換します。
gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github;
use markdown_github only if you need extensions not supported in gfm.
- name: Convert HTML to Markdown
uses: docker://pandoc/core:3.5
with:
args: >-
--to=gfm
--output=coverage.md
coverage/index.html
Artifactへ保存
今回はmarkdown変換後のレポートのみ保存します。
また検証段階のため保存期間は1日と最短日数で指定しています。
- name: Upload Coverage Artifact
uses: actions/upload-artifact@v4
with:
name: coverage-report
path: coverage.md
# 検証のため最短期間で設定
retention-days: 1
Job Summaryでの結果表示
今回の本題です。
Pandocで変換したgfm形式のレポートをSummaryで表示します。
- name: Add Coverage to Job Summary
run: |
echo "# Test Coverage Report" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
cat coverage.md >> $GITHUB_STEP_SUMMARY
当初は通常のmarkdownで表示できるのかと思ったのですが、同僚からGitHub Flavored Markdownでいけるとアドバイスをもらいました。
実際、githubのドキュメントにも下記記述があります。
ジョブの概要では GitHub Flavored Markdown がサポートされていて、
ステップの Markdown コンテンツを GITHUB_STEP_SUMMARY 環境ファイルに追加できます。
ちなみにhtmlやxml、text形式のものをそのままpushしてもエラーにはなりませんが、明らかに表示が崩れてしまうのでご注意ください。
おわりに
上記のようになりました。
テストカバレッジレポートの形式をgfmに変換さえできれば、後はgithub公式のアクションで対応できるのでとても簡単でした！(むしろ変換の部分で手こずった印象です)
レポートの出力形式のスタイルをどうするかという部分はあるものの、表示するという基本部分についてはしっかり抑えられているかと思います。
みなさんもぜひ試してみてください！
おまけ
少し見栄えが悪いので整えてみました。
gfmへの変換前にcoverage/index.htmlを下記ステップで整形します。
- name: Remove breadcrumb and links from HTML
run: |
# Remove breadcrumb navigation
sed -i '/<nav aria-label="breadcrumb">/,/<\/nav>/d' coverage/index.html
# Remove directory icons
sed -i 's|<img src="_icons/[^"]*" class="octicon" />||g' coverage/index.html
# Remove links but keep text
sed -i 's|<a href="[^"]*">\([^<]*\)</a>|\1|g' coverage/index.html
はい、少しマシになりましたね