すべてのチートシートPython 開発

pytest

pytest 8+

pytest CLI のクイックリファレンス:テスト検出、選択、fixtures、markers、並列、parametrize、カバレッジ統合 — よく使うオプションと実用例をまとめました。

34 コマンド

ヘルプ

pytest --version

pytest バージョンと検出したインポートライブラリパスを表示します。

pytest --version

pytest --help

1 行の説明付きですべての 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

collect-only モード — 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

トレースバックスタイルを選択します: `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` xfails、`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

パラメタライズ / fixtures

pytest --fixtures

現在のテストスコープで可視のすべての fixture を一覧表示します(リポジトリルートから実行した場合はプロジェクト全体)。

--fixtures; --fixtures-per-test

pytest --fixtures -q

pytest --markers

定義されたすべての marker を一覧表示します(pytest.ini / pyproject.toml で登録済み)。

--markers

pytest --markers

並列

pytest -n <N>

`<N>` 個のワーカープロセス間でテストを並列実行します(pytest-xdist プラグイン)。CPU 数のワーカーには `auto` を使用します。

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

pytest -n auto

pytest --dist loadgroup

`@pytest.mark.group_*` markers でテストをグループ化します(xdist)— 単一のグループが単一のワーカーで実行されます — リソース競合するテストに便利です。

--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 プラグイン)。

--html=report.html; --self-contained-html

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

pytest --cov=<pkg>

カバレッジ測定下でテストを実行します(pytest-cov プラグイン)。出力形式を選択するには `--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

ウォッチモードで pytest を実行します — すべてのファイル変更でスイートを再実行します(pip 経由でインストールされる pytest-watch)。

--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 でプラグインをロードします(例: `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

実行中に fixtures のセットアップ / ティアダウントレースを表示します(実行なしのトレースには `--setup-plan` を使用)。

--setup-show; --setup-plan

pytest --setup-show tests/test_db.py

警告

pytest -W <filter>

pytest がそれらを発行したかのように Python 警告を転送します。フィルターは `-W` アクションモジュール仕様に従います。

-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 プラグインを登録して `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、markers、リッチなプラグインエコシステム(pytest-cov、pytest-xdist、pytest-mock、pytest-django、pytest-asyncio、hypothesis など)が付属しています。現在の安定版は pytest 8+(8.3+)。pytest は既定の命名規則(`test_*.py` / `*_test.py`)を介してテストを自動検出し、決定論的な順序で実行し、アサーション失敗時にリッチな diff を出力します。pytest は unittest / nose スタイルのテストも実行できます。一般的な companion CLI は `coverage` です(`coverage run -m pytest` を実行してから `coverage report`)。pytest はあなたのコードをアップロードしません; すべてのテスト実行はローカルです。

チートシートバージョン 1.0.0