全部速查表Python 開發

pytest

pytest 8+

pytest CLI 命令快速參考：測試探索、選取、fixture、marker、平行化、parametrize 與覆蓋率整合——附常用參數與實作範例。

34 條命令

說明

pytest --version

印出 pytest 版本以及它找到的匯入函式庫路徑。

pytest --version

pytest --help

顯示所有 pytest CLI 旗標與簡短說明。

-h

pytest --help | less

探索

pytest

依預設探索規則（`test_*.py`／`*_test.py`、名為 `test_*` 的函式、名為 `Test*` 的類別）執行當前目錄與子目錄中的所有測試。

-x；--maxfail=1；--co；--collect-only；-q；-v；-k <expr>；-m <marker>；--no-header

pytest

pytest <path>

只執行指定檔案或目錄下的測試。支援 glob。

<path>；tests/；tests/test_x.py；tests/test_x.py::test_y

pytest tests/unit

pytest tests/test_user.py::TestUser::test_create

依完整節點路徑執行單一測試：模組／類別／函式。

pytest tests/test_user.py::test_create_user

選取

pytest -k <expr>

執行名稱符合子串／Python 運算式的測試（`-k 'user and not slow'`）。

-k 'pattern'；-k 'ClassName and method'

pytest -k 'create or update'

pytest -m <marker>

只執行帶有指定 marker 的測試（marker 必須在 `pyproject.toml` 或 pytest.ini 中註冊以避免警告）。

-m slow；-m 'not slow'

pytest -m 'not integration'

pytest --co

僅收集模式——列出 pytest 將執行的測試而不實際執行。CI 預覽很實用。

--collect-only；-q

pytest --co -q

停止／報告

pytest -x

首次失敗時停止。使用 `--maxfail=N` 可自訂門檻。

--maxfail=1；--maxfail=3；--exitfirst；-x

pytest -x --maxfail=2

pytest --tb=short

選擇 traceback 樣式：`long`（預設）、`short`、`line`、`native`、`no`（抑制）。

long；short；line；native；no

pytest --tb=short

pytest -v

詳細模式——顯示每個測試函式的完整節點 ID。加上 `-vv` 取得更詳細資訊。

-v；-vv；--no-header；--no-summary；-q；-rA

pytest -v --no-header

pytest -s

停用 stdout／stderr 捕捉——讓 print() 陳述直接輸出到終端機（罕見；建議在測試內使用 `capfd` fixture）。

--capture=no；-s；--capture=fd

pytest -s tests/test_print.py

pytest --durations=10

在最終報告顯示最慢的 10 個測試（`--durations=0` 顯示全部）。

--durations=10；--durations=min=0.5

pytest --durations=10

pytest -rA

印出額外測試結果的摘要：`E` 錯誤、`F` 失敗、`s` 略過、`x` 預期失敗、`A` 全部。

-rA；-rfE；-rs；-rxX

pytest -rA

重新執行

pytest --lf

Last-failed——只重新執行上次失敗的測試。搭配 `--ff` 讓失敗的測試優先排序。

--lf；--last-failed；--ff；--failed-first；--cache-clear

pytest --lf

pytest --sw

逐步模式——首次失敗時停止，下一次執行從該處繼續。

--stepwise；--stepwise-skip；--stepwise-skip-some

pytest --sw

Parametrize／fixture

pytest --fixtures

列出當前測試範圍可見的所有 fixture（從 repo 根目錄執行時為全專案範圍）。

--fixtures；--fixtures-per-test

pytest --fixtures -q

pytest --markers

列出所有已定義的 marker（在 pytest.ini／pyproject.toml 中註冊）。

--markers

pytest --markers

平行化

pytest -n <N>

把測試分散到 `<N>` 個 worker 行程中平行執行（pytest-xdist plugin）。用 `auto` 依 CPU 數量決定 worker。

-n auto；-n 4；--dist loadscope；--dist loadfile；-p no:cacheprovider

pytest -n auto

pytest --dist loadgroup

依 `@pytest.mark.group_*` marker 把測試分組（xdist），同一組在同一 worker 內執行——適合資源互斥的測試。

--dist loadgroup；--dist loadscope

pytest -n 4 --dist loadgroup

輸出

pytest --junitxml=<file>

輸出 JUnit 風格的 XML 報告（供 GitHub Actions、GitLab、Jenkins、CircleCI 使用）。

--junitxml=report.xml；--junit-xml=report.xml

pytest --junitxml=pytest-report.xml

pytest --html=<file>

產生自含 HTML 測試報告（pytest-html plugin）。

--html=report.html；--self-contained-html

pytest --html=report.html --self-contained-html

pytest --cov=<pkg>

在覆蓋率量測下執行測試（pytest-cov plugin）。搭配 `--cov-report=` 選擇輸出格式。

--cov=src；--cov-report=term；--cov-report=xml；--cov-report=html；--cov-fail-under=80

pytest --cov=src --cov-report=term-missing --cov-fail-under=80

監看／自動重跑

pytest --looponfail

每次存檔時重新執行失敗的測試直到通過（pytest 7+ 已棄用；改用 pytest-watch／pytest-xdist --loop-onfail）。

--looponfail

pytest --looponfail

ptw

以 watch 模式執行 pytest——每次檔案變更都重跑測試套件（pytest-watch，透過 pip 安裝）。

--clear；--runner 'pytest -x'；--now

ptw -- -x

設定

pytest -c <file>

覆寫 pytest 設定檔（預設 `pytest.ini`／`pyproject.toml [tool.pytest.ini_options]`／`tox.ini`／`setup.cfg`）。

-c pytest.ini；-c tests/pytest-cfg.ini

pytest -c tests/pytest-cfg.ini

pytest -p <plugin>

從 CLI 載入 plugin（例如 `pytest -p no:cacheprovider` 停用快取）。

-p django；-p asyncio；-p no:warnings；-p no:cacheprovider

pytest -p no:cacheprovider

除錯

pytest --trace

在第一個測試開始時進入 `pdb.set_trace()`（CLI 以外當機請用 `--trace-cli`）。

--trace；--trace-cli

pytest --trace tests/test_user.py::test_login

pytest --pdb

每當測試失敗或錯誤時自動啟動 pdb。

--pdb；--pdbcls=IPython.terminal.debugger.TerminalPdb

pytest --pdb -x

pytest --setup-show

執行時顯示 fixture 的 setup／teardown 追蹤（只追蹤不執行可用 `--setup-plan`）。

--setup-show；--setup-plan

pytest --setup-show tests/test_db.py

警告

pytest -W <filter>

把 Python 警告當作 pytest 引發一樣轉發。過濾器遵循 `-W` action 模組規格。

-W error；-W ignore::DeprecationWarning；-W default

pytest -W error::DeprecationWarning

pytest --strict-markers

把未註冊的 marker 視為錯誤——可抓出 `@pytest.mark.slow` 等拼字錯誤。

--strict-markers；--strict-config；--strict

pytest --strict-markers

非同步

pytest -p asyncio

註冊 pytest-asyncio plugin 以支援 `async def test_*` 函式。

-p asyncio；--asyncio-mode=auto

pytest --asyncio-mode=auto

雜項

pytest --rootdir=<dir>

覆寫 pytest 用於探索設定檔的專案根目錄。

--rootdir=.；--import-mode=importlib

pytest --rootdir=. tests/

商標與使用聲明

本批命令列工具速查手冊為開源社群參考資料。文中涉及的各工具的名稱、標識、商標（如 Git™、Docker™、Kubernetes®、kubectl、PostgreSQL®、MySQL®、Redis™、MongoDB®、Linux™、PowerShell™、Vim™ 等）均歸對應權利人所有，此處僅為識別與參考之目的使用。

本速查手冊的全部內容均為獨立編寫的簡化自包含參考，**與任何官方文件不存在隸屬、被認可或引用關係**。命令列表、參數說明、範例均為作者原創簡化表達；如需權威資訊，請參閱各工具的官方文件。

命令語法與參數可能在不同工具版本中有所差異。所示版本標籤對應穩定發佈版本；其他版本行為可能有所不同。本速查手冊**不代表**商標權利人的任何偏好或推薦。

如商標或版權方認為本站部分內容存在權益侵害，請發送電郵至[email protected]，我們在收到有效權屬證明後，會在合理期限內修改或移除相關內容。

本網站不對因使用本站資訊而產生的任何直接或間接損失承擔法律責任。

關於 pytest

pytest 是事實上的 Python 測試標準框架。它由 Holger Krekel 於 2008 年建立並發佈（最初是較舊 `py` 函式庫的後繼）。pytest 簡化了 Python 標準函式庫 `unittest` 的樣板——測試就是普通的 `def test_*():` 函式，無需類別樣板——並內建強大的 fixture 系統、parametrize、marker，以及豐富的 plugin 生態（pytest-cov、pytest-xdist、pytest-mock、pytest-django、pytest-asyncio、hypothesis 等）。目前穩定版線為 pytest 8+（8.3+）。pytest 透過預設命名規則（`test_*.py`／`*_test.py`）自動探索測試，以確定性順序執行，並在斷言失敗時產生豐富的 diff。pytest 也能執行 unittest／nose 風格的測試。常見的姊妹 CLI 為 `coverage`（執行 `coverage run -m pytest` 然後 `coverage report`）。pytest 不會上傳你的程式碼；所有測試執行都在本地。

速查頁版本 1.0.0