在 Visual Studio Code 中進行 Python 測試

Python 擴充功能建立在 VS Code 內建的 測試功能之上，並為 Python 內建的 unittest 框架以及 pytest 提供測試探索、測試覆蓋率，以及執行與偵錯測試的功能。

設定測試

當安裝了 Python 擴充功能且在編輯器中開啟 Python 檔案時，VS Code 活動列上會顯示一個燒杯圖示，代表測試總管 (Test Explorer) 檢視。如果尚未啟用測試框架，開啟測試總管會顯示設定 Python 測試 (Configure Python Tests) 按鈕。選擇設定 Python 測試會提示您選擇測試框架以及包含測試的資料夾。如果您使用 unittest，還需要選擇用於識別測試檔案的檔案 glob 模式。

您可以隨時透過命令選擇區 (Command Palette) 使用 Python: Configure Tests 命令，或按照 VS Code 設定 (Settings) 文件所述，在設定編輯器或 settings.json 檔案中設定 python.testing.unittestEnabled 或 python.testing.pytestEnabled 來設定測試。如 測試組態設定 所述，每個框架也針對其資料夾和模式有特定的組態設定。

如果您啟用 pytest 但目前啟用的環境中尚未安裝它，Python 擴充功能會嘗試在背景安裝。此外，如果兩個框架都已啟用，Python 擴充功能將僅執行 pytest。

測試探索

依預設，Python 擴充功能會在您啟用框架後嘗試探索測試。您隨時可以使用命令選擇區中的 Test: Refresh Tests 命令來觸發測試探索。

測試探索會對目前框架套用探索模式（可使用 測試組態設定 進行自訂）。預設行為如下：

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

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

如果測試探索成功，您將會在測試總管中看到測試清單。

當直接從測試總管觸發測試探索時，您也可以取消正在進行的測試探索呼叫。請使用取消 (Cancel) 按鈕，該按鈕會在探索期間取代重新整理 (Refresh) 按鈕。

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

執行測試

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

• 開啟測試檔案後，點選測試定義行旁裝訂邊 (gutter) 顯示的綠色執行圖示（如上一節所示）。此命令僅執行該特定方法。

  

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

  • Test: Run All Tests - 執行所有已探索的測試。
  • Test: Run Tests in Current File - 執行編輯器中開啟的檔案內的所有測試。
  • Test: Run Test at Cursor - 僅執行編輯器中游標所在位置的測試方法。

• 從測試總管：

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

    

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

    

  • 您也可以透過測試總管執行選定的測試。若要執行此操作，請按住 Ctrl+點擊（在 macOS 上為 Cmd+點擊）選取您要執行的測試，對其中一個按右鍵，然後選擇執行測試 (Run Test)。

測試執行後，VS Code 會直接在編輯器中以裝訂邊裝飾顯示結果。失敗的測試也會在編輯器中反白顯示，並提供一個 Peek View，顯示測試執行錯誤訊息以及所有測試執行的歷史記錄。您可以按 Escape 關閉該檢視。您也可以透過開啟使用者設定（在命令選擇區中輸入偏好設定：開啟設定 (UI) 命令）並將測試：自動開啟 Peek View 設定的值變更為 never 來停用它。

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

VS Code 也會在測試結果 (Test Results) 面板中顯示測試結果。

執行含覆蓋率的測試

若要在啟用覆蓋率的情況下執行測試，請選取測試總管中的覆蓋率執行圖示，或從您通常觸發測試執行的任何選單中選擇使用覆蓋率執行 (Run with coverage) 選項。如果您使用 pytest，Python 擴充功能會使用 pytest-cov 外掛程式執行覆蓋率分析；若是 unittest，則使用 coverage.py。

覆蓋率執行完成後，編輯器中會反白顯示程式碼行以標示行層級的覆蓋率。測試覆蓋率結果會以「測試覆蓋率 (Test Coverage)」子頁籤形式出現在測試總管中，您也可以透過命令選擇區中的測試：聚焦於測試覆蓋率檢視 (Testing: Focus on Test Coverage View) 指令（⇧⌘P (Windows, Linux Ctrl+Shift+P)）導覽至該處。在此面板上，您可以查看工作區中每個檔案和資料夾的行覆蓋率指標，以及相關的分支覆蓋率。

若要在使用 pytest 時對覆蓋率執行過程進行更精細的控制，您可以編輯 python.testing.pytestArgs 設定以包含您的規格。當 python.testing.pytestArgs 中存在 pytest 引數 --cov 時，Python 擴充功能將不會對覆蓋率引數進行任何額外編輯，以確保您的自訂設定生效。如果找不到 --cov 引數，擴充功能會在執行前將 --cov=. 新增至 pytest 引數，以便在工作區根目錄啟用覆蓋率。

有關測試覆蓋率的更多資訊，請造訪 VS Code 的 測試覆蓋率文件。

偵錯測試

若要偵錯測試，請在函數定義旁的裝訂邊裝飾上按右鍵並選擇偵錯測試 (Debug Test)，或選取測試總管中該測試旁邊的偵錯測試圖示。

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

• Test: Debug All Tests - 為工作區中的所有測試啟動偵錯工具。
• Test: Debug Tests in Current File - 為編輯器中開啟的檔案中定義的測試啟動偵錯工具。
• Test: Debug Test at Cursor - 僅為您在編輯器中將游標聚焦的方法啟動偵錯工具。您也可以使用測試總管中的偵錯測試圖示，為選定範圍內的所有測試以及所有已探索到的測試啟動偵錯工具。

您也可以透過在 settings.json 檔案中將 testing.defaultGutterClickAction 設定值變更為 debug，將點選裝訂邊裝飾的預設行為從執行變更為偵錯。

偵錯工具對於測試的運作方式與其他 Python 程式碼相同，包括中斷點、變數檢查等。若要自訂測試偵錯設定，您可以透過在工作區的 .vscode 資料夾內的 launch.json 或 settings.json 檔案中新增 "purpose": ["debug-test"] 到您的設定中，來指定測試偵錯組態。當您執行 Test: Debug All Tests、Test: Debug Tests in Current File 及 Test: Debug Test at Cursor 命令時，將會使用此組態。

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

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

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

如需偵錯的詳細資訊，或要了解它在 VS Code 中如何運作，請閱讀 Python 偵錯組態 和一般的 VS Code 偵錯 (Debugging) 文章。

並行執行測試

透過 pytest-xdist 套件支援使用 pytest 平行執行測試。請造訪其 文件，以取得有關如何使用 pytest-xdist 的更多資訊。

當啟用 xdist 且引數中未指定工作站 (worker) 數量時，Python 擴充功能會根據在測試總管中選取的測試數量，自動最佳化工作站數量。

Django 單元測試

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

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

      提示：您可以透過在檔案總管檢視中對檔案按右鍵並選擇複製路徑 (Copy Path) 來複製路徑。

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

導覽至測試檢視，並選取重新整理測試 (Refresh Tests) 按鈕以顯示您的 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 環境變數時，改為使用 manage.py 檔案的絕對路徑。

測試命令

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

測試組態設定

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

通用 UI 設定

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

通用 Python 設定

unittest 組態設定

unittest 的預設引數如下：

• -v 設定預設的詳細程度。移除此引數可獲得較精簡的輸出。
• -s . 指定探索測試的起始目錄。如果您有「test」資料夾中的測試，請將引數變更為 -s test（意味著在引數陣列中為 "-s", "test"）。
• -p *test*.py 是用於尋找測試的探索模式。在此情況下，它是任何包含「test」字詞的 .py 檔案。如果您以不同方式命名測試檔案（例如在每個檔名後加上「_test」），請在陣列的對應引數中使用類似 *_test.py 的模式。

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

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

pytest 組態設定

pytest 的預設引數如下：

• rootdir 根據工作區中 python.testing.cwd 設定的存在與否進行動態調整。

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

IntelliSense 設定

參見

• Python 環境 - 控制編輯與偵錯時所使用的 Python 直譯器。
• 設定參考 - 探索 VS Code 中所有與 Python 相關的設定。