用 100% code coverage 讓自己設計品質好的軟體

-

前言

很多敘述都是說 100% code coverage 雖然可以達成，但是會花非常多時間，所以往往 project 的 code coverage 都設定在 80-90% 左右。

但這前提是 source code 非常亂的情況下，才是 true。

現在我習慣讓新 projects 達到 100% code coverage，並不會多花時間，反而減少了許多 bugs，而且整體上程式碼也變得非常好讀，甚至讓任何新人進來看都看得懂。

我用一個簡化的 python 例子來描述怎麼做到這件事。

100% 不合理的案例

現代化的軟體通常少不了與外部軟體的整合，所以我們可以設計一個簡單化的 application:

  1. 用 REST API 取得某個使用者的發文
  2. 把 raw data 轉成 application 內部 data
  3. 用一些邏輯去搜尋發文

就會寫出下面這樣的程式碼，看似簡單:


# complex_find.py
from dataclasses import dataclass

import requests


@dataclass(frozen=True)
class Post:
    id: int
    title: str
    body: str


def find_posts_with_keyword(user_id: int, keyword: str) -> list[Post]:
    # Get a list of posts with REST API
    base_url = "https://jsonplaceholder.typicode.com/posts"
    params: dict[str, int] = {"userId": user_id}
    response = requests.get(base_url, params)
    try:
        response.raise_for_status()
    except requests.HTTPError as e:
        raise RuntimeError(f"Failed to call API with params: {params}") from e

    # Filter posts with the keyword
    data_list = response.json()
    posts: list[Post] = []
    for data in data_list:
        if "id" not in data or "title" not in data or "body" not in data:
            raise ValueError(f"API data should contain 'id', 'title' and 'body': {data}")

        try:
            id = int(data["id"])
        except ValueError as e:
            raise ValueError(f"API data 'id' should be integer but got: {data['id']}") from e

        title = data["title"].strip()
        body = data["body"].strip()
        if keyword in title.lower() or keyword in body.lower():
            posts.append(Post(id=id, title=title, body=body))

    return posts


但在做 testing 的時候就會很痛苦，尤其是如果要達到 100% code coverage:


# tests/test_complex_find.py
import pytest
import requests
from pytest_mock import MockerFixture

from complex_find import find_posts_with_keyword


def test_find_posts_with_keyword() -> None:
    posts = find_posts_with_keyword(3, "quia")

    assert len(posts) == 5
    for post in posts:
        assert "quia" in post.title or "quia" in post.body


def test_find_posts_with_keyword_when_request_fails(mocker: MockerFixture) -> None:
    mock_response = mocker.create_autospec(requests.Response)
    mock_response.raise_for_status.side_effect = requests.HTTPError("fake error")
    mocker.patch.object(requests, "get", return_value=mock_response)

    with pytest.raises(RuntimeError, match="Failed to call API with params:"):
        find_posts_with_keyword(3, "quia")


def test_find_posts_with_keyword_when_required_fields_are_missing(
    mocker: MockerFixture,
) -> None:
    fake_data: list[dict[str, int]] = [{"id": 1}]

    mock_response = mocker.create_autospec(requests.Response)
    mock_response.json.return_value = fake_data
    mocker.patch.object(requests, "get", return_value=mock_response)

    with pytest.raises(
        ValueError, match="API data should contain 'id', 'title' and 'body':"
    ):
        find_posts_with_keyword(3, "quia")


def test_find_posts_with_keyword_when_id_is_not_integer(
    mocker: MockerFixture,
) -> None:
    fake_data: list[dict[str, str]] = [
        {"id": "x", "title": "some title", "body": "some body"}
    ]

    mock_response = mocker.create_autospec(requests.Response)
    mock_response.json.return_value = fake_data
    mocker.patch.object(requests, "get", return_value=mock_response)

    with pytest.raises(
        ValueError, match="API data 'id' should be integer but got: x"
    ):
        find_posts_with_keyword(3, "quia")

主要痛苦的原因:

  1. REST API 有點慢而且不穩定，為了每增加一行 error handling 的 coverage 就新增一個 test case 導致 project 在 CI/CD 的時候非常久，而且經常因為 REST API 的問題而 fail
  2. 為了讓特定 error handling 條件成真，需要用很多 mocking

最後的折衷就是退而求其次，可能 90% 就夠了，但你有發現上面的測試光是測 error handling 就花了 3 個 test cases 嗎? 反而最重要的 business logic 卻只有 1 個 test case。

就算沒有 100% code coverage，要新增 test cases 專門去測重要的東西時開發者也會猶豫，因為我們其實在測一個 "複雜" 的系統。

Clean code 版本

如果要達到 100% code coverage 要怎麼做? 在做過許多 projects 後我觀察到雖然有各種技巧，但通常最簡單又避不開的其實就是 clean code 說的:

把程式碼切小塊一點

這也是阻擋 100% code coverage 的主因，因為一個複雜的系統要怎麼切比較好牽扯到很多面向，和 clean architecture 裡面的 components 怎麼切有點像，例如說:

  • 程式碼的穩定性 (像是 REST API 不穩定，核心程式碼很穩定)
  • 程式碼修改的頻率 (像是有些規則因為使用者要求經常變動，但資料處理的部分卻不太變化)
  • 程式碼的 responsibility (例如取得資料和驗證資料是兩回事)

實務上也會因為一些奇怪的原因而把原本一個檔案切成好幾個，例如說:

  • 因為不確定使用者喜不喜歡一個小地方，先切出來變成 beta 功能
  • Linter 很討厭某個 third-party library 的語法，但這個 library 又太好用，只好切出來專屬於 library 的程式碼並把 file disable
  • 懷疑部分程式碼是 performance bottleneck 切出來做更詳細的測試

原因百百種，但切出來各做測試通常更容易達到 100% code coverage，其實同時間也解決了很多維護上的困擾。

以上面的例子而言，通常我會切成 3 塊:

  1. REST API
  2. Data validation
  3. Application logic

# api_client.py
import requests

from internal.validate import to_posts
from models.post import Post


def find_posts(user_id: int) -> list[Post]:
    base_url = "https://jsonplaceholder.typicode.com/posts"
    params: dict[str, int] = {"userId": user_id}

    response = requests.get(base_url, params)
    try:
        response.raise_for_status()
    except requests.HTTPError as e:
        raise RuntimeError(f"Failed to call API with params: {params}") from e

    data_list = response.json()
    return to_posts(data_list)


# internal/validate.py
from typing import Any

from models.post import Post


def to_posts(data_list: Any) -> list[Post]:
    posts: list[Post] = []
    for data in data_list:
        if "id" not in data or "title" not in data or "body" not in data:
            raise ValueError(
                f"API data should contain 'id', 'title' and 'body': {data}"
            )

        try:
            id = int(data["id"])
        except ValueError as e:
            raise ValueError(
                f"API data 'id' should be integer but got: {data['id']}"
            ) from e

        title = data["title"].strip()
        body = data["body"].strip()
        posts.append(Post(id=id, title=title, body=body))
    return posts


# search.py
from models.post import Post


def find_posts_by_keyword(posts: list[Post], keyword: str) -> list[Post]:
    return list(
        filter(lambda x: keyword in x.title.lower() or keyword in x.body.lower(), posts)
    )

在做 refactoring 之前我也沒料想到我一開始把 data validation 和 application logic 混在一起增加 bugs 的可能性，也增加維護上的困擾，例如某天我只想改 data validation 的部分卻要連 application logic 的 test cases 一起修改。

切成這三塊之後我們就可以看到其實最重要的 application logic 就凸顯出來了。其他 REST API 或 data validation 其實沒有那麼重要，而且也容易因為外部變動而跟著更改。

用切成小塊的程式碼後要達到 100% code coverage 就變得很簡單。


# tests/unit/test_api_client.py
import pytest
import requests
from pytest_mock import MockerFixture

from api_client import find_posts


def test_find_posts_with_successful_response(mocker: MockerFixture) -> None:
    mock_response = mocker.create_autospec(requests.Response)
    mock_response.json.return_value = [
        {"id": "1", "title": "some title", "body": "some body"}
    ]
    mocker.patch.object(requests, "get", return_value=mock_response)

    posts = find_posts(3)
    assert len(posts) > 0


def test_find_posts_with_failed_response(mocker: MockerFixture) -> None:
    mock_response = mocker.create_autospec(requests.Response)
    mock_response.raise_for_status.side_effect = requests.HTTPError("fake error")
    mocker.patch.object(requests, "get", return_value=mock_response)

    with pytest.raises(RuntimeError, match="Failed to call API with params:"):
        find_posts(3)


# tests/unit/internal/test_validate.py
import pytest

from internal.validate import to_posts
from models.post import Post


def test_to_posts_with_valid_data() -> None:
    data_list: list[dict[str, int | str]] = [
        {"id": 1, "title": "some title", "body": "some body"}
    ]
    posts = to_posts(data_list)
    assert posts == [Post(id=1, title="some title", body="some body")]


def test_to_posts_with_missing_fields() -> None:
    data_list: list[dict[str, int | str]] = [{"id": 1, "body": "some body"}]
    with pytest.raises(
        ValueError, match="API data should contain 'id', 'title' and 'body':"
    ):
        to_posts(data_list)


def test_to_posts_with_wrong_id_type() -> None:
    data_list: list[dict[str, int | str]] = [
        {"id": "x", "title": "some title", "body": "some body"}
    ]
    with pytest.raises(ValueError, match="API data 'id' should be integer but got: x"):
        to_posts(data_list)


# tests/unit/test_search.py
from models.post import Post
from search import find_posts_by_keyword


def test_find_posts_by_keyword_when_keyword_in_title_and_body() -> None:
    posts: list[Post] = [
        Post(id=1, title="some quia", body="quia some"),
        Post(id=2, title="something else", body="something else"),
    ]
    found_posts = find_posts_by_keyword(posts, "quia")

    assert found_posts == [posts[0]]


def test_find_posts_by_keyword_when_keyword_in_title_only() -> None:
    posts: list[Post] = [
        Post(id=1, title="some quia", body="x"),
        Post(id=2, title="something else", body="something else"),
    ]
    found_posts = find_posts_by_keyword(posts, "quia")

    assert found_posts == [posts[0]]


def test_find_posts_by_keyword_when_keyword_not_found() -> None:
    posts: list[Post] = [
        Post(id=1, title="x", body="x"),
        Post(id=2, title="something else", body="something else"),
    ]
    found_posts = find_posts_by_keyword(posts, "quia")

    assert found_posts == []

雖然程式碼看起來變多，但我們終於可以好好的測試最重要的核心邏輯了 (search) ! 每個 test file 都變得很清楚，要修改也變得容易許多。

而且因為我們把 REST API 完全 mock 掉，以上 unit testing 會變得又穩定又快，幾乎不會 fail。

但我們還是需要測試實際使用 REST API 的時機，因此我們可以用額外一組 integration test 來達成。


# tests/integration/test_app.py
from api_client import find_posts
from search import find_posts_by_keyword


def test_app() -> None:
    posts = find_posts(3)
    filtered_posts = find_posts_by_keyword(posts, "minus")

    assert len(filtered_posts) == 1
    assert "minus" not in filtered_posts[0].title
    assert "minus" in filtered_posts[0].body

可以看到 integration test 不用太複雜，因為目的只是驗證 API 可以用而已，我們就不需要額外在測其他 failure 的部分，除非 API 有提供這種功能。

切小塊 ≠ 小 function

我們切小塊的目的只是把一開始多面向的程式碼切成 "單一面向"，例如 REST API function 就真的只做 REST API，data validation 就只做 validation，不做其他的事。

但這不代表 function 就一定都差不多行數，因為每個面向都有自己要煩惱的事。

最簡單的例子就是一些條列式的規則處理，如果一個 function 在 "同個領域中" 根據 100 種規則輸出不同的資料，那代表至少有 100 行程式碼，但也沒必要說為了讓 function 變小一點而拆成好幾個小 functions。

100% ≠ 每行都測到

我們只想讓該測的地方 100%，不該測的應該就 0%。

該測的地方就是指對 project 重要的地方，哪怕沒測到任何一行，實際上有可能走到，就算機率再小，就是隱藏的 bug。

不該測的地方其實不少見，例如:

  • Interface (像是一整個 file 只有 Python Protocol)
  • Third-party 產生的 generated files (像是 Qt 的 moc)
  • 實驗性的功能，且預期頻繁修改 (生命極短暫)
這種不該測的就該直接把整個 file 從 coverage tool exclude 掉。

Best practices 自動出現

在達成 100% code coverage 後，一堆程式碼上的好習慣就自然被套用了，例如:

  • SRP (single responsibility principle)
  • DRY (don't repeat yourself)
  • KISS (keep it simple, stupid)
  • YAGNI (you ain't gonna need it)

通常每個 file 都只有 1~5 個 functions，都專心做一件事，達到 SRP。

在切檔案的時候通常就會把重複的部分切出來變成一個檔案，達到 DRY。

又因為切出來後我們用更多的 function names 來表示在做什麼，也不需要 comments，達到 KISS。

切出來後原本覺得會需要的東西，因為要專門寫他的 unit test 時就會思考到底有沒有必要，就算真的留著未來要刪除也很單純，達到 YAGNI。

結論

現代的 projects 通常是多面向、多方面整合的一堆程式碼的集合體，如何根據不同面向 (case-by-case) 切開複雜的程式碼，通常就已經邁向 100% code coverage 一大步。

100% code coverage 不僅讓自己重新思考系統的架構，也讓寫測試變得容易許多，提高維護性。

留言

發佈留言

此網誌的熱門文章

[試算表] 追蹤台股 Google Spreadsheet (未實現損益/已實現損益)

-
圖片
在 Dcard 上發了一篇文結果引起超多網友回應想要看試算表，我就來整理一下我追蹤台股用的 Google 試算表給大家。 這個試算表我目標是以 "簡單" 為主，底下我也會講解公式的運作原理，希望大家能以此試算表輕鬆擴充自己想要的功能。 功能 未實現損益 (Unrealized Gain/Loss 表) 不管同一支股票是不是有部分已經賣出，只要你還持有未賣出的股票這邊都看的到。 已實現損益 (Realized Profit/Loss 表) 我過去的績效如何? 在這個表一目了然。 未實現損益: 詳細資料 (Unrealized Stats 表) 我還持有多少股? 每股市值多少? 每股的成本是多少? 在這個表可以快速追蹤。 手機友善 (Mobile Friendly) 我為了在手機上也可以快速看我想看的資訊，把 "Unrealized Gain/Loss" 做成比較窄的版型。 只要下載 Google Sheets app 打開試算表就可以了。 Google Spreadsheet 連結 Google Drive 連結 Stock Tracking 使用方式 請先點 "檔案" -> "建立副本"，copy 一份試算表到你自己的 Google Drive 將 "Current Price" 表單中填上你想要追蹤的股票代號和名稱 將 "Transactions" 表單中刪除範例資料，但請務必留下第 2 列 (因為有公式)，然後慢慢往下填入你的資料 Step 1: 檔案 -> 建立副本 Step 2: 新增/刪除股票代號和名稱 (紅框圈起處)，灰色底欄位代表有公式 Step 3: 在 "Transactions" 表填入資料到白色底欄位 (紅框圈起處)，灰色底欄位代表要讓公式自動計算 未實現損益的正確算法 其實在發 Dcard 文之前我自己也像 另外一個表單 犯了同樣的錯誤，就是只有在股票全部賣光光 (持有 0 股) 後計算的未實現損益才會正確。還沒全部賣光怎麼辦? 難道就不顯示了嗎? 飲料的例子 只要股票中途賣出一部分，目前還持有部分股票的話，感覺計算就突然變得很複雜。但不用怕，我們來用飲料當作股票舉個超簡單的例子 (1 杯=1...
閱讀更多

互動式教學神經網路反向傳播 Interactive Computational Graph

-
圖片
成品 互動式網頁連結:  Interactive Computational Graph 微積分課經典的範例 df/dx sin(x) / x: 2 個 inputs, 1 個 output, 沒有 hidden layer 的 fully connected neural network: 為何要做這套工具 以前在學 machine learning 的時候覺得最難理解的部分就是 backpropagation，也就是神經網路到底是怎麼用數學來做訓練的。 我們知道神經網路就是長這樣子: Source: Wikipedia 但實際上每個 neuron (圓圈圈) 裡面有許多基本的數學運算，像是 sum 還有 activation function: Source:  Neural Networks and Machine Learning 當我們把所有東西綜合在一起，腦袋就會打結，到底 chain rule 是怎麼在這麼複雜的神經網路之間套用的? 就算了解基礎也很難相信實際上到底怎麼運作的。我又沒有要真的使用的話，網路上的教學就覺得看看就好 Source:  A Step by Step Backpropagation Example 但決心要了解 backpropagation 細節之後，不少教學都提到了 computational graph，從基礎的數學運算當作 nodes 來去理解似乎是比較簡單的方式。 後來找到了這篇文章  Calculus on Computational Graphs: Backpropagation  把 chain rule 講解的簡單至極，於是就在想，為何我不做一個網頁，讓大家可以自由地組合想要的 graph，然後看一下 chain rule 是怎麼流通的。 失敗作經驗 在做這次 side project 前，其實早在一年前我就開始作另一個 side project 是想展現神經網路的訓練過程。名稱叫做 explain-derivatives，是被 TensorFlow 的一個網頁 A Neural Network Playground 啟發的。 但由於一開始欠缺規劃，想到什麼就加什麼功能進去，造成架構一直修改，最後由於程式碼架構太過複雜就放棄了。 這個 project 是用 Cy...
閱讀更多

[Side Project] Google Apps Script 實作 Google Sheet 抽股票的篩選工具

-
圖片
有抽過股票的人應該都知道 HiStock嗨投資有一個 公開申購/股票抽籤日程表 的網頁: 不過我們自己應該都會去有一些規則去篩選，例如最簡單的篩選規則我們可以這樣訂: 承銷張數 >= 1000 (越多張中籤率越高) 獲利 >= 5000 (獲利太少我幹嘛去抽?) 報酬率(%) >= 10 (報酬率太低怕可能等抽到股價已經跌破承銷價) 不要含有 "KY" 的股票 在 Google Sheets 試算表匯入網頁資料 我們可以打開一個空白的試算表，在最左上角的一格輸入: =IMPORTHTML("https://histock.tw/stock/public.aspx", "table") 這樣表單就會大概 一小時更新一次 把上面網頁的資料匯入到工作表中: 條件式格式設定好難用 如何把我們想要篩選的列給標示出來? 我們可以用條件式格式設定 (Conditional formatting)。 為了套用顏色到每一列，我們只能先選全部範圍，再用公式的方式: =AND($F1>=1000, $I1>=5000, $J1>=10) 可是光是套用前三條規則我們立刻就發現公式變得很長又不好讀: 條件式格式設定的缺點 條件式格式設定這麼難用，我盡量會避免的原因是: 剪下、複製、貼上一些資料後，套用範圍經常會亂掉，會這邊缺一個洞、那邊缺一個洞 要經常更改公式會變得很麻煩 在 Excel 也會碰到同樣的問題。第一個剪下貼上的問題可以透過一些小技巧避免，第二個問題基本上無解。 用 Google Apps Script 寫小工具: Smart 篩選 之前就有用 Google Apps Script 幫不會用公式的朋友寫一些好用的小工具的經驗，所以我就在想，我能不能做出一個比條件式格式設定更好用的工具? 於是我就花了一些時間用 Google Apps Script, jQuery, DataTables, Bootstrap 5 加上比較新的 ES6 來練習寫一個工具 Smart 篩選 : 安裝方法我就放在 GitHub 不在這邊贅述了。 只要是 Table 格式的資料都可以用，我這邊只是用抽股票來當範例。 使用方式 把 GitHub 中的檔案都在 Apps Script 設置完後，重新整...
閱讀更多