docs(python): Enhance documentation for Python testing strategies (#306)

YadaYuki · web-flow · commit 3abc42cd02fd · 2025-03-03T10:06:19.000+09:00
## What - SSIA ## CHECKS ⚠️ Please make sure you are aware of the following. - [ ] **The changes in this PR doesn't have private information
diff --git a/document/06-testing.en.md b/document/06-testing.en.md
@@ -233,6 +233,97 @@ func TestSayHelloWithTime(t *testing.T) {
 
 This demonstrates writing code with testing in mind.
 
+### Python
+
+# Python Testing Strategies
+
+**:book: Reference**
+
+(EN)[pytest: helps you write better programs — pytest documentation](https://docs.pytest.org/en/stable/)
+(EN)pytest fixtures: explicit, modular, scalable — pytest documentation
+(EN)Parametrizing fixtures and test functions — pytest documentation
+
+While Python has the standard unittest library built-in for testing, the **pytest** library is widely used to write more flexible and readable tests. pytest comes with a simple API and powerful features, and can be easily installed with `pip install pytest`. You can run tests with the `$ pytest` command.
+
+In Python, you can use the `pytest.mark.parametrize` decorator to describe multiple test cases together. Let's write a test for the say_hello function:
+
+```python
+# hello.py
+def say_hello(name=""):
+    if name:
+        return f"Hello, {name}!"
+    return "Hello!"
+
+# test_hello.py
+import pytest
+from hello import say_hello
+
+@pytest.mark.parametrize("name, expected",[
+    ("Alice", "Hello, Alice!"),
+    ("", "Hello!"),
+]
+)
+def test_say_hello(name, expected):
+    got = say_hello(name)
+
+    # Check if the expected return value and the actual value are the same, and display an error if they differ
+    assert got == expected, f"unexpected result of say_hello: want={expected}, got={got}"
+```
+
+The need to consider argument design with testing in mind is common to both Python and Go. Let's consider modifying the `say_hello` implementation to change the greeting based on the time of day:
+
+```python
+from datetime import datetime
+
+def say_hello(name):
+    now = datetime.now() # Directly depends on the current time, making it difficult to test
+    current_hour = now.hour
+
+    if 6 <= current_hour < 10:
+        return f"Good morning, {name}!"
+    if 10 <= current_hour < 18:
+        return f"Hello, {name}!"
+    return f"Good evening, {name}!"
+```
+
+This function is difficult to test because it directly depends on the current time. To test each time period, you would need to run the test at that specific time.
+
+To make it more testable, we can rewrite the function as follows:
+
+```python
+# Improved code (more testable design)
+from datetime import datetime
+
+def say_hello(name, now=None):
+    if now is None:
+        now = datetime.now()
+    
+    current_hour = now.hour
+
+    if 6 <= current_hour < 10:
+        return f"Good morning, {name}!"
+    if 10 <= current_hour < 18:
+        return f"Hello, {name}!"
+    return f"Good evening, {name}!"
+```
+
+Now we can specify the current time as an argument. By setting None as the default value, we can still omit the now parameter in normal usage.
+
+```python
+import pytest
+from datetime import datetime
+from greetings import say_hello
+
+@pytest.mark.parametrize("name, now, expected", [
+    ("Alice", datetime(2024, 1, 1, 9, 0, 0), "Good morning, Alice!"),
+    ("Bob", datetime(2024, 1, 1, 12, 0, 0), "Hello, Bob!"),
+    ("Charlie", datetime(2024, 1, 1, 20, 0, 0), "Good evening, Charlie!"),
+])
+def test_say_hello_simple(name, now, expected):
+    got = say_hello(name, now)
+    assert got == expected, f"unexpected result of say_hello: want={expected}, got={got}"
+```
+
 ## 1. Writing Tests for the Item Listing API
 
 Let's write tests for basic functionality, specifically testing item registration requests.
@@ -251,8 +342,11 @@ Let's write test cases for this.
 - What does this test verify?
 - What's the difference between `t.Error()` and `t.Fatal()`?
 
-### Python
-TBD
+### Python (Read Only)
+
+Python testing is implemented in [`main_test.py`](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py).
+
+Unlike the Go API implementation, in Python API implementation using the FastAPI framework, developers do not need to implement HTTP Request parsing themselves. Therefore, no additional implementation is required in this chapter, but you should review the test code to deepen your understanding.
 
 ## 2. Writing Tests for the Hello Handler
 
@@ -283,7 +377,16 @@ Once you have the logic figured out, implement it.
 
 ### Python
 
-TBD
+- (En)[FastAPI > Learn > Tutorial - User Guide / Testing](https://fastapi.tiangolo.com/tutorial/testing/)
+
+In Python, we use FastAPI's `testclient.TestClient` to verify that the handler function `hello` works correctly. Let's edit the test function [test_hello](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L53) that's already provided and write a test.
+
+As with Go, let's implement the test code with the following considerations in mind:
+
+- What do you want to test with this handler?
+- How can you verify that it behaves correctly?
+
+For implementing the test, you may refer to the [official FastAPI documentation](https://fastapi.tiangolo.com/tutorial/testing/#testclient).
 
 ## 3. Writing Tests Using Mocks
 
@@ -311,9 +414,24 @@ Let's test both successful and failed persistence scenarios using mocks.
 - Consider the benefits of using interfaces to satisfy mocks
 - Think about the pros and cons of using mocks
 
-### Python
+### Python (Read Only)
 
-TBD
+**:book: Reference**
+
+- (EN) [pytest-mock](https://github.com/pytest-dev/pytest-mock)
+- (EN) [unittest.mock --- introduction](https://docs.python.org/3.13/library/unittest.mock-examples.html#)
+
+For Python mock libraries, there are several options including the built-in standard `unittest.mock` and pytest's `pytest-mock`. Mocks become necessary when the process being tested depends on external tools or objects, such as in the following cases:
+
+- Mocking database connections to test user authentication logic without connecting to an actual database.
+- Mocking HTTP API clients to test weather forecast retrieval functions without actual network communication.
+- Mocking the file system to test logging functionality without actual file operations.
+
+In our case, we could consider implementing a test like the first example mentioned: "mocking database connections." However, the Build Python API implementation is very simple, and setting up classes like ItemRepository for mock testing would unnecessarily complicate the implementation.
+
+Since sufficient verification can be done with the test code implemented in the chapter "4. Writing tests using actual databases," and because it would contradict Python's language philosophy of "simplicity" and "explicitness," **we have omitted Python implementations using mocks from this teaching material**.
+
+However, in actual development environments where applications become more complex, there are many cases where tests using mocks are implemented in Python as well. If you're interested, take a look at the explanation of mock testing in the Go section, or review Python test implementations using mocks that are introduced on the internet.
 
 ## 4. Writing Tests Using Real Databases
 
@@ -332,7 +450,17 @@ After performing database operations, we need to verify the database state match
 
 ### Python
 
-TBD
+Let's write a test in Python using a test database (sqlite3). Uncomment the two places in [main_test.py](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py) that say "`STEP 6-4: uncomment this test setup`". ([first location](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L9-L42)/[second location](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L60-L84))
+
+The `db_connection` function creates and sets up a new test database using sqlite3 before the test, and deletes the test database after the test is completed.
+
+The `test_add_item_e2e` function tests the item addition functionality by sending a POST request to the API endpoint (`/items/`). This function runs with parameterized test cases (valid and invalid data). The test verifies:
+
+1. Whether the response status code matches the expected value
+2. For non-error cases, whether the response body contains a "message"
+3. Whether the data was correctly saved in the database (matching name and category)
+
+What's particularly important is that it tests end-to-end using an actual database (for testing) rather than mocks, which verifies the functionality in a way that's closer to the actual environment.
 
 ## Next
 
diff --git a/document/06-testing.ja.md b/document/06-testing.ja.md
@@ -233,6 +233,97 @@ func TestSayHelloWithTime(t *testing.T) {
 
 このようにして、テストのことも意識したコードをかけると良いですね。
 
+### Python
+
+Pythonにおけるテスト戦略
+**:book: Reference**
+
+(EN)[pytest: helps you write better programs — pytest documentation](https://docs.pytest.org/en/stable/)
+(EN)pytest fixtures: explicit, modular, scalable — pytest documentation
+(EN)Parametrizing fixtures and test functions — pytest documentation
+
+Pythonにはtest用のライブラリとして標準搭載されているunittestがありますが、より柔軟で可読性の高いテストを書くために**pytest**というライブラリが広く利用されています。pytestはシンプルなAPIと強力な機能を備えており、`pip install pytest`で簡単にインストールできます。`$ pytest`コマンドでテストを実行することができます。
+
+
+Pythonでは`pytest.mark.parametrize`デコレータを使って複数のテストケースをまとめて記述できます。say_hello関数のテストを書いてみましょう。
+
+```python
+# hello.py
+def say_hello(name=""):
+    if name:
+        return f"Hello, {name}!"
+    return "Hello!"
+
+# test_hello.py
+import pytest
+from hello import say_hello
+
+@pytest.mark.parametrize("name, expected",[
+    ("Alice", "Hello, Alice!"),
+    ("", "Hello!"),
+]
+)
+def test_say_hello(name, expected):
+    got = say_hello(name)
+
+    # 期待する返り値と実際に得た値が同じか確認した上で, 期待する返り値と実際に得た値が異なる場合は、エラーを表示
+    assert got == expected, f"unexpected result of say_hello: want={expected}, got={got}"
+```
+
+テストを想定して、引数の設計を考える必要があるという点はPythonもGoと共通です。`say_hello`の実装を時間に応じて挨拶を変えるように変更することを想定します。
+
+```python
+from datetime import datetime
+
+def say_hello(name):
+    now = datetime.now() # 現在時刻に直接依存しているため、テストしにくい
+    current_hour = now.hour
+
+    if 6 <= current_hour < 10:
+        return f"Good morning, {name}!"
+    if 10 <= current_hour < 18:
+        return f"Hello, {name}!"
+    return f"Good evening, {name}!"
+```
+
+この関数は現在時刻に直接依存しているため、テストが難しい設計です。各時間帯をテストするためには、実際にその時間にテストを実行する必要があります。
+
+テストしやすくするために、関数を次のように書き換えます：
+
+```python
+# 改善されたコード（テストしやすい設計）
+from datetime import datetime
+
+def say_hello(name, now=None):
+    if now is None:
+        now = datetime.now()
+
+    current_hour = now.hour
+
+    if 6 <= current_hour < 10:
+        return f"Good morning, {name}!"
+    if 10 <= current_hour < 18:
+        return f"Hello, {name}!"
+    return f"Good evening, {name}!"
+```
+
+これで現在時刻を引数として指定できるようになりました。デフォルト値としてNoneを設定することで、通常の使用ではnowを省略することもできます。
+
+```python
+import pytest
+from datetime import datetime
+from greetings import say_hello
+
+@pytest.mark.parametrize("name, now, expected", [
+    ("Alice", datetime(2024, 1, 1, 9, 0, 0), "Good morning, Alice!"),
+    ("Bob", datetime(2024, 1, 1, 12, 0, 0), "Hello, Bob!"),
+    ("Charlie", datetime(2024, 1, 1, 20, 0, 0), "Good evening, Charlie!"),
+])
+def test_say_hello_simple(name, now, expected):
+    got = say_hello(name, now)
+    assert got == expected, f"unexpected result of say_hello: want={expected}, got={got}"
+```
+
 ## 1. 出品APIのテストを書く
 基礎的な機能のテストである、アイテム登録のためのリクエストのテストを書いてみましょう。
 
@@ -250,8 +341,12 @@ func TestSayHelloWithTime(t *testing.T) {
 - このテストは何を検証しているでしょうか？
 - `t.Error()` と `t.Fatal()` には、どのような違いがあるでしょうか？
 
-### Python
-TBD
+### Python(Read Only)
+
+Pythonのテストは[`main_test.py`](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py)に実装されています。
+
+GoのAPI実装と異なり、FastAPIというフレームワークを活用したPythonのAPI実装ではHTTP RequestをParseする処理を開発者で実装する必要がありません。そのため、本章で追加の実装は必要ありませんが、テストコードに目を通し、理解を深めておきましょう。
+
 
 ## 2. Hello Handlerのテストを書く
 ハンドラのテストを書いてみましょう。
@@ -281,7 +376,16 @@ Goでは、 `httptest` と呼ばれるハンドラをテストするためのラ
 
 ### Python
 
-TBD
+- (JA)[FastAPI > チュートリアル > ユーザーガイド / テスト](https://fastapi.tiangolo.com/ja/tutorial/testing/)
+
+Pythonでは、FastAPIが提供する`testclient.TestClient`を用いて、ハンドラとなる`hello`が正しく動作するかどうかを検証します。すでに用意されているテスト用の関数の[test_hello](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L53)を編集して、テストを書いてみましょう。
+
+Goと同じように以下のことを意識しながら、テストコードを実装してみましょう。
+
+- このハンドラでテストしたいのは何でしょうか？
+- それが正しい振る舞いをしていることはどのようにして確認できるでしょうか？
+
+テストの実装には、[FastAPIの公式document](https://fastapi.tiangolo.com/ja/tutorial/testing/#testclient)を参考にしてみてください。
 
 ## 3. モックを用いたテストを書く
 モックを用いたテストを書いてみましょう。
@@ -309,7 +413,23 @@ Goには様々なモックライブラリがありますが、今回は `gomock`
 - モックを利用するメリットとデメリットについて考えてみましょう
 
 ### Python
-TBD
+
+**:book: Reference**
+
+- (EN) [pytest-mock](https://github.com/pytest-dev/pytest-mock)
+- (JA) [unittest.mock --- 入門](https://docs.python.org/ja/3.13/library/unittest.mock-examples.html#)
+
+Pythonのmock用のライブラリとしては標準搭載された`unittest.mock`やpytestが提供する`pytest-mock`等の選択肢が存在します。モックが必要になるケースとしては、テスト対象となる処理が外部的なツールやオブジェクトに依存する場合、例えば以下のようなケースが挙げられます。
+
+- データベース接続をモックして、実際のDBに接続せずにユーザー認証ロジックをテストする。
+- HTTP APIクライアントをモックして、実際のネットワーク通信なしで天気予報取得関数をテストする。
+- ファイルシステムをモックして、実際のファイル操作なしでログ出力機能をテストする。
+
+今回の場合、例の一番最初にあげた「データベース接続をモックする」というテストの実装が考えられます。しかし、BuildのPythonによるAPI実装は非常にシンプルなもので、モックしたテストを書くために、ItemRepositoryのようなクラスを設けることは必要以上に実装を複雑にしてしまいます。
+
+「4. 実際のデータベースを用いたテストを書く」という章で実装するテストコードで十分な検証ができる上に、Pythonの「シンプルさ」と「明示的であること」を重視する言語哲学にも反すると考え、**今回の教材からはmockを用いたpythonの実装を省いています**
+
+ただし、実際の開発現場のように、アプリケーションが複雑化した場合はmockを用いたテストの実装をPythonでも実施するケースが多いです。興味があるという方は、Goの方のmockを用いたテストの説明に目を通してみたり、インターネット上で紹介されているmockを用いたpythonのテスト実装に目を通してみましょう。
 
 ## 4. 実際のデータベースを用いたテストを書く
 STEP 6-3におけるモックを実際のデータベースに置き換えたテストを書いてみましょう。
@@ -325,7 +445,19 @@ Goでは、テスト用にデータベース用のファイルを作成して、
 - それが正しい振る舞いをしていることはどのようにして確認できるでしょうか？
 
 ### Python
-TBD
+
+Pythonで、テスト用のデータベース(sqlite3)を用いたテストを書いていきましょう。[main_test.py]()の「`STEP 6-4: uncomment this test setup`」という記載がある二カ所をコメントアウトしてください。([一カ所目](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L9-L42)/[二カ所目](https://github.com/mercari-build/mercari-build-training/blob/main/python/main_test.py#L60-L84))
+
+
+`db_connection`関数で、テスト前にはsqlite3を用いたテスト用のdbの新規作成とセットアップを行い、テストの終了後にはテスト用のdbを削除する処理を行なっています。
+
+`test_add_item_e2e`では、APIのエンドポイント（`/items/`）に対してPOSTリクエストを送信し、アイテム追加機能をテストしています。この関数は複数のテストケース（有効なデータと無効なデータ）をパラメータ化して実行します。テストでは以下を検証します：
+
+1. レスポンスのステータスコードが期待値と一致するか
+2. エラーでない場合は、レスポンスボディに「message」が含まれているか
+3. データベースに正しくデータが保存されたか（名前とカテゴリが一致するか）
+
+特に重要なのは、モックではなく実際のデータベース（テスト用）を使用してエンドツーエンドでテストすることで、実際の環境に近い形で機能を検証している点です。
 
 ## Next
 
diff --git a/python/main_test.py b/python/main_test.py
@@ -16,6 +16,7 @@
 #     finally:
 #         conn.close()
 
+# app.dependency_overrides[get_db] = override_get_db
 
 # @pytest.fixture(autouse=True)
 # def db_connection():
@@ -39,8 +40,6 @@
 #     if test_db.exists():
 #         test_db.unlink() # Remove the file
 
-# app.dependency_overrides[get_db] = override_get_db
-
 client = TestClient(app)
 
 
