前言：把覆蓋率的開關打開，要花多少功夫？

「覆蓋率工具要裝、要設定門檻、CI 要改，聽起來是一個大工程吧？」

前幾天看到 phpunit.xml 裡明明有完整的覆蓋率報表設定，CI 卻用 --no-coverage 把它整個關掉。今天實際動手看看，把這個開關打開，到底要花多少功夫——先說結論：答案跟我一開始猜的不一樣。

提醒：以下所有操作都在我自己另外複製的一份本機暫存副本上做示範，不是對 omnipay-taiwan/omnipay-ecpay 這個真實公開套件的正式修改。這些改動如果真的要推回原套件，還是要由維護者評估後決定要不要送出 PR。

今日目標

• 知道 .github/workflows/tests.yml 的 CI 設定裡，其實早就準備好了覆蓋率工具
• 看懂 --no-coverage 這個開關,拿掉之後 CI 端幾乎不用改別的東西
• 理解本機環境跟 CI 環境在「裝覆蓋率工具」這件事上，難度可能完全不同
• 誠實面對一次「以為很難，其實卡在別的地方」的除錯過程

先查一個關鍵事實：CI 早就裝好覆蓋率驅動了

重新讀一次 .github/workflows/tests.yml 的 Setup PHP 步驟：

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}
    extensions: ${{ env.extensions }}
    tools: composer:v2
    coverage: xdebug

coverage: xdebug 這一行，代表 CI 用的 shivammathur/setup-php 這個 action，早就幫每一個 PHP 版本（7.1 到 8.3）都裝好了 Xdebug。也就是說，CI 環境從來就不缺覆蓋率驅動，缺的只是最後一步：把 --testdox --no-coverage 改成不帶 --no-coverage。

❌ 現在：明明裝了 Xdebug，卻在最後一步把覆蓋率關掉
- name: Execute tests
  run: vendor/bin/phpunit --testdox --no-coverage

✅ 改動：拿掉 --no-coverage，覆蓋率報表就會照 phpunit.xml 的設定產出
- name: Execute tests
  run: vendor/bin/phpunit --testdox

在 CI 這一端，這個改動小到不能再小——這也印證了昨天（第三部）反覆講的主題：這個套件不缺工具，缺的是「把工具真正打開」這個動作被排進待辦清單。

本機卻踢到鐵板：覆蓋率驅動沒那麼好裝

我原本想在自己的本機環境先跑一次覆蓋率報表，驗證拿掉 --no-coverage 之後真的會產出報表。結果：

$ vendor/bin/phpunit --coverage-text
...
There was 1 PHPUnit test runner warning:
1) No code coverage driver available

我的本機沒裝 Xdebug 或 pcov。試著用 pecl install pcov 補裝，又卡在另一個問題：

fatal error: 'pcre2.h' file not found
make: *** [pcov.lo] Error 1

編譯 pcov 需要系統先裝好 pcre2 的開發用標頭檔，我的本機環境沒有。這不是 omnipay-ecpay 這個套件的問題，是我自己本機環境缺一塊系統相依套件——但這個小插曲反而是這篇最有價值的發現：「覆蓋率工具沒被打開」這件事，原因可能因環境而完全不同。在 CI 上，工具早就裝好了，只是一行指令的選擇；在某些本機開發環境上，光是把驅動裝起來就可能卡在系統層級的相依問題，跟套件本身的程式碼一點關係都沒有。

❌ vs ✅：兩種「沒有覆蓋率」的原因,不能用同一套話術解釋

❌ 籠統地說
「這個套件沒有覆蓋率，因為維護者沒有重視測試品質。」

✅ 分開來看
CI 端：驅動早就裝好了（coverage: xdebug），只差一個指令選項——這是「選擇」問題。
本機端：驅動可能因為系統環境缺依賴而裝不起來——這是「環境」問題,不代表開發者不重視覆蓋率。

在下結論說『某個防線沒有被啟用』之前，先查清楚卡住的到底是意願、是流程、還是純粹的環境相依問題——這三種原因需要的解法完全不一樣，混為一談只會讓你把力氣花在錯的地方。

今日思考題

你的專案裡有沒有「工具裝設起來比想像中更困難」的經驗？回想一次你排查很久,最後發現卡點只是一個系統相依套件而不是程式邏輯的往事。

今日重點回顧

• CI 的 Setup PHP 步驟早就用 coverage: xdebug 裝好覆蓋率驅動，--no-coverage 是最後一步刻意加上的選項
• 在 CI 上打開覆蓋率報表，理論上只需要拿掉一個指令參數
• 本機環境嘗試裝 pcov 時，因為系統缺少 pcre2.h 而失敗——覆蓋率驅動的取得難度因環境而異
• 判斷「品質防線為什麼沒開」時，要先分清楚是意願問題、流程問題，還是環境相依問題

明日預告

明天處理另一個「設定了但沒接進 CI」的工具：check-style（PSR2 風格檢查）。跟覆蓋率不一樣的是，這個工具一旦接進 CI，馬上會踢到已知存在的 8 個真實錯誤——要接進去,就得先做一個選擇。