GitHub Actions を使っていると、
「CI のテスト結果が見づらい」と感じることが増えてきた。
例えば：
- ログを延々スクロールしないと失敗箇所が分からない
- Jest / Vitest の JSON を毎回 jq で加工している
- summary に coverage を出したい
- failed test を PR 上でサッと確認したい
特に複数 repository へ横展開し始めると、
「毎回 CI 側で JSON を加工する」
実装がかなり辛くなってくる。
そこで今回、
Jest / Vitest の JSON を読み取り、
- GitHub Actions Step Summary 向け Markdown を生成
- Coverage 表示
- Failed Test 一覧
- ローカル preview
などをまとめて行う CLI を作った。
npm package 名は：
@acme/ci-test-summary
CLI コマンドは：
ci-summary
を使う。
GitHub Actions の $GITHUB_STEP_SUMMARY が便利
GitHub Actions には、
$GITHUB_STEP_SUMMARY
という特殊な環境変数がある。
ここへ Markdown を書き込むと、
Actions UI 上に整形済みの Summary を表示できる。
例えば：
- 総テスト数
- 成功 / 失敗数
- Coverage
- Failed Test
などを Markdown Table 付きで表示できる。
CI ログを掘らなくても、
PR 上で結果を見やすく確認できるのがかなり便利だった。
利用イメージ
GitHub Actions ではこんな感じで使う。
- name: Run tests
run: npm run test:ci
- name: Write CI summary
if: always()
run: |
ci-summary \
--format auto \
--json artifacts/test-results/unit.json \
--coverage coverage/coverage-summary.json \
--title "Unit Tests"
実際には：
- Jest / Vitest JSON を読み取り
- Markdown Summary を生成
-
$GITHUB_STEP_SUMMARYに追記
している。
Jest / Vitest は JSON 構造が結構違う
最初は単純に、
jq
で JSON を加工しようとしていた。
単一 repository の間は、
それでもそこまで困らなかった。
しかし：
- repository 数
- workflow 数
- test runner 数
が増え始めると、
runner 差分対応が workflow 側へ散らばり始めた。
さらに formatter 側で：
- failureMessage の形式差異
- assertion 配列位置
- duration の持ち方
- skipped test の扱い
などを吸収し始めると、
「表示責務なのに runner JSON 構造を知っている」
状態になり、
責務分離が崩れ始めた。
特に CI 系ツールは、
後から：
- runner
- formatter
- reporter
- output format
が増えやすい。
そのため：
runner 差分は parser 層で閉じ込める
設計に切り替えた。
parser 層で差分を吸収する設計にした
そこで今回は、
Jest JSON
↓
Jest Parser
↓
NormalizedTestResult
↓
Formatter
という構造にした。
Vitest も同じ。
Vitest JSON
↓
Vitest Parser
↓
NormalizedTestResult
↓
Formatter
つまり：
runner 差分は parser 層で閉じ込める
方針にした。
共通型へ正規化する
formatter 側では、
- Jest
- Vitest
を意識しない。
共通型だけを見る。
例えば：
export interface NormalizedTestResult {
total: number;
passed: number;
failed: number;
skipped: number;
runtimeMs: number | null;
failedAssertions: FailedAssertion[];
}
こうしておくと、
- formatter
- GitHub Summary
- console preview
などを runner 非依存で扱える。
これは後々かなり効いた。
formatter は「表示責務だけ」に集中させる
formatter 側では：
- どの runner か
- JSON 構造がどうか
は一切知らない。
受け取るのは：
NormalizedTestResult
のみ。
結果として：
- parser
- formatter
- coverage
- CLI
を疎結合にできた。
特に CI 系ツールは、
「責務を混ぜない」ことがかなり重要だと思っている。
--format auto で runner を自動判定
CLI では：
--format auto
を指定できる。
内部では JSON 構造を見て：
- Jest
- Vitest
を自動判定している。
例えば：
testResults が存在 → Jest
numTotalTestSuites が存在 → Jest
のような特徴を見る。
利用側としては：
「runner ごとの差を意識しなくていい」
のでかなり楽になった。
Coverage Summary も Markdown 化する
さらに：
coverage-summary.json
も読み取り可能にした。
例えば：
| Type | Coverage |
|---|---|
| Lines | 91% |
| Functions | 88% |
| Branches | 84% |
のような表を Step Summary へ出せる。
CI ログへ coverage 数値を埋め込むより、
Summary の方が圧倒的に見やすい。
Failed Test は <details> で折りたたむ
失敗テストを全部展開すると、
Summary が巨大化する。
そこで：
<details>
<summary>Failed Tests</summary>
</details>
を使って折りたたむようにした。
さらに：
- 最大20件まで
- failure message を整形
- path を短縮
などを行っている。
CI Summary は、
「全部出す」より：
「必要な情報を短く出す」
方が重要だった。
ローカル実行時は console preview を出す
GitHub Actions 以外では、
$GITHUB_STEP_SUMMARY
が存在しない。
その場合は：
if (process.env['GITHUB_STEP_SUMMARY']) {
fs.appendFileSync(process.env['GITHUB_STEP_SUMMARY'], `${markdown}\n`);
} else {
console.log(markdown);
}
として、
標準出力へ Markdown preview を出すようにした。
これによって：
- ローカル確認
- formatter デバッグ
- snapshot 更新
などがやりやすくなった。
CLI としても API としても使えるようにした
今回のツールは：
- CLI
- TypeScript API
両方で使えるようにしている。
例えば将来的には：
- custom formatter
- Slack 通知
- PR comment
- 独自 reporter
などへも流用しやすい。
CI ツールは、
「CLIだけ」に閉じると拡張性が低くなりやすい。
fixture ベースで parser をテストした
JSON parser 系は、
fixture ベースがかなり相性良かった。
例えば：
__tests__/fixtures/
へ：
- Jest JSON
- Vitest JSON
- coverage-summary.json
を置き、
__tests__/parsers/
で parser の結果を検証している。
特に：
- runner version 差異
- optional field
- failure shape
などを固定しやすい。
CLI ツールほど、
fixture test が重要だと感じた。
今後やりたいこと
今後は：
- GitHub annotations 対応
- flaky test 集計
- trend 可視化
- junit xml support
- custom formatter plugin
などもやってみたい。
特に：
「CI をただのログ置き場ではなく、観測しやすい品質基盤にする」
方向へ伸ばしていきたいと思っている。
CI は、
単なるログ置き場ではなく、
「品質状態を短時間で観測できる場所」
であるべきだと思っている。
特に repository 数や workflow 数が増え始めると、
- jq を workflow ごとに書く
- formatter 実装が散らばる
- runner 差分対応が各所へ漏れる
状態はかなり辛くなる。
今回の CLI は、
そういった CI 可観測性の負債を減らすために作った。
今後も：
- flaky test
- trend 可視化
- annotations
- test analytics
などを含め、
「CI を品質基盤として扱う」
方向へ伸ばしていきたい。