如何建置 python, pytest, vscode 的測試程式的 debug 環境

ThisisEngineering null on Unsplash

Let's build debug environment for testing software development.

軟體工程師的日常

你知道嗎？軟體工程師的日常有很大部分時間都在 Trace code & Debug 度過。

根據我的觀察，測試領域大家愛用的程式語言是 python，幾乎都會搭配一個測試框架 ，例如 pytest, IDE 用 Microsoft vscode，考慮團隊共同開發，工作站的作業系統會選 Linux。

1. 獨立運行的 python 虛擬環境
2. 建立 IDE vscode 的 debug 配置

獨立運行的 python 虛擬環境

什麼是「python 虛擬環境」？ python 的虛擬環境可以理解是從系統獨立「格」出來的一個虛擬空間，每個虛擬空間可以有自己的 python 解譯器、所需的套件以及環境設定。可以想像一個被拿來格套的公寓，每間套房都有自己的衛浴、床鋪等設施，不同的住戶入住會有不同的電器需求與室內裝修風格。

用 python 的 venv 套件就能在作業系統上建立一到多個 python 虛擬環境。以我目前的 Linux 作業系統為例，雖然系統已經有提供 python 3.7，但我需要在專案 A 跑 python 3.8.17，在專案 B 跑 python 3.12.9，可以先用 venv 把 python 3.8.17 的虛擬環境建起來，如法泡製後面的 python 3.12.9。

# 使用 venv 建立 python 虛擬環境​
# 指定 .venv3817 目錄當作虛擬環境的根目錄​
$~/Python-3.8.17/python --version # 習慣先確認下版本
$~/Python-3.8.17/python -m venv .venv3817 

一定會有人好奇，要建這麼多虛擬環境感覺好麻煩，難道不能直接使用作業系統的 python 環境嗎？在只有單人的作業環境是可以，只是每次切換專案都需要重新整備開發環境，重新安裝所需的 python 版本與套件，管理成本實在太高了。在多人共用的工作站就修改系統設定所有人都會受到影響。所以花點空間來換取獨立的虛擬環境是最好的選擇，還有萬一不小心手賤玩壞了直接整個目錄砍掉完全不用擔心。

啟動與退出虛擬環境

我的習慣是會幫不同版本的 python 虛擬環境按照編譯器版本取名字，例如：python 3.8 的就會用 .venv3817，前面的點(.)可以讓虛擬環境的資料夾變成隱藏屬性。建立好虛擬環境後就可以用 source 指令啟動 python 虛擬環境，接著就可以安裝需要的擴充套件。

# 啟動虛擬環境
$source .venv3817/bin/activate 
(.venv3817)$  

看到提示字符 $ 前面出現 (.venv3817) 代表已經成功進入虛擬環境。deactivate 指令可以退出目前的 python 虛擬環境。看到提示字符 $ 前的 (.venv3817) 消失，代表退出成功。

# 退出虛擬環境
(.venv3817)$deactivate
$

所以要切換不同虛擬環境就是先 deactivate 退出原本虛擬環境再用 source 指令進入指定的虛擬環境。

安裝必要套件

成功進入 python 虛擬環境後，就可以用 pip 安裝 python 套件，習慣上會按照不同的目的批次處理套件。例如：要安裝的套件放到 requirements.txt 內，要移除的套件放到 requirements-uninstall.txt，其他如內部開發的套件就放在 requirement-framework.txt。等待套件安裝時間取決於套件數量，可以先去喝個水上個廁所，套件安裝完畢後代表虛擬環境準備工作告一段落了。

# 先把 pip 升級
# 安裝套件 requirements.txt
# 解安裝​不需要的套件 requirements-unistall.txt
# 安裝內部開發套件 requirement-framework.txt
(.venv3817)$pip install --upgrade pip 
(.venv3817)$pip install -r requirements.txt 
(.venv3817)$pip uninstall -y -r requirements-uninstall.txt 
(.venv3817)$pip install -r requirement-framework.txt 

建立 IDE vscode 的 debug 配置

接下來開始配置 vscode 的 debug 環境設定，目標是在 vscode 的 .vscode 目錄內建立一個 launch.json 檔案，並完成裡面的配置設定。vscode 啟動 debug 模式會從此檔識別出 debug 進入點，以及 debug 啟動程式所需參數也會寫在這個檔案內。如果是第一次啟動 vscode 發現沒有 .vscode 目錄或 launch.json 檔案，先以用 vscode 的選單工具 Run-> Add configuration 先把檔案與基礎的環境與參數建起來。

一般的 python 程式要進 debug mode 都是透過 python 的 main() 函數進入，這是 file debug 模式。因為測試程式會使用 pytest 模組，所以進入點會改由模組啟動，其實就是 python -m 的意思，所以使用選單工具時，當 IDE 有問到要以哪種模式啟動時，要記得選 by module 把然後把模組名稱 pytest 填入。

{
	"version": "0.2.0",
	"configuations":[
	{
		"name": "Python Debugger: pytest debug",
		"type": "debugpy",
		"module":"pytest",
		"request":"launch"
		}
	]
}

加入 args 參數設定

設定好以模組 pytest 啟動 debug 模式後，會得到基本的 debug 環境設定。接下來還需要手動補上一組 args 設定，告知 vscode debug 程式所需的外部參數。因為是模組方式啟動，需要的外部參數就是 pytest 單獨執行時可以帶入的參數，例如可用 -k testcase 來啟動特定名稱 testcase 作為進入點。pytest 本身還有很多參數可以搭配使用，更多細節可以參考 pytest 的 help file，再按照需求添加至 args 的設定就可以了。

{
	"version": "0.2.0",
	"configuations":[
		{
			"name": "Python Debugger: pytest debug",
			"type": "debugpy",
			"request":"launch",
			"module":"pytest",​
			"justMyCode": true,
			"args":[
				"-rA",
				"--show-capture=no",
				​"--capture=no",
				"--tb=no",
				"-c",
				"testcase/pytest.ini",
				"--topo_config_path=topology/testbed_2/main.yaml",
				"-m",
				"test_group",
				"test_case"
			]
		}
	]
}

選擇要搭配的 python 解譯器

我想你應該注意到了，現在系統內有三個 python 執行環境，vscode 怎麼知道要用哪個環境的 python 解譯器來 debug 呢？可以觀察 IDE 右下角的 button，可以看出我目前用的解譯器是 .venv3129 的 python，點選它就可以切換不同版本的 python 虛擬環境讓 vscode 知道該用哪個版本的解譯器進行除錯。

Location of selecting python interpreter

Select a target verion for debugging

完成這關聯性設定後，python, pytest 與 vscode 的 debug 環境就配置完成。接下來就可以開心地下斷點，按 F5 進行日常開發、trace code 與除錯的工作了。

結論：久久做一次，做一次久久

要建立 python, pytest, vscode 的 debug 環境上並不太困難，也都是做一次久久，然後久久才做一次的小事。只是每次要執行的時候總是「流程記得很清楚步驟細節總是很模糊」，會令人感到煩躁心情不美麗；善用文件化補充細節就能在下次需要重建 debug 環境時省下不少時間。