Go Test Coverage -coverpkg Flag

概念概覽

問題根因

核心知識

問題根因

go test ./... 預設只統計 被測 package 內部 的執行路徑，跨 package 呼叫不計入。結果是覆蓋率數字看起來高，但實際有效覆蓋遠低於顯示值。

修正方式

# 錯誤（預設行為，數字虛高）
go test ./...

# 正確（取得真實跨 package 覆蓋率）
go test -coverpkg=./... ./...

-coverpkg=./... 告訴 Go 工具鏈：無論哪個 package 觸發執行，都要統計 所有 package 的覆蓋情況。

應用場景

這在有明確分層架構的後端專案特別重要——例如 modules/dungeon 呼叫 pkg/idempotency，如果不加此旗標，idempotency 被實際執行的路徑不會被計入覆蓋率。

經驗教訓

• CI 看到的覆蓋率數字在未加 -coverpkg 時是誤導性的，應優先修正量測工具再評估補測優先級

• 安全關鍵 package（如 pkg/middleware）若覆蓋率虛高，風險更大

常見陷阱

• 覆蓋率從虛高數字修正後會大幅下降，需提前與團隊溝通預期，避免誤判為「覆蓋率退步」

最佳實踐

• CI pipeline 加入 -coverpkg=./... 作為標準旗標

• 修正量測方式後，重新評估各 package 覆蓋率的真實狀況再排優先級

相關概念

• Argo Events Ephemeral Pod JIT Test Architecture
• Go Middleware Chain Ordering
• Jenkins Pipeline Silent Failure
• JIT Test File Lifecycle Management
• MkDocs Knowledge Graph Enhancement
• Testcontainers Custom PostgreSQL Image

來源 Sessions

日期	Session	貢獻摘要

| 2026-03-24 | cc0870e9-96f8-44f2-8716-4d11484f8a36 | 確認 CI 未加 -coverpkg 旗標會造成跨 package 覆蓋率虛高，並給出正確修正方式 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-03-24