python-tdd-with-uv

uv を使った Python の TDD

依存関係と環境を素早く管理できる uv を使い、テストファーストで Python コードを書きます。

プロジェクトのセットアップ

1. uv がインストールされていることを確認します：uv --version
2. プロジェクトに pyproject.toml がない場合は、初期化します：

   uv init
   

3. 開発用の依存関係として pytest を追加します：

   uv add --dev pytest pytest-cov
   

4. テストランナーが動作することを確認します：

   uv run pytest --co
   

TDD ワークフロー — 垂直スライス

小さなサイクルで作業します。一度に失敗するテストを複数書いてはいけません。

計画フェーズ

コードを書く前に、次の点を確認します：

1. どのインターフェースを変更する必要がありますか？（関数、クラス、API）
2. どの動作が最も重要ですか？（重要な経路を優先する）
3. テストしやすい設計にできますか？（依存関係を注入し、グローバル状態を避ける）

サイクル

RED   → Write ONE failing test for the next behavior
GREEN → Write the MINIMUM code to make it pass
REFACTOR → Clean up without changing behavior
REPEAT

ルール：

• 失敗するテストができる前に実装を書いてはいけません
• 一度に失敗するテストを複数書いてはいけません
• 変更するたびに uv run pytest を実行します
• テストでは実装の詳細ではなく、観測可能な動作を検証します
• モックはシステム境界（I/O、ネットワーク、時計）でのみ使用します

テストファイルの構成

# tests/test_<module>.py

class TestFeatureName:
    """Group related behaviors."""

    def test_does_expected_thing_when_given_input(self):
        result = function_under_test(input_value)
        assert result == expected

    def test_raises_when_given_invalid_input(self):
        with pytest.raises(ValueError):
            function_under_test(bad_input)

テストの実行

uv run pytest                      # all tests
uv run pytest tests/test_foo.py    # single file
uv run pytest -k "test_name"       # by name pattern
uv run pytest --cov=src            # with coverage
uv run pytest -x                   # stop on first failure

uv の基本

uv add <package>           # add dependency
uv add --dev <package>     # add dev dependency
uv remove <package>        # remove dependency
uv sync                    # sync environment from lockfile
uv run <command>           # run in managed environment
uv lock                    # regenerate lockfile

• コマンドの実行には必ず uv run を使います。仮想環境を手動で有効化してはいけません
• pyproject.toml と uv.lock の両方をコミットします

参考資料

• mattpocock/skills — TDD skill — 垂直スライス型 TDD の考え方
• nizos/tdd-guard — フックによる TDD の自動的な徹底
• s2005/uv-skill — uv のワークフローパターン