pytest-cov 完全ガイド: Pythonコードカバレッジ測定の決定版 🐍✅

Pythonでテストを書く際、そのテストがコードのどれだけの範囲をカバーしているかを知ることは、ソフトウェアの品質を保証する上で非常に重要です。pytest-cov は、人気のテストフレームワーク pytest と連携し、コードカバレッジ測定を簡単かつ強力に実現するプラグインです。

この記事では、pytest-cov の基本的な使い方から設定、高度な活用法、CI/CDパイプラインへの組み込みまで、網羅的に解説します。これを読めば、あなたもカバレッジ測定マスターになれるはずです！ 💪

pytest-cov は、Coverage.py というPythonの標準的なカバレッジ測定ライブラリを、pytest から簡単に利用できるようにするためのプラグインです。Coverage.py単体で使用するのに比べ、以下のような利点があります。

• 簡単な統合: pytest コマンドにオプションを追加するだけでカバレッジ測定を実行できます。
• サブプロセスサポート: テスト中にサブプロセスを生成した場合でも、そのカバレッジを自動で測定します。
• xdistサポート: pytest-xdist を用いたテストの並列実行時でも、正確なカバレッジレポートを生成できます。
• 一貫した動作: pytest 本来の挙動（特に sys.path の扱い）を維持したままカバレッジを測定できます。

要するに、pytest ユーザーにとって、カバレッジ測定をより手軽に、かつ高機能に行うための必須ツールと言えるでしょう。

内部的には Coverage.py を利用しているため、Coverage.py の豊富な機能（設定ファイルによるカスタマイズなど）も活用できます。

pytest-cov のインストールは pip を使って簡単に行えます。

pip install pytest-cov

pytest 本体もまだインストールしていない場合は、一緒にインストールしましょう。

pip install pytest pytest-cov

テストの並列実行機能を提供する pytest-xdist と連携する場合は、こちらもインストールしておくと良いでしょう。

pip install pytest-xdist

注意: 過去の非常に古いバージョン (2.0より前) からアップグレードする場合、古い設定ファイル (init_cov_core.pth) が残っている可能性があるため、手動で削除する必要があるかもしれません。

最も基本的な使い方は、pytest コマンド実行時に --cov オプションを追加することです。このオプションに、カバレッジを測定したいPythonパッケージ名またはディレクトリパスを指定します。

例えば、my_project というパッケージのカバレッジを測定し、テストコードが tests/ ディレクトリにある場合は、以下のように実行します。

pytest --cov=my_project tests/

実行すると、テスト結果の後に、ターミナル上にシンプルなカバレッジレポートが表示されます。

============================= test session starts ==============================
platform linux -- Python 3.10.12, pytest-8.0.0, pluggy-1.4.0
rootdir: /path/to/your/project
plugins: cov-5.0.0
collected 3 items

tests/test_module.py ...                                                 [100%]

----------- coverage: platform linux, python 3.10.12-final-0 -----------
Name                 Stmts   Miss  Cover
----------------------------------------
my_project/__init__.py     1      0   100%
my_project/core.py        15      2    87%
my_project/utils.py        8      0   100%
----------------------------------------
TOTAL                   24      2    92%
============================== 3 passed in 0.10s ===============================

このレポートでは、各ファイルごとのステートメント数 (Stmts)、実行されなかったステートメント数 (Miss)、そしてカバレッジ率 (Cover) が表示されます。

複数のパッケージやディレクトリを指定することも可能です。

pytest --cov=my_project --cov=another_module tests/

--cov オプションに値を指定せず、単に --cov とだけ記述することもできます。この場合、どのソースを測定対象とするかは、後述する設定ファイルで指定する必要があります。

毎回コマンドラインオプションを指定するのは手間がかかりますし、より詳細な設定を行いたい場合もあります。そのような場合は、設定ファイルを利用するのが便利です。pytest-cov は Coverage.py の設定ファイルシステムを利用しており、主に以下のファイルが認識されます。

• .coveragerc (Coverage.py の伝統的な設定ファイル)
• pyproject.toml (推奨されるモダンな設定ファイル)
• pytest.ini
• setup.cfg
• tox.ini

ここでは、現代的なPythonプロジェクトでよく使われる pyproject.toml と、依然として広く使われている pytest.ini での設定例を中心に紹介します。

4.1. pyproject.toml での設定

pyproject.toml ファイルでは、[tool.pytest.ini_options] テーブルと [tool.coverage.run], [tool.coverage.report], [tool.coverage.html] などのテーブルを使って設定を記述します。

[tool.pytest.ini_options]
# pytest自体のオプション (例: 詳細表示)
addopts = "-v --cov=src --cov-report=term-missing --cov-report=html"
# テストファイルがあるディレクトリ
testpaths = [
    "tests",
]
# テストファイル名のパターン
python_files = "test_*.py"

[tool.coverage.run]
# カバレッジ測定対象のソースディレクトリ (addoptsの--covと重複しても良いが、こちらで管理する方が推奨される場合もある)
source = ["src"]
# ブランチカバレッジを有効にするか
branch = true
# 設定ファイルを指定する場合 (通常は不要だが、.coveragercを明示的に使いたい場合など)
# cov_config = ".coveragerc"
# 並列実行時のデータファイル名のサフィックス (pytest-covが管理するため通常不要)
# parallel = true

[tool.coverage.report]
# カバレッジから除外する行のパターン
exclude_lines = [
    # デバッグ時のみ実行されるコードを除外
    "pragma: no cover",
    # 型チェック時のみインポートされるものを除外
    "if TYPE_CHECKING:",
    # 標準的なmainガードを除外
    "if __name__ == \"__main__\":",
    # 抽象メソッドを除外
    "raise NotImplementedError",
    # 単純なpass文を除外
    "^\s*pass\s*$",
]
# 測定から除外するファイル/ディレクトリのパターン (glob形式)
omit = [
    "src/vendor/*", # サードパーティライブラリなど
    "tests/*",      # テストコード自体はカバレッジに含めない場合
    "*/__main__.py", # 実行用スクリプトなど
]
# カバレッジ率がこの値を下回ったらエラーにする (%)
fail_under = 90
# レポート表示時の数値の精度 (小数点以下の桁数)
precision = 2
# カバレッジが100%のファイルをレポートから除外するか
# skip_covered = true

[tool.coverage.html]
# HTMLレポートの出力ディレクトリ
directory = "htmlcov"

[tool.coverage.xml]
# XMLレポートの出力ファイル名
output = "coverage.xml"

このように設定しておけば、コマンドラインで pytest と実行するだけで、pyproject.toml に記述された --cov や --cov-report などのオプションが自動的に適用されます。

4.2. pytest.ini での設定

pytest.ini を使用する場合も同様の設定が可能です。[pytest] セクションと、Coverage.py の設定を記述するための [coverage:run], [coverage:report], [coverage:html] などのセクションを使用します。

[pytest]
addopts = -v --cov=src --cov-report=term-missing --cov-report=html
testpaths = tests
python_files = test_*.py

[coverage:run]
source = src
branch = true
omit =
    src/vendor/*
    tests/*
    */__main__.py

[coverage:report]
exclude_lines =
    pragma: no cover
    if TYPE_CHECKING:
    if __name__ == "__main__":
    raise NotImplementedError
    ^\s*pass\s*$
fail_under = 90
precision = 2
# skip_covered = True

[coverage:html]
directory = htmlcov

[coverage:xml]
output = coverage.xml

4.3. 主要な設定オプション解説

pytest-cov は様々な形式のレポートを出力できます。目的に応じて適切なレポートを活用しましょう。

5.1. ターミナルレポート (term, term-missing)

最も手軽に確認できるのがターミナルへの出力です。--cov-report=term (デフォルト) または --cov-report=term-missing を指定します。

• term: ファイルごとのカバレッジ率をシンプルに表示します。
• term-missing: term の情報に加え、カバレッジされていない行番号 (Miss 列) も表示します。テストが不足している箇所を素早く特定するのに役立ちます。
• term:skip-covered: 100%カバーされたファイルの表示を省略し、問題のあるファイルに注目しやすくします。

# term-missing の例
pytest --cov=my_project --cov-report=term-missing tests/

----------- coverage: platform linux, python 3.10.12-final-0 -----------
Name                 Stmts   Miss  Cover   Missing
--------------------------------------------------
my_project/__init__.py     1      0   100%
my_project/core.py        15      2    87%   35-36  <-- この行が実行されていない
my_project/utils.py        8      0   100%
--------------------------------------------------
TOTAL                   24      2    92%

5.2. HTMLレポート (html)

--cov-report=html を指定すると、詳細なHTML形式のレポートが生成されます (デフォルトでは htmlcov/ ディレクトリ)。ブラウザで htmlcov/index.html を開くと、以下のような情報をインタラクティブに確認できます。

• プロジェクト全体のカバレッジサマリー
• ファイルごとのカバレッジ率一覧
• 各ソースコードの行ごとのカバレッジ状況 (色分け表示)
  • 緑色: 実行された行
  • 赤色: 実行されなかった行
  • 灰色: 除外された行 (コメント、pragma: no cover など)
• ブランチカバレッジが有効な場合、条件分岐のどの経路が実行されたか/されなかったか

HTMLレポートは、カバレッジ状況を最も詳細に分析するのに適しています。どのコードパスがテストでカバーされていないかを視覚的に把握できます。

5.3. XMLレポート (xml)

--cov-report=xml を指定すると、XML形式のレポート (デフォルトでは coverage.xml) が生成されます。この形式は、Codecov や Coveralls といった外部のカバレッジレポートサービスや、JenkinsなどのCIツールと連携する際によく利用されます。

CI/CDパイプラインでカバレッジ結果を記録・追跡する場合に必須となる形式です。

5.4. その他のレポート形式

• JSONレポート (json): 機械処理しやすいJSON形式でカバレッジデータを出力します。独自のツールでカバレッジ情報を処理したい場合に便利です。
• LCOVレポート (lcov): LCOV形式のレポートを生成します。主にC/C++などのカバレッジツールで使われる形式ですが、一部のフロントエンドツールなどでも利用されることがあります。
• Annotateレポート (annotate): 各ソースファイルのコピーを作成し、実行されなかった行に !、実行されなかったブランチに > を付けてアノテーションします。テキストベースで簡易的に未カバー箇所を確認したい場合に利用できます。

6.1. ブランチカバレッジ (--cov-branch)

単に行が実行されたかだけでなく、if文やwhileループなどの条件分岐が網羅されているかを測定するのがブランチカバレッジです。--cov-branch オプションまたは設定ファイルで branch = true を指定することで有効になります。

レポートには、実行された分岐の数と総分岐数、そしてブランチカバレッジ率が表示されるようになります。HTMLレポートでは、分岐が部分的にしか実行されていない箇所が黄色などでハイライトされます。

# myapp.py
def check_value(x):
    if x > 10:
        print("Large")  # 分岐1
    elif x > 0:
        print("Medium") # 分岐2
    else:
        print("Small")  # 分岐3

# test_myapp.py
from myapp import check_value

def test_check_value_large():
    # x > 10 のケースのみテスト
    check_value(15)

pytest --cov=myapp --cov-branch tests/

----------- coverage: platform linux, python 3.10.12-final-0 -----------
Name          Stmts   Miss Branch BrPart  Cover   Missing
--------------------------------------------------------
myapp.py          6      2      6      4    50%   5-8, 7->8
--------------------------------------------------------
TOTAL             6      2      6      4    50%

この例では、Stmts (ステートメント) は4/6 (67%) カバーされていますが、Branch (分岐) は6つのうち2つ (33%) しか実行されていないことがわかります (BrPart は部分的に実行された分岐の数)。Missing 列には、実行されなかった行 (5-8) と、実行されなかった分岐 (7->8 は elif x > 0: がFalseになった場合の分岐、つまり else: 節への分岐) が示されています。

ブランチカバレッジを有効にすることで、テストケースの抜け漏れをより効果的に発見できます。

6.2. 特定の行やブロックをカバレッジから除外 (# pragma: no cover)

デバッグ用のコード、OS依存のコード、あるいはテストが困難な防御的プログラミングなど、意図的にカバレッジ測定から除外したい行やコードブロックが存在する場合があります。そのような場合は、該当する行の末尾に # pragma: no cover というコメントを追加します。

import sys

def platform_specific_code():
    if sys.platform == "win32":
        print("Windows specific code")
    elif sys.platform == "darwin":
        print("MacOS specific code")
    else:
        # このブロックはテストしない (またはテスト環境がない)
        print("Other OS")  # pragma: no cover

def debug_only_function():  # pragma: no cover
    # この関数全体をデバッグ時のみ使用し、カバレッジに含めない
    import pdb; pdb.set_trace()

def main_logic(data):
    if not data:
        # 防御的プログラミング: 通常は起こりえないが念のため
        raise ValueError("Data should not be empty") # pragma: no cover
    # ... main logic ...
    return True

このコメントが付与された行は、カバレッジ計算 (Stmts や Miss) の対象から除外されます。HTMLレポートでは灰色で表示されます。

設定ファイルの exclude_lines オプションを使えば、正規表現で特定のパターンに一致する行 (例: raise NotImplementedError) を一括で除外することも可能です。

6.3. 並列テスト (pytest-xdist) との連携

pytest-xdist を使用してテストを並列実行する場合でも、pytest-cov は特別な設定なしで正しくカバレッジを測定し、結果を結合してくれます。これは pytest-cov の大きな利点の一つです。

pip install pytest-xdist
pytest --cov=my_project -n auto tests/  # -n auto でCPUコア数に応じて並列実行

各ワーカープロセスで測定されたカバレッジデータが、テスト終了時に自動的にマージされ、単一のレポートとして出力されます。

注意: 並列テストを行う場合、各ワーカーノードにも pytest-cov がインストールされている必要があります。

6.4. サブプロセスのカバレッジ測定

テストコードが外部コマンドや別のPythonスクリプトをサブプロセスとして実行する場合、pytest-cov はそのサブプロセス内のコードカバレッジも自動的に測定します。

これも特別な設定は通常不要ですが、以下の条件を満たす必要があります:

• サブプロセスで使用されるPython環境にも pytest-cov がインストールされていること。
• サブプロセスが通常のPythonサイト初期化プロセス (site-packagesの読み込みなど) を行うこと。
• 親プロセスからサブプロセスへ環境変数が正しく渡されること (通常は問題ありません)。

これにより、コマンドラインツールやマルチプロセスアプリケーションのテストでも、正確なカバレッジを得ることができます。

6.5. テストが実行されなかったファイルの検出

--cov オプションや設定ファイルの source で指定した範囲内に、一度も実行されなかった (したがってカバレッジ0%の) Pythonファイルが存在する場合、デフォルトではレポートに含まれないことがあります。これらのファイルもレポートに含めるには、coverage run の --include オプションに相当する設定が必要ですが、pytest-cov では --cov で指定したパスが暗黙的に --include の役割も果たすため、通常は問題なく検出されます。

もし意図したファイルがレポートに表示されない場合は、--cov や設定ファイルの source, omit の指定が正しいか確認してください。

pytest-cov はCI/CDパイプラインに簡単に組み込むことができ、コード品質の自動チェックに役立ちます。

7.1. カバレッジ閾値によるビルド失敗 (--cov-fail-under)

--cov-fail-under=MIN オプション (または設定ファイルの fail_under) を使うと、全体のカバレッジ率が MIN % を下回った場合に pytest がエラー終了 (非ゼロの終了コード) するようになります。これにより、CIパイプラインはカバレッジが低い場合にビルドを失敗させることができます。

# 例: カバレッジが90%未満ならCIで失敗させる
pytest --cov=src --cov-report=term --cov-fail-under=90 tests/

これは、コード品質の基準を維持するための強力なメカニズムです。

7.2. GitHub Actions での利用例

以下は、GitHub Actions のワークフローで pytest-cov を実行し、XMLレポートを生成する簡単な例です。

name: Python application test with coverage

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11"]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pytest pytest-cov
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
        # Poetry や PDM を使っている場合はそれに合わせたインストールコマンド
    - name: Run tests with coverage
      run: |
        # pyproject.toml などで設定済みなら単に pytest でも良い
        pytest --cov=src --cov-report=xml --cov-report=term-missing --cov-fail-under=90 tests/
    # - name: Upload coverage reports to Codecov
    #   uses: codecov/codecov-action@v4
    #   with:
    #     token: ${{ secrets.CODECOV_TOKEN }} # Codecovにアップロードする場合
    #     files: ./coverage.xml # 生成されたXMLレポートを指定
    #     fail_ci_if_error: true

このワークフローでは、テストを実行し、XML形式のカバレッジレポート (coverage.xml) を生成します。オプションで、Codecovなどの外部サービスにレポートをアップロードするステップを追加できます。

7.3. GitLab CI での利用例

GitLab CI の .gitlab-ci.yml でも同様の設定が可能です。

image: python:3.10

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip
    - venv/

before_script:
  - python -V  # Print out python version for debugging
  - pip install virtualenv
  - virtualenv venv
  - source venv/bin/activate
  - pip install pytest pytest-cov -r requirements.txt

test:
  script:
    # pyproject.toml などで設定済みなら単に pytest でも良い
    - pytest --cov=src --cov-report=term-missing --cov-report=xml:coverage.xml --cov-fail-under=90 tests/
  coverage: '/^TOTAL.+?(\d+\%)$/' # GitLabの機能でカバレッジ率を抽出
  artifacts:
    when: always
    reports:
      junit: report.xml # pytest-junitxml などでJUnitレポートも生成する場合
      coverage_report:
        coverage_format: cobertura # GitLab 13.7以降でCobertura形式をサポート
        path: coverage.xml

GitLab CI では、coverage キーワードで正規表現を指定することで、ジョブのログからカバレッジ率を抽出し、マージリクエストなどで表示できます。また、artifacts:reports:coverage_report を使うことで、XMLレポート (Cobertura形式) をアップロードし、差分カバレッジなどを表示させることも可能です。

7.4. Codecov / Coveralls との連携

Codecov や Coveralls は、カバレッジレポートをホスティングし、経時的な変化やプルリクエストでのカバレッジ差分などを可視化してくれるサービスです。pytest-cov で生成したXMLレポートやJSONレポートをこれらのサービスにアップロードすることで、より高度なカバレッジ分析と品質管理が可能になります。

多くのCIサービスには、これらのサービスへのレポートアップロードを簡単に行うための連携機能や公式アクション/Orbなどが用意されています。

# GitHub Actions で Codecov Uploader を使う例
- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v4
  with:
    token: ${{ secrets.CODECOV_TOKEN }}
    file: ./coverage.xml # pytest-cov で生成したXMLファイル
    flags: unittests # オプション: テストの種類を示すフラグ
    fail_ci_if_error: true # アップロード失敗時にCIを失敗させるか

Q: カバレッジが思ったように計測されない、レポートにファイルが表示されない

A: 以下の点を確認してください。

• --cov=PATH や設定ファイルの source 指定が正しいか？測定したいソースコードのルートパッケージやディレクトリを正確に指定する必要があります。
• 設定ファイルの omit で意図せず除外されていないか？
• テスト対象のPythonファイルが、テスト実行時に一度もインポートまたは実行されていない可能性はないか？ (カバレッジ0%のファイルも表示されるはずですが、念のため)
• サブプロセスを測定したい場合、サブプロセスの環境に pytest-cov がインストールされているか？
• 非常に古い pytest-cov や coverage.py を使用していないか？

Q: 設定ファイル (.coveragerc, pyproject.toml など) の設定が反映されない

A: 以下の点を確認してください。

• 設定ファイルの名前と場所は正しいか？ (プロジェクトルートにあるか？)
• 設定ファイルの構文は正しいか？ (TOMLやINIの文法ミスはないか？)
• 複数の設定ファイル (例: .coveragerc と pyproject.toml) が存在し、意図しない方が優先されていないか？ 必要であれば --cov-config で明示的に指定してみてください。
• コマンドラインオプションで設定を上書きしていないか？ (例: --cov-report=term を指定すると、設定ファイルのHTMLレポート指定が無効になる)
• 特定のオプションは pytest-cov が制御するため、.coveragerc で設定しても無視される場合があります (例: parallel, data_file, source (--cov=... 指定時))。

Q: coverage run -m pytest と pytest --cov=... の違いは？

A: どちらも Coverage.py を使ってカバレッジを測定しますが、pytest --cov=... (pytest-cov プラグイン) を使う方が一般的に推奨されます。主な違いは以下の通りです。

• xdistサポート: pytest-cov は pytest-xdist による並列テストのカバレッジ測定をシームレスにサポートします。coverage run では追加の設定が必要です。
• サブプロセスサポート: pytest-cov はサブプロセスのカバレッジ測定をより簡単に扱えます。
• sys.path の一貫性: coverage run -m pytest で実行すると、カレントワーキングディレクトリが sys.path に追加されるため、通常の pytest 実行時と挙動が異なる場合があります。pytest-cov はこの違いを生じさせません。
• 設定の統合: pytest-cov は pytest の設定ファイル (pytest.ini, pyproject.toml) とより親和性が高いです。

特別な理由がない限り、pytest ユーザーは pytest-cov を使用するのが良いでしょう。

Q: テストコード自体もカバレッジに含まれてしまう

A: 設定ファイルの omit オプションを使って、テストコードが格納されているディレクトリ (例: tests/*) を除外するように指定してください。

# pyproject.toml
[tool.coverage.report]
omit = [
    "tests/*",
    # 他の除外パターン...
]

pytest-cov は、Pythonプロジェクトにおけるコードカバレッジ測定を大幅に簡略化し、強化する強力なツールです。基本的な使い方から設定ファイルの活用、ブランチカバレッジ、CI/CD連携まで、その機能は多岐にわたります。

この記事で紹介した内容を活用し、あなたのプロジェクトでもカバレッジ測定を導入・改善してみてください。テストカバレッジを継続的に監視し、向上させることは、コードの品質を高め、バグを未然に防ぎ、自信を持ってソフトウェアをリリースするための重要なステップです。

さあ、pytest-cov を使って、より堅牢なPythonコードを目指しましょう！ ✨