Visual Studio Code 中的 Python 測試

Python 擴充功能支援使用 Python 內建的 unittest 框架和 pytest 進行測試。

單元測試的簡要背景

(如果您已熟悉單元測試，可以跳至逐步解說。)

單元是要測試的特定程式碼片段，例如函式或類別。單元測試是其他程式碼片段，其專門使用各種不同的輸入 (包括邊界和邊緣案例) 來執行程式碼單元。unittest 和 pytest 框架都可用於撰寫單元測試。

例如，假設您有一個函式，用於驗證使用者在 Web 表單中輸入的帳戶號碼格式

def validate_account_number_format(account_string):
    # Return False if invalid, True if valid
    # ...

單元測試僅關注單元的介面 (其引數和傳回值)，而不關注其實作 (這就是為什麼函式主體中未顯示任何程式碼的原因；通常您會使用其他經過良好測試的程式庫來協助實作函式)。在此範例中，函式接受任何字串，如果該字串包含格式正確的帳戶號碼，則傳回 true，否則傳回 false。

為了徹底測試此函式，您需要向其拋出所有可能的輸入：有效字串、輸入錯誤的字串 (錯一個或兩個字元，或包含無效字元)、太短或太長的字串、空白字串、Null 引數、包含控制字元 (非文字程式碼) 的字串、包含 HTML 的字串、包含注入攻擊 (例如 SQL 命令或 JavaScript 程式碼) 的字串等等。如果驗證的字串稍後用於資料庫查詢或顯示在應用程式的 UI 中，則測試注入攻擊等安全性案例尤其重要。

針對每個輸入，您接著定義函式的預期傳回值 (或多個值)。同樣地，在此範例中，函式應僅針對格式正確的字串傳回 true。(號碼本身是否為真實帳戶是另一回事，將在其他地方透過資料庫查詢處理。)

掌握所有引數和預期傳回值後，您現在可以撰寫測試本身，這些測試是使用特定輸入呼叫函式的程式碼片段，然後將實際傳回值與預期傳回值進行比較 (此比較稱為判斷提示)

# Import the code to be tested
import validator

# Import the test framework (this is a hypothetical module)
import test_framework

# This is a generalized example, not specific to a test framework
class Test_TestAccountValidator(test_framework.TestBaseClass):
    def test_validator_valid_string():
        # The exact assertion call depends on the framework as well
        assert(validate_account_number_format("1234567890"), True)

    # ...

    def test_validator_blank_string():
        # The exact assertion call depends on the framework as well
        assert(validate_account_number_format(""), False)

    # ...

    def test_validator_sql_injection():
        # The exact assertion call depends on the framework as well
        assert(validate_account_number_format("drop database master"), False)

    # ... tests for all other cases

程式碼的確切結構取決於您使用的測試框架，本文稍後會提供具體範例。無論如何，如您所見，每個測試都很簡單：使用引數叫用函式，並判斷提示預期的傳回值。

所有測試的合併結果是您的測試報告，其中告訴您函式 (單元) 在所有測試案例中是否如預期般運作。也就是說，當單元通過其所有測試時，您可以確信它運作正常。(測試驅動開發的做法是您實際上先撰寫測試，然後撰寫程式碼以通過越來越多的測試，直到所有測試都通過為止。)

由於單元測試是小型、隔離的程式碼片段 (在單元測試中，您會避免外部相依性，並使用模擬資料或其他模擬輸入)，因此執行速度很快且成本不高。此特性表示您可以儘早且經常執行單元測試。開發人員通常甚至在將程式碼認可至存放庫之前就執行單元測試；閘道簽入系統也可以在合併認可之前執行單元測試。許多持續整合系統也會在每次組建後執行單元測試。儘早且經常執行單元測試表示您可以快速捕捉到迴歸，也就是先前通過所有單元測試的程式碼行為中意外的變更。由於測試失敗可以輕鬆追溯到特定的程式碼變更，因此很容易找到並修正失敗的原因，這無疑比在流程後期才發現問題要好得多！

如需單元測試的一般背景資訊，請閱讀 Wikipedia 上的 單元測試。如需有用的單元測試範例，您可以檢閱 https://github.com/gwtw/py-sorting，這是一個包含不同排序演算法測試的存放庫。

範例測試逐步解說

Python 測試是 Python 類別，位於與受測程式碼不同的檔案中。每個測試框架都會指定測試和測試檔案的結構和命名。一旦您撰寫測試並啟用測試框架，VS Code 就會找到這些測試，並為您提供各種命令來執行和偵錯它們。

針對本節，請建立一個資料夾並在 VS Code 中開啟它。然後建立一個名為 inc_dec.py 的檔案，其中包含下列要測試的程式碼

def increment(x):
    return x + 1

def decrement(x):
    return x - 1

使用此程式碼，您可以體驗在 VS Code 中使用測試，如下列各節所述。

設定測試

一旦您安裝 Python 擴充功能並在編輯器中開啟 Python 檔案，測試燒杯圖示將顯示在 VS Code 活動列上。燒杯圖示適用於測試總管檢視。當開啟測試總管時，如果您未啟用測試框架，您將看到設定測試按鈕。一旦您選取設定測試，系統將提示您選取測試框架和包含測試的資料夾。如果您使用 unittest，系統也會要求您選取用於識別測試檔案的檔案全域模式。

注意：檔案全域模式是已定義的字串模式，其根據萬用字元比對檔案或資料夾名稱，然後包含或不包含。

您可以隨時使用命令選擇區中的 Python: 設定測試命令來設定測試。您也可以透過設定 python.testing.unittestEnabled 或 python.testing.pytestEnabled 手動設定測試，這可以在設定編輯器中或 settings.json 檔案中完成，如 VS Code 設定文件中所述。每個框架也有特定的組態設定，如其資料夾和模式的測試組態設定下所述。

如果同時啟用這兩個框架，則 Python 擴充功能只會執行 pytest。

如果您啟用 pytest，VS Code 會提示您安裝框架套件 (如果目前啟用的環境中尚未存在)

注意：python 擴充功能支援的 pytest 最低版本為 7.0.0。

建立測試

每個測試框架都有其自身的慣例，用於命名測試檔案和建構其中的測試，如下列各節所述。每個案例都包含兩個測試方法，其中一個方法會故意設定為失敗，以用於示範目的。

unittest 中的測試

建立一個名為 test_unittest.py 的檔案，其中包含一個具有兩個測試方法的測試類別

import inc_dec    # The code to test
import unittest   # The test framework

class Test_TestIncrementDecrement(unittest.TestCase):
    def test_increment(self):
        self.assertEqual(inc_dec.increment(3), 4)

    # This test is designed to fail for demonstration purposes.
    def test_decrement(self):
        self.assertEqual(inc_dec.decrement(3), 4)

if __name__ == '__main__':
    unittest.main()

pytest 中的測試

建立一個名為 test_pytest.py 的檔案，其中包含兩個測試方法

import inc_dec    # The code to test

def test_increment():
    assert inc_dec.increment(3) == 4

# This test is designed to fail for demonstration purposes.
def test_decrement():
    assert inc_dec.decrement(3) == 4

測試探索

根據預設，Python 擴充功能會在您啟用框架後嘗試探索測試。您也可以隨時使用命令選擇區中的 測試: 重新整理測試命令來觸發測試探索。

python.testing.autoTestDiscoverOnSaveEnabled 預設設定為 true，這表示每當您在工作區中新增、刪除或更新任何 Python 檔案時，也會自動執行測試探索。若要停用此功能，請將值設定為 false，這可以在設定編輯器中或 settings.json 檔案中完成，如 VS Code 設定文件中所述。您需要重新載入視窗，此設定才會生效。

測試探索會套用目前框架的探索模式 (可以使用測試組態設定自訂)。預設行為如下

• python.testing.unittestArgs：在最上層專案資料夾中尋找名稱中包含 "test" 的任何 Python (.py) 檔案。所有測試檔案都必須是可以匯入的模組或套件。您可以使用 -p 組態設定自訂檔案比對模式，並使用 -t 設定自訂資料夾。

• python.testing.pytestArgs：尋找名稱以 "test_" 開頭或以 "_test" 結尾的任何 Python (.py) 檔案，這些檔案位於目前資料夾和所有子資料夾內的任何位置。

提示：有時無法探索到放在子資料夾中的測試，因為無法匯入這些測試檔案。若要使其可匯入，請在該資料夾中建立一個名為 __init__.py 的空檔案。

如果測試探索成功，您會在測試總管中看到列出的測試

如果探索失敗 (例如，未安裝測試框架，或您的測試檔案中有語法錯誤)，您會在測試總管中看到顯示的錯誤訊息。您可以檢查 Python 輸出面板以查看完整的錯誤訊息 (使用 檢視 > 輸出 功能表命令來顯示 輸出 面板，然後從右側的下拉式清單中選取 Python)。

一旦 VS Code 辨識測試，它就會提供幾種方式來執行這些測試，如執行測試中所述。

執行測試

您可以使用下列任何動作來執行測試

• 在開啟測試檔案的情況下，選取測試定義行旁邊的裝訂邊中顯示的綠色執行圖示，如上一節所示。此命令只會執行該一個方法。

  

• 從 命令選擇區中，執行下列任何命令

  • 測試: 執行所有測試 - 執行已探索到的所有測試。
  • 測試: 執行目前檔案中的測試 - 執行編輯器中開啟的檔案中的所有測試。
  • 測試: 執行游標處的測試 - 只執行編輯器中游標下的測試方法。

• 從 測試總管

  • 若要執行所有探索到的測試，請選取 測試總管頂端的播放按鈕

    

  • 若要執行特定的一組測試或單一測試，請選取檔案、類別或測試，然後選取該項目右側的播放按鈕

    

  • 您也可以透過測試總管執行選取的測試。若要執行此操作，請 Ctrl+按一下 (或 macOS 上的 Cmd+按一下) 您想要執行的測試，以滑鼠右鍵按一下其中一個測試，然後選取 執行測試。

在測試執行之後，VS Code 會直接在編輯器中以裝訂邊裝飾的形式顯示結果。失敗的測試也會在編輯器中醒目提示，並顯示測試執行錯誤訊息和所有測試執行歷程記錄的概覽檢視。您可以按下 Escape 以關閉檢視，您可以透過開啟使用者設定 (喜好設定: 開啟設定 (UI) 命令，位於 命令選擇區中) 並將 測試: 自動開啟概覽檢視 設定的值變更為 never 來停用它。

在 測試總管中，會顯示個別測試以及包含這些測試的任何類別和檔案的結果。如果該資料夾中的任何測試未通過，資料夾將會顯示失敗圖示。

VS Code 也會在 Python 測試記錄輸出面板中顯示測試結果。

平行執行測試

透過 pytest-xdist 套件支援使用 pytest 平行執行測試。若要啟用平行測試

1. 開啟整合式終端機並安裝 pytest-xdist 套件。如需更多詳細資訊，請參閱專案的文件頁面。

   適用於 Windows

   py -3 -m pip install pytest-xdist
   

   適用於 macOS/Linux

   python3 -m pip install pytest-xdist
   

2. 接下來，在您的專案目錄中建立一個名為 pytest.ini 的檔案，並新增以下內容，指定要使用的 CPU 數量。例如，若要將其設定為 4 個 CPU

    [pytest]
    addopts=-n4
   

   或者，如果您使用的是 pyproject.toml 檔案

    [tool.pytest.ini_options]
    addopts="-n 4"
   

3. 執行您的測試，這些測試現在將平行執行。

執行具有涵蓋率的測試

測試涵蓋率是用來衡量您的程式碼有多少比例被測試涵蓋，這可以協助您識別程式碼中未完全測試的區域。如需有關測試涵蓋率的詳細資訊，請造訪 VS Code 的測試涵蓋率文件。

提示：目前僅當將 "python.experiments.optInto": ["pythonTestAdapter"] 新增至您的使用者 settings.json 時，才支援執行具有涵蓋率的 Python 測試。

若要執行已啟用涵蓋率的測試，請選取測試總管中的涵蓋率執行圖示，或從您通常從中觸發測試執行的任何功能表中選取「執行並涵蓋率」選項。如果您使用 pytest，Python 擴充功能將使用 pytest-cov 外掛程式執行涵蓋率，或者針對 unittest 使用 coverage.py。

注意：在執行具有涵蓋率的測試之前，請確定已為您的專案安裝正確的測試涵蓋率套件。

一旦涵蓋率執行完成，程式碼行將在編輯器中醒目提示以表示程式碼行層級的涵蓋率。測試涵蓋率結果將會顯示為測試總管中的「測試涵蓋率」子索引標籤，您也可以使用命令選擇區 (F1)) 中的 測試: 專注於測試涵蓋率檢視導覽至此索引標籤。在此面板上，您可以檢視工作區中每個檔案和資料夾的程式碼行涵蓋率計量。

若要在使用 pytest 時更精細地控制您的涵蓋率執行，您可以編輯 python.testing.pytestArgs 設定以包含您的規格。當 pytest 引數 --cov 存在於 python.testing.pytestArgs 中時，Python 擴充功能將不會對涵蓋率引數進行其他編輯，以允許您的自訂生效。如果找不到 --cov 引數，則擴充功能會在執行之前將 --cov=. 新增至 pytest 引數，以在工作區根目錄啟用涵蓋率。

偵錯測試

您有時可能需要逐步執行並分析偵錯工具中的測試，原因可能是測試本身有程式碼缺陷需要追蹤，或是為了更深入了解程式碼的受測區域為何失敗。如需有關偵錯的詳細資訊，或了解其在 VS Code 中的運作方式，您可以閱讀Python 偵錯組態和一般 VS Code 偵錯文章。

例如，先前提供的 test_decrement 函式失敗，因為判斷提示本身有錯誤。下列步驟示範如何分析測試

1. 在 test_decrement 函式的第一行設定中斷點。

2. 以滑鼠右鍵按一下函式定義旁邊的裝訂邊裝飾，然後選取 偵錯測試，或選取 測試總管中該測試旁邊的 偵錯測試 圖示。VS Code 會啟動偵錯工具，並在中斷點處暫停。

   

3. 在 偵錯主控台面板中，輸入 inc_dec.decrement(3) 以查看實際結果為 2，而測試中指定的預期結果為不正確的值 4。

4. 停止偵錯工具並修正錯誤的程式碼

   # unittest
   self.assertEqual(inc_dec.decrement(3), 2)
   
   # pytest
   assert inc_dec.decrement(3) == 2
   

5. 儲存檔案並再次執行測試以確認它們通過，並查看裝訂邊裝飾也指示通過狀態。

   注意：執行或偵錯測試不會自動儲存測試檔案。務必先儲存對測試的變更，再執行測試，否則您可能會對結果感到困惑，因為它們仍然反映檔案的先前版本！

您可以使用命令選擇區中的下列命令來偵錯測試

• 測試: 偵錯所有測試 - 針對工作區中的所有測試啟動偵錯工具。
• 測試: 偵錯目前檔案中的測試 - 針對您在編輯器中開啟的檔案中定義的測試啟動偵錯工具。
• 測試: 偵錯游標處的測試 - 僅針對您在編輯器中將游標焦點放在其上的方法啟動偵錯工具。您也可以使用測試總管中的 偵錯測試 圖示，針對選取範圍中的所有測試和所有探索到的測試啟動偵錯工具。

您也可以變更按一下裝訂邊裝飾的預設行為，以偵錯測試而不是執行，方法是將 testing.defaultGutterClickAction 設定值變更為 debug (位於您的 settings.json 檔案中)。

偵錯工具的運作方式與其他 Python 程式碼的運作方式相同，包括中斷點、變數檢查等等。若要自訂偵錯測試的設定，您可以在工作區中 .vscode 資料夾的 launch.json 檔案中指定 "purpose": ["debug-test"]。當您執行 測試: 偵錯所有測試、測試: 偵錯目前檔案中的測試 和 測試: 偵錯游標處的測試 命令時，將會使用此組態。

例如，launch.json 檔案中的下列組態會停用偵錯測試的 justMyCode 設定

{
  "name": "Python: Debug Tests",
  "type": "debugpy",
  "request": "launch",
  "program": "${file}",
  "purpose": ["debug-test"],
  "console": "integratedTerminal",
  "justMyCode": false
}

如果您有多個具有 "purpose": ["debug-test"] 的組態項目，則會使用第一個定義，因為我們目前不支援此要求類型的多個定義。

測試命令

以下是 Python 擴充功能在 VS Code 中支援的所有測試命令。這些命令都可以在命令選擇區中找到

Django 單元測試

Python 擴充功能也提供探索和執行 Django 單元測試的支援！您只需幾個額外的設定步驟即可探索您的 Django 測試

提示：目前僅當將 "python.experiments.optInto": ["pythonTestAdapter"] 新增至您的使用者 settings.json 時，才支援 Django 測試。

1. 在您的 settings.json 檔案中設定 "python.testing.unittestEnabled": true,。
2. 新增 MANAGE_PY_PATH 作為環境變數
   1. 在您的專案根目錄建立 .env 檔案。
   2. 將 MANAGE_PY_PATH='<path-to-manage.py>' 新增至 .env 檔案，並以應用程式 manage.py 檔案的路徑取代 <path-to-manage.py>。

      提示：您可以透過以滑鼠右鍵按一下總管檢視中的檔案並選取 複製路徑 來複製路徑。

3. 視需要將 Django 測試引數新增至 settings.json 檔案中的 "python.testing.unittestArgs": []，並移除任何與 Django 不相容的引數。

注意：根據預設，Python 擴充功能會在專案根目錄中尋找並載入 .env 檔案。如果您的 .env 檔案不在專案根目錄中，或者您使用的是 VS Code 變數取代，請將 "python.envFile": "${workspaceFolder}/<path-to-.env>" 新增至您的 settings.json 檔案。這可讓 Python 擴充功能在執行和探索測試時從此檔案載入環境變數。取得有關Python 環境變數的更多資訊。

導覽至測試檢視，然後選取 重新整理測試 按鈕，讓您的 Django 測試顯示出來！

疑難排解

如果您的 Django 單元測試未顯示在測試檢視中，請嘗試下列疑難排解步驟

• 在 Python 輸出面板中搜尋錯誤訊息。它們可能會提供有關為何未探索到您的測試的提示。

• 嘗試在終端機中執行 Django 測試。然後將相同的命令「轉換」為 VS Code 設定。例如，如果您在終端機中執行 python manage.py test --arg，您會將 MANAGE_PY_PATH='./manage.py' 新增至 .env 檔案，並在 VS Code 設定中設定 "python.testing.unittestArgs": [--arg]。

  或者，您也可以在 Python 輸出面板中找到 Python 擴充功能執行的命令。

• 如果您最初使用相對路徑，請在使用絕對路徑設定 MANAGE_PY_PATH 環境變數時。

pytest 的 IntelliSense

Pylance 提供 IntelliSense 功能，可協助您更有效率地使用 pytest 夾具和參數化測試。

當您輸入測試函式的參數時，Pylance 會為您提供完成項目清單，其中包含來自 @pytest.mark.parametrize 裝飾項的引數名稱，以及在您的測試檔案或 conftest.py 中定義的現有 pytest 夾具。程式碼導覽功能 (例如 移至定義 和 尋找所有參考) 和重新命名符號重構也受到支援。

當滑鼠停留在夾具參考或參數化引數參考上方時，Pylance 會顯示推斷的類型註解，無論是根據夾具的傳回值，還是根據傳遞至參數化裝飾項的引數的推斷類型。

Pylance 也提供程式碼動作，將類型註解新增至具有夾具參數的測試函式。也可以透過在您的使用者設定中將 python.analysis.inlayHints.pytestParameters 設定為 true，來啟用推斷的夾具參數類型的內嵌提示。

測試組態設定

Python 測試的行為是由 VS Code 提供的通用 UI 設定，以及特定於 Python 和您已啟用的任何框架的設定所驅動。

通用 UI 設定

影響測試功能 UI 的設定是由 VS Code 本身提供的，當您搜尋「Testing」時，可以在VS Code 設定編輯器中找到這些設定。

通用 Python 設定

unittest 組態設定

unittest 的預設引數如下

• -v 設定預設詳細程度。移除此引數可簡化輸出。
• -s . 指定探索測試的起始目錄。如果您在 "test" 資料夾中有測試，請將引數變更為 -s test (在引數陣列中表示 "-s", "test")。
• -p *test*.py 是用於尋找測試的探索模式。在此案例中，它是任何包含 "test" 一詞的 .py 檔案。如果您以不同的方式命名測試檔案，例如在每個檔案名稱後附加 "_test"，則在陣列的適當引數中使用類似 *_test.py 的模式。

若要在第一次失敗時停止測試執行，請將快速失敗選項 "-f" 新增至引數陣列。

請參閱 unittest 命令列介面 以取得所有可用的選項。

pytest 設定組態

您也可以使用 pytest.ini 檔案設定 pytest，如pytest 設定中所述。

注意 如果您已安裝 pytest-cov 覆蓋率模組，則 VS Code 在偵錯時不會在斷點停止，因為 pytest-cov 使用相同的技術來存取正在執行的原始碼。 若要防止此行為，請在偵錯測試時於 pytestArgs 中加入 --no-cov，例如將 "env": {"PYTEST_ADDOPTS": "--no-cov"} 新增至您的偵錯組態。（請參閱上方偵錯測試，瞭解如何設定該啟動組態。）（如需更多資訊，請參閱 pytest-cov 文件中的偵錯工具和 PyCharm。）

IntelliSense 設定

另請參閱

• Python 環境 - 控制用於編輯和偵錯的 Python 解譯器。
• 設定參考 - 探索 VS Code 中與 Python 相關的完整設定範圍。