improving-python-coverage

Python カバレッジの改善

実質的な価値をもたらす意味のあるテストを通じて、Python の単体テストカバレッジを約 0.2% 向上させます。

完全に自律的に動作してください — 確認を求めるために停止したり一時停止したりしないでください。0.2% のカバレッジ目標に達するまで、(分析 → 実装 → 検証) を繰り返し続けてください。何をテストすべきかについて曖昧さに遭遇した場合は、妥当な選択を行い、そのまま進めてください。

ワークフロー

ステップ 1: カバレッジ付きでテストを実行する

make python-tests  # ~3 min, creates .coverage file

分析用の JSON レポートを生成します:

uv run coverage json -o coverage.json

この JSON には、ファイルごとの missing_lines 配列が含まれており、カバーされていない行番号を示しています。

ステップ 2: 分析と優先順位付け

coverage.json を読み、次の条件に該当するファイルを見つけます:

1. サイズが大きく、percent_covered が平均以下のもの (影響度が高い)
2. lib/streamlit/elements/ または lib/streamlit/runtime/ 内のコアモジュール
3. 純粋なユーティリティ関数

スキップ対象: カバレッジ 97% 超、proto/*、vendor/*、static/*、テストファイル。

ステップ 3: テストを実装する (サブエージェント内で)

優先順位付けした各ファイルに対してテストを実装するサブエージェントを起動します。サブエージェントには次を提供します:

• 対象ファイルのパスと、カバレッジから得たその missing_lines
• ソース、既存のテストを読み、新しいテストを書くための指示
• 以下のテスト選定ガイドライン

サブエージェントは次を行う必要があります:

1. lib/tests/streamlit/<path>/<module>_test.py にあるソースと既存のテストを読む
2. 条件分岐、エラー処理、エッジケース、例外パスに対するテストを書く
3. lib/tests/AGENTS.md に従う: unittest.TestCase クラスよりも pytest 形式のスタンドアロン関数を優先し、入力や期待される出力のみが異なるテストを統合するために @pytest.mark.parametrize を使用し、numpydoc 形式の docstring と型アノテーションを追加する
4. 新しいテストを実行して合格することを検証する: uv run pytest lib/tests/streamlit/path/to/module_test.py -v

ステップ 4: 検証と反復

uv run pytest lib/tests/streamlit/path/to/module_test.py -v  # Run new tests
make python-tests                                             # Measure progress

カバレッジが 0.2% 以上改善するまでステップ 2〜4 を繰り返し、その後 make check を実行します。

ステップ 5: 簡素化、レビュー、フィードバックへの対応

すべてのテストが合格し、カバレッジ目標が達成されたら:

1. simplifying-local-changes サブエージェントを実行して、コード変更をクリーンアップして簡素化します。完了を待ちます。
2. reviewing-local-changes サブエージェントを実行して、変更をレビューします。完了を待ち、レビュー出力を読みます。
3. レビューのフィードバックに対応します: 各推奨事項について、妥当でコード品質を向上させる場合は実装し、該当しない場合や過剰な設計になる場合は簡潔な理由を添えてスキップします。
4. /checking-changes を実行して、変更後もすべてが合格することを検証します。

テストの選定

テストすべき: 条件ロジック、エラー処理、エッジケース (None、空、ゼロ、最大値)、公開 API 関数、複雑な分岐。

テストすべきでない: 単純なアクセサ、protobuf、実装の詳細、すでに十分にカバーされているコード。

カバレッジ除外: 本当にテストを必要としないコードには # pragma: no cover を控えめに使用します。常に理由を含めてください (例: # pragma: no cover - defensive):

• CI で実行できないプラットフォーム固有の分岐 (# pragma: no cover - platform-specific)
• 決して実行されるべきでない防御的コード (# pragma: no cover - defensive)
• 抽象メソッドのスタブやプロトコル定義 (# pragma: no cover - abstract)

統合テストの依存関係: pyproject.toml の [dependency-groups] にある integration に記載されているパッケージ (例: pydantic、sympy、polars、sqlalchemy) は、通常の単体テストではなく統合テストのためにのみインストールされます。これらのパッケージを使用するテストを書く場合:

• モジュールのトップレベルではなく、テスト関数の内部でインポートします
• テストに @pytest.mark.require_integration マーカーを追加します
• これにより、統合テスト環境外で実行されたときにテストが適切にスキップされます

テストファイルの配置

lib/tests/streamlit/<package>/<module>_test.py は lib/streamlit/<package>/<module>.py に対応します

注意事項

• カバレッジの数値よりも品質を優先する - 実際のバグを検出できないテストはスキップしてください

• 目標は lib/tests/AGENTS.md に基づくカバレッジ 95% 以上です

• テストを実装した後は /checking-changes を使用してください

• 外部ライブラリ（データベースコネクタ、オプションの依存関係など）に関連する一部のコードパスは、pytest.mark.require_integration でマークされた統合テストですでにカバーされています。これらの統合テストは、make python-tests によるカバレッジの数値には含まれていません。未カバーの行を分析する際は、ユニットテストや # pragma: no cover アノテーションを追加する前に、その未カバーのコードが統合テストで実行されているかどうかを確認してください。

• ローカルと CI のカバレッジの違い: バージョン固有（Python のバージョン、ライブラリのバージョン）のコードや、統合依存関係を使用するコードは、ローカルでは未カバーに見えても、CI ではテストされカバーされている場合があります。例:

  • Python のバージョン固有の分岐（例: if sys.version_info >= (3, 14)）は、一致する CI ジョブでのみ実行されます
  • ライブラリのバージョン固有のコード（例: pandas 2.x と 3.x の動作の違い）は、CI マトリックス全体でカバーされます
  • 統合依存関係のテスト（@pytest.mark.require_integration）は、それらのパッケージがインストールされた別の CI ジョブで実行されます

  そのようなコードに対してテストや # pragma: no cover を追加する前に、それが CI ですでに実行されているかどうかを確認してください。