python-testing-strategies

Python テスト戦略 — クイックリファレンス

セットアップ（重要）

pyproject.toml で asyncio_mode = "auto" を設定すると、マーカーなしで非同期テストを自動検出できます。（テストに @pytest.mark.asyncio を付ける場合は、デフォルトの「strict」モードでも動作します。）

conftest.py と pyproject.toml の完全なセットアップについては、examples.md を参照してください。

テストクライアント

httpx.AsyncClient と ASGITransport を使用してください。非同期テストで TestClient は使用しないでください。

クライアントフィクスチャのセットアップについては、examples.md を参照してください。

エンドポイントごとに必要なカバレッジ

1. 正常系（作成、読み取り、更新、削除）
2. 見つからない場合（404）
3. バリデーションエラー（422）
4. 認証失敗（401）— 保護されている場合
5. 論理削除 — 削除済みレコードが返されないこと

テストの命名

async def test_create_item():           # Happy path
async def test_create_item_missing_name():  # Validation
async def test_get_item_not_found():    # 404
async def test_get_item_soft_deleted(): # Soft delete

テストデータファクトリー

妥当なデフォルト値を持つシンプルなファクトリー関数を使用してください。テストで必要なものだけを上書きします。

ファクトリーのパターンについては、examples.md を参照してください。

テストの実行

pytest                           # All tests
pytest tests/test_items.py       # One file
pytest -k "test_create"          # By name pattern
pytest --tb=short -q             # Quiet output

注意点

• asyncio_mode = "auto" がないと、すべてが気付かないうちに動作しなくなります。 テストは成功したように見える（収集数が 0）か、無期限にハングします。非同期テストを書く前に、pyproject.toml に [tool.pytest.ini_options] asyncio_mode = "auto" を追加してください。これは「テストが実行されない」という問題の最大の原因です。

• TestClient と AsyncClient は互換性がありません。 TestClient（Starlette 製）は同期型で、処理をブロックします。AsyncClient（httpx 製）は非同期型で、イベントループを使用します。アプリで async def のルートと await を使用する場合は、ASGITransport と組み合わせて AsyncClient を使用する必要があります。TestClient を使うと同期的に実行されるため、非同期処理のバグが見えなくなることがあります。

• 適切にクリーンアップしないと、データベースの状態がテスト間で漏れます。 各テストにはクリーンなデータベースが必要です。テーブルを作成・削除する autouse=True のフィクスチャを使用するか、テスト間でテーブルを空にしてください。これを行わないと、テストの実行順に依存するようになり、CI でランダムな失敗が発生します。

• response.json() は、FastAPI のデフォルトではスネークケースを返します。 Pydantic モデルで alias_generator を使用している場合、JSON のキーは Python のフィールド名と異なることがあります。Python の属性名ではなく、実際の JSON のキーを必ず検証してください。

• 非同期テストで await を忘れると、分かりにくいエラーが発生します。 テスト出力に実際のデータではなく <coroutine object ...> が表示される場合は、await を忘れています。client.get()、client.post() などはすべて await する必要があります。