Pythonテストカバレッジ計測の決定版！ coverage.py を徹底解説

ソフトウェア開発において、テストは品質を担保するための重要なプロセスです。しかし、書いたテストがコードのどの部分をどれだけ網羅しているかを把握するのは容易ではありません。そこで登場するのがテストカバレッジという指標です。

テストカバレッジとは、テストコードが本番コードのどの程度の範囲を実行したかを示す割合のことです。カバレッジを計測することで、テストが不十分な箇所を特定し、テストの質を高めることができます。これにより、バグの早期発見やコードの信頼性向上につながります。

Pythonにおけるテストカバレッジ計測ツールとして、デファクトスタンダードとなっているのが coverage.py です。coverage.pyは、Pythonプログラムの実行を監視し、どのコード行が実行され、どのコード行が実行されなかったかを記録・分析します。非常に多機能でありながら使いやすく、多くのPythonプロジェクトで採用されています。

このブログでは、coverage.pyの基本的な使い方から、設定ファイルによるカスタマイズ、ブランチカバレッジなどの詳細な機能、テストフレームワークやCI/CDツールとの連携まで、網羅的に解説していきます。coverage.pyを使いこなして、あなたのPythonプロジェクトのテスト品質をさらに向上させましょう！

インストール

coverage.py のインストールは pip を使って簡単に行えます。

pip install coverage

インストールが完了したら、バージョンを確認してみましょう。

coverage --version

2025年3月30日にはバージョン7.8.0がリリースされています。常に最新の情報を確認し、必要に応じてアップデートしましょう。

コマンドラインでの実行

coverage.py の基本的な使い方は、コマンドラインから実行することです。主に以下の3つのコマンドを使用します。

1. coverage run <your_script.py>: 指定したPythonスクリプトを実行し、カバレッジデータを収集します。収集されたデータは、デフォルトでは .coverage という名前のファイルに保存されます。
2. coverage report: 収集したカバレッジデータをもとに、結果をコンソールに表示します。各ファイルの実行された行数（Stmts）、実行されなかった行数（Miss）、カバレッジ率（Cover）などが表示されます。-m オプションを付けると、実行されなかった行番号（Missing）も表示されます。
3. coverage html: 収集したカバレッジデータをもとに、HTML形式のレポートを生成します。デフォルトでは htmlcov というディレクトリが作成され、その中にレポートファイルが生成されます。htmlcov/index.html をブラウザで開くと、詳細なレポートを確認できます。

簡単なサンプルコードとテストコード

例として、簡単な関数とそのテストコードを用意します。

my_module.py:

def add(x, y): if not isinstance(x, (int, float)): raise TypeError("x must be a number") if not isinstance(y, (int, float)): raise TypeError("y must be a number") return x + y
def subtract(x, y): # この関数はテストで呼ばれない return x - y

test_my_module.py (unittestを使用):

import unittest
import my_module
class TestMyModule(unittest.TestCase): def test_add_normal(self): self.assertEqual(my_module.add(1, 2), 3) self.assertEqual(my_module.add(1.5, 2.5), 4.0) def test_add_error(self): with self.assertRaises(TypeError): my_module.add("a", 1) with self.assertRaises(TypeError): my_module.add(1, "b")
if __name__ == '__main__': unittest.main()

実行とレポート確認

まず、coverage run を使ってテストを実行し、カバレッジデータを収集します。unittestを実行する場合は -m unittest オプションを使用します。

coverage run -m unittest test_my_module.py

これにより、.coverage ファイルが生成されます。

次に、コンソールでレポートを確認します。

coverage report -m

出力例:

Name Stmts Miss Cover Missing
------------------------------------------------
my_module.py 7 1 86% 10
test_my_module.py 11 0 100%
------------------------------------------------
TOTAL 18 1 94%

my_module.py のカバレッジが86%で、10行目 (subtract関数の中身) が実行されていないことがわかります。

最後に、HTMLレポートを生成します。

coverage html

htmlcov/index.html をブラウザで開くと、より視覚的で詳細なレポートを確認できます。各ファイルをクリックすると、ソースコード上で実行された行（緑）、実行されなかった行（赤）、除外された行（灰色）などが色分けされて表示されます。

コマンドラインオプションでも多くの設定が可能ですが、設定項目が多くなるとコマンドが長くなり、管理が煩雑になります。そこで便利なのが設定ファイル .coveragerc です。

.coveragerc は INI 形式のファイルで、プロジェクトのルートディレクトリに配置するのが一般的です。pyproject.toml や setup.cfg, tox.ini 内に設定を記述することも可能です。

以下は .coveragerc の基本的な構造と主要な設定項目です。

[run]
; 実行時の設定
source = my_project/ ; カバレッジ計測対象のソースディレクトリ/パッケージを指定 (複数指定可)
omit = ; 計測から除外するファイル/ディレクトリのパターン (ワイルドカード使用可) */tests/* */migrations/* my_project/settings.py
include = ; 計測対象に含めるファイル/ディレクトリのパターン (sourceと併用) my_project/core/*
branch = True ; ブランチカバレッジを有効にする (True/False)
concurrency = multiprocessing ; 並列実行ライブラリを指定 (multiprocessing, thread, gevent, eventlet, greenlet)
parallel = True ; 並列モードを有効にし、データファイル名にサフィックスを付与
data_file = .coverage ; カバレッジデータファイルのベース名
context = ; 静的なコンテキストラベルを設定
[report]
; レポート生成時の設定 (coverage report, html, xml などで共通)
show_missing = True ; 未実行の行番号を表示する
ignore_errors = False ; ソースファイル読み込みエラーを無視する
precision = 0 ; カバレッジ率の小数点以下の桁数
fail_under = 80 ; 合計カバレッジが指定値を下回る場合に終了コード2で失敗させる
exclude_lines = ; 正規表現にマッチする行を除外する pragma: no cover raise NotImplementedError if __name__ == .__main__.:
partial_branches = ; 正規表現にマッチする行のブランチを部分ブランチとして扱う pragma: no branch if TYPE_CHECKING:
skip_covered = False ; 100%カバレッジのファイルをレポートからスキップする
sort = name ; レポートのソート順 (name, stmts, miss, branch, brpart, cover)
[html]
; HTMLレポート固有の設定
directory = htmlcov ; レポート出力ディレクトリ
title = My Project Coverage Report
show_contexts = False ; コンテキスト情報をHTMLレポートに表示する (True/False)
[xml]
; XMLレポート固有の設定 (Cobertura形式)
output = coverage.xml ; 出力ファイル名
package_depth = 2 ; パッケージ階層の深さ
[json]
; JSONレポート固有の設定
output = coverage.json ; 出力ファイル名
pretty_print = True ; 見やすくフォーマットする
; 他にも lcov, annotate などのセクションがあります

主要な設定項目解説

• [run] source: 計測対象のソースコードを指定します。ディレクトリやパッケージ名を指定でき、カンマ区切りまたは改行で複数指定可能です。これを指定することで、coverage.pyは指定された範囲内で実行されなかったファイルも検出し、レポートに含めることができます（0%カバレッジとして）。
• [run] omit / include: 計測対象から除外するファイルや、含めるファイルをパターンで指定します。omit はテストコード、設定ファイル、マイグレーションファイル、外部ライブラリなどを除外するのによく使われます。include は source で指定した範囲内で、さらに特定のファイル群のみを対象としたい場合に使用します。ファイルパターンはシェルのワイルドカード（*, ?）が利用できます。
• [run] branch: True に設定すると、ステートメントカバレッジに加えてブランチカバレッジも計測します。詳細は後述します。
• [report] exclude_lines: 特定のパターンにマッチする行をカバレッジ計測から除外します。pragma: no cover というコメントを書いた行を除外するのが一般的です。これにより、テストが困難または不要なコード（デバッグ用コード、抽象メソッド定義など）を意図的に除外できます。
• [report] fail_under: CI/CD 環境で役立つ設定です。全体のカバレッジ率が指定した閾値を下回った場合に、コマンドを失敗させることができます。これにより、カバレッジの低下を防ぐ強制力を導入できます。

ブランチカバレッジ (分岐網羅)

通常のカバレッジ（ステートメントカバレッジ）は、コードの各行が実行されたかどうかを計測します。しかし、if 文や while ループなどの条件分岐を持つコードでは、行が実行されただけでは不十分な場合があります。

ブランチカバレッジは、条件分岐の各経路（例えば if の True 側と False 側）が実行されたかどうかを計測します。これにより、条件分岐の網羅性をより厳密に評価できます。

.coveragerc で [run] branch = True を設定するか、コマンドラインで --branch オプションを付けることで有効になります。

coverage run --branch -m unittest test_my_module.py
coverage report -m

レポートには Branch (分岐の総数), BrPart (実行された部分分岐の数), BrCov (ブランチカバレッジ率) の列が追加され、Missing 列には実行されなかった分岐（例: 12->14 は12行目から14行目への分岐が実行されなかったことを示す）が表示されます。

ブランチカバレッジを100%にすることで、より信頼性の高いテストスイートを構築できます。

レポート形式

coverage.py は様々な形式でレポートを出力できます。

用途に応じて適切なレポート形式を選択しましょう。一般的には、ローカルでの確認には html、CI/CD連携には xml がよく使われます。

API経由での利用

coverage.py はコマンドラインだけでなく、Pythonコード内から直接 API を利用することも可能です。

import coverage
import unittest
# Coverageオブジェクトを作成 (設定ファイルも読み込まれる)
cov = coverage.Coverage(source=['my_module'])
# カバレッジ計測を開始
cov.start()
# ここでテスト対象のコードを実行 (例: unittestを実行)
# loader = unittest.TestLoader()
# suite = loader.discover('.')
# runner = unittest.TextTestRunner()
# runner.run(suite)
# または特定の関数を呼び出すなど
try: import my_module my_module.add(1, 2)
except Exception: pass # エラー処理
# カバレッジ計測を停止
cov.stop()
# カバレッジデータを保存
cov.save()
# レポートを生成 (例: HTMLレポート)
cov.html_report(directory='covhtml_from_api')
# 合計カバレッジ率を取得
total_coverage = cov.report()
print(f"Total coverage: {total_coverage:.2f}%")
# 他のレポート形式も生成可能
# cov.xml_report(outfile='coverage_api.xml')
# cov.json_report(outfile='coverage_api.json')

APIを利用することで、より複雑なテストシナリオや、独自のレポート生成、テストプロセスへの深い統合が可能になります。Coverage クラスのコンストラクタやメソッドで、コマンドラインや設定ファイルと同様のオプションを指定できます。

並列実行 (Concurrency)

multiprocessing や gevent などを使用してテストを並列実行する場合、各プロセス/スレッドで個別にカバレッジデータが収集されるため、そのままでは正確な全体のカバレッジが得られません。

coverage.py はこれに対応する機能を持っています。

1. 設定: .coveragerc の [run] セクションで concurrency に使用するライブラリ (multiprocessing, thread, gevent, eventlet, greenlet のいずれか、またはカンマ区切りで複数) を指定し、parallel = True を設定します。

   [run]
   concurrency = multiprocessing
   parallel = True

2. 実行: 通常通り coverage run ... を実行します。これにより、各プロセス/スレッドごとに .coverage.<hostname>.<pid>.<random> のようなサフィックス付きのデータファイルが複数生成されます。
3. 結合: coverage combine コマンドを実行して、生成された複数のデータファイルを1つの .coverage ファイルに結合します。

   coverage combine

   結合後は、通常通り coverage report や coverage html でレポートを生成できます。

この機能により、大規模なテストスイートの実行時間を短縮しつつ、正確なカバレッジ計測が可能になります。

コンテキスト (Context)

coverage.py 5.0 から導入された比較的新しい機能で、「どのテストがどのコード行を実行したか」を記録・分析できます。

静的コンテキスト: coverage run --context=<label> ... のように実行時にラベルを指定します。例えば、異なる種類のテスト（単体テスト、結合テストなど）を実行する際に、それぞれのコンテキストを設定できます。

動的コンテキスト: .coveragerc で [run] dynamic_context = test_function を設定すると、実行中のテスト関数名を自動的にコンテキストとして記録します (pytest や unittest との連携が必要です)。

[run]
dynamic_context = test_function

収集したコンテキスト情報は、coverage report --contexts=REGEX や coverage html --show-contexts で表示できます。HTMLレポートでは、各行がどのテスト（コンテキスト）によって実行されたかのリストが表示され、特定のテストがどのコードパスをカバーしているかを詳細に追跡するのに役立ちます。

これは、テストの冗長性の発見や、特定の機能変更が影響するテストの特定などに有効です。

coverage.py は主要な Python テストフレームワークとスムーズに連携できます。

pytest との連携 (pytest-cov)

pytest ユーザーにとって最も一般的な方法は、pytest-cov プラグインを使用することです。

1. インストール:

   pip install pytest-cov

2. 実行: pytest コマンドに --cov=<path> オプションを追加して実行します。<path> にはカバレッジを計測したいモジュールやディレクトリを指定します。

   pytest --cov=my_project tests/

   これにより、テスト実行後に自動的にカバレッジレポートがコンソールに出力されます。
3. レポート形式の指定: --cov-report オプションでレポート形式を指定できます。

   pytest --cov=my_project --cov-report=html tests/ # HTMLレポートを htmlcov/ に生成
   pytest --cov=my_project --cov-report=xml tests/ # XMLレポートを coverage.xml に生成

4. 設定ファイルの利用: .coveragerc ファイルがあれば、pytest-cov は自動的にその設定を読み込みます。例えば、.coveragerc で branch = True を設定しておけば、pytest --cov=... を実行するだけでブランチカバレッジが計測されます。--cov-config=.coveragerc で明示的に設定ファイルを指定することも可能です。
5. 閾値の設定: --cov-fail-under=<min> オプションで、カバレッジ率が指定値を下回った場合に pytest を失敗させることができます。

   pytest --cov=my_project --cov-fail-under=90 tests/

6. コンテキストの利用: --cov-context=test を指定すると、テスト関数名を動的コンテキストとして記録できます。

   pytest --cov=my_project --cov-context=test tests/
   coverage html --show-contexts # HTMLレポートでコンテキスト表示

pytest-cov を使うことで、pytest のエコシステム内でシームレスにカバレッジ計測を統合できます。

unittest との連携

標準ライブラリの unittest を使用している場合は、前述の基本的な使い方で示したように、coverage run -m unittest ... コマンドを使用します。

# テストファイルを実行
coverage run -m unittest test_my_module.py
# tests/ ディレクトリ以下のテストを自動検出して実行
coverage run -m unittest discover tests/
# レポート生成
coverage report -m
coverage html

.coveragerc ファイルで設定を管理するのが一般的です。

Django との連携

Django プロジェクトでは、manage.py test コマンドと組み合わせて coverage.py を使用します。

# coverage を通してテストを実行 (--source で計測対象を指定)
coverage run --source='.' manage.py test your_app
# レポート生成
coverage report
coverage html

.coveragerc で source や omit (マイグレーションファイルやテスト用ファイルを除外) を設定しておくと、コマンドがシンプルになります。

[run]
source = your_project, your_app
omit = */migrations/* */tests/* manage.py your_project/wsgi.py your_project/asgi.py your_project/settings.py

設定ファイルがあれば、以下のように実行できます。

coverage run manage.py test your_app
coverage report
coverage html

テストカバレッジは、継続的インテグレーション (CI) / 継続的デリバリー (CD) パイプラインに組み込むことで、その真価を発揮します。コードが変更されるたびに自動的にカバレッジを計測し、品質の低下を早期に検知できます。

基本的な組み込み

CI スクリプト (例: .github/workflows/ci.yml, .gitlab-ci.yml, Jenkinsfile) のテスト実行ステップで、coverage run と coverage report (または coverage xml) コマンドを実行します。

GitHub Actions の例:

name: Python CI
on: [push, pull_request]
jobs: build: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.9", "3.10", "3.11"] steps: - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install coverage pytest pytest-cov # テストとカバレッジツールをインストール - name: Run tests with coverage run: | pytest --cov=my_project --cov-report=xml # XMLレポートを出力 # 必要に応じて、ここでカバレッジレポートをアーティファクトとして保存したり、 # 外部サービスにアップロードしたりするステップを追加 # - name: Upload coverage reports to Codecov # uses: codecov/codecov-action@v3 # with: # token: ${{ secrets.CODECOV_TOKEN }} # Codecovのトークン（リポジトリ設定で登録） # files: ./coverage.xml # アップロードするレポートファイル # fail_ci_if_error: true

カバレッジレポートの活用

1. 閾値によるビルド失敗: coverage report --fail-under=<min> や pytest --cov-fail-under=<min> を使用して、カバレッジが一定の閾値を下回った場合にCIビルドを失敗させます。これにより、テストカバレッジの維持を強制できます。
2. レポートの保存 (Artifacts): CI/CDプラットフォームのアーティファクト機能を使って、生成されたHTMLレポートやXMLレポートを保存します。これにより、ビルド後にレポートを確認できます。
3. 外部サービスとの連携 (Codecov, Coveralls など):
   • CodecovやCoverallsのようなカバレッジレポートサービスを利用すると、カバレッジの推移をグラフで可視化したり、Pull Request (Merge Request) 上で変更されたコードのカバレッジ状況を表示したりできます。
   • これらのサービスは通常、CIで生成されたXMLレポート (Cobertura形式) をアップロードすることで連携します。
   • GitHub Actionsには、codecov/codecov-action のような専用のアクションが用意されており、簡単にレポートをアップロードできます。
   • GitLab CIでは、組み込みのテストカバレッジ可視化機能があり、artifacts:reports:coverage_report に Cobertura XML ファイルを指定することで、マージリクエストの差分ビューにカバレッジ情報を表示できます。

CI/CDパイプラインにカバレッジ計測を組み込み、レポートを可視化・活用することで、コード品質の継続的な監視と改善が可能になります。

よくある問題と対処法

• カバレッジが0%または非常に低い:
  • coverage run を使わずにテストを実行していませんか？ coverage を通して実行する必要があります。
  • .coveragerc の source 設定が正しいか確認してください。計測対象のディレクトリやパッケージが正しく指定されていないと、意図したファイルが計測されません。
  • omit 設定で誤って計測したいファイルを除外していませんか？ パターンを確認してください。
  • テスト自体が対象コードを実行していない可能性があります。テストケースを見直してください。
  • ファイル名やパスに特殊文字が含まれていると、スキップされる場合があります。
• テストファイル自体がレポートに含まれてしまう:
  • .coveragerc の omit 設定でテストファイル (例: */tests/*, test_*.py) を除外してください。
• ブランチカバレッジが期待通りにならない:
  • branch = True が有効になっているか確認してください。
  • 単純な if True: や while False: のような常に結果が決まっている分岐は、最適化により coverage.py が分岐として認識しない場合があります (バージョンによる挙動の違いあり)。
  • exclude_lines で pragma: no branch のようなコメントを使って、意図的に特定の分岐を計測対象外にできます。
• HTMLレポートでソースコードが表示されない:
  • レポート生成時に対象のソースファイルが見つからない可能性があります。coverage run と coverage html を実行するカレントディレクトリが適切か確認してください。
  • coverage combine を使用している場合、結合前のデータファイルが生成された環境と、結合・レポート生成を行う環境でパスが異なると問題が発生することがあります。[paths] セクションでパスのマッピングを設定する必要があるかもしれません。
• CoverageException: No data to report.:
  • coverage run でデータが収集されなかったか、収集されたデータファイル (.coverage) が見つからない場合に発生します。実行コマンドやカレントディレクトリを確認してください。
• CoverageWarning: Module X was never imported.:
  • source で指定したモジュールが、テスト実行中に一度も import されなかった場合に表示されます。不要な指定か、テストケースが不足している可能性があります。
• CoverageWarning: No lines detected in file Y:
  • ファイルは存在しますが、実行可能な Python コード行が検出されなかった場合に表示されます (例: 空の __init__.py)。通常は問題ありません。

パフォーマンスに関する注意点

カバレッジ計測は、Python のトレース機能を利用するため、通常のコード実行よりもオーバーヘッドが発生し、実行速度が低下します。特に大規模なプロジェクトや多数のテストを実行する場合、この影響は顕著になります。

• 計測対象を絞る: source, omit, include を適切に設定し、不要なコードの計測を避けることが最も重要です。特に、標準ライブラリやインストール済みのサードパーティライブラリは、デフォルトで除外されますが (cover_pylib=False)、意図せず計測対象に含まれないように注意しましょう。
• timid=True の検討: 特定の環境 (高度なメタプログラミングや他のトレースツールとの競合など) で問題が発生する場合、[run] timid = True を設定すると、低速ですがより安定したトレースメカニズムを使用します。通常は不要です。
• C拡張: coverage.py はパフォーマンス向上のために C 拡張を使用しています。インストール時に C コンパイラがあれば自動的にビルドされます。coverage --version で “with C extension” と表示されていれば有効です。
• 並列実行: 前述の通り、concurrency と parallel = True を利用してテストを並列化することで、全体の実行時間を短縮できます。
• 最新バージョンの利用: coverage.py は継続的に改善されています。新しいバージョンほどパフォーマンスが向上している可能性があるため、定期的にアップデートを検討しましょう。(例: Python 3.12+ の sys.monitoring を利用した実験的な高速化など)

coverage.py は、Python プロジェクトにおけるテストカバレッジ計測のための強力で不可欠なツールです。基本的な使い方から設定ファイルによるカスタマイズ、ブランチカバレッジ、テストフレームワークやCI/CDとの連携まで、その機能を活用することで、テストの網羅性を正確に把握し、コードの品質を効果的に向上させることができます。

主なポイントを振り返りましょう：

• coverage run でテストを実行しカバレッジデータを収集。
• coverage report や coverage html で結果を確認。HTMLレポートは視覚的に分かりやすい。
• .coveragerc で計測対象 (source) や除外設定 (omit, exclude_lines)、ブランチカバレッジ (branch=True) などを柔軟に設定可能。
• pytest (pytest-cov) や unittest、Django とスムーズに連携。
• CI/CD パイプラインに組み込み、--fail-under や外部サービス連携 (Codecovなど) で品質を継続的に監視。
• 並列実行 (concurrency, parallel=True, combine) やコンテキスト (context) などの高度な機能も提供。

テストカバレッジは万能薬ではありません。カバレッジ率が高いことが必ずしもバグがないことを保証するわけではありませんが、テストされていないコード領域を特定するための非常に有効な手段です。coverage.py を活用し、継続的にカバレッジを計測・改善していくことで、より堅牢で信頼性の高い Python アプリケーションを開発していく一助となれば幸いです。