Pythonの単体テストで「修正した箇所だけ確認したいのに、全件実行で時間がかかる」と悩んでいませんか？テストコードが増えるほど、実行の効率化は不可欠です。
本記事では、pytestで特定のテストだけを指定して実行するコマンドを分かりやすく解説します。ファイルやクラス単位の指定から、便利なキーワード検索、マーカー機能まで網羅。状況に合わせた最適な実行手法をマスターして、開発スピードを劇的に向上させましょう。
記事のポイント
- ファイル・クラス・関数単位での指定に加え、「::」を繋ぐことで特定のメソッドまでピンポイントに実行できます。
- 「-k」オプションを使えば、テスト名に含まれるキーワードから柔軟に対象を絞り込んだり、特定のテストを除外したりできます。
- マーカー機能（-m）を活用することで、独自のタグを付けたグループ単位での一括実行が可能になり、テスト管理が容易になります。
- 前回失敗したテストのみを再実行する「—lf」や、実行時のログを表示する「-s」など、デバッグ効率を高める便利なオプションも紹介しています。
- 状況に応じた最適な実行コマンドを使い分けることで、無駄な待ち時間を減らし、開発サイクルを大幅に高速化できます。
pytestで特定のテストだけを効率的に実行する4つの指定方法
pytestは、プロジェクト全体ではなく 特定のテストだけ を選択して実行する柔軟な機能を備えています。開発中に修正した箇所の動作確認を素早く行うために、以下の4つの手法を使い分けるのが一般的です。これらをマスターすることで、テストの待ち時間を大幅に短縮し、開発サイクルを高速化できる可能性があります。
ファイル名やディレクトリを指定してテストを実行する
もっとも基本的な方法は、コマンドの引数にファイルパスやディレクトリパスを直接渡す方法です。
pytest tests/unit/
pytest tests/test_sample.py特定のモジュールに関連するテストだけをまとめて確認したい場合に、もっとも直感的で使いやすい方法と言えるでしょう。
関数名やクラス名を「::」で繋いでピンポイントに実行する
ファイル内の特定のテスト関数やクラスだけを狙い撃ちしたい場合は、 「::」（ダブルコロン） を使ったノードID指定が便利です。
pytest tests/test_sample.py::test_successクラス内の特定のメソッドだけを指定する方法
テストがクラス（TestClassなど）にまとめられている場合は、さらにコロンを繋いでメソッドを指定します。
pytest tests/test_sample.py::TestClass::test_method_one複雑なテストファイルの中から、今まさにデバッグしている箇所だけを動かしたい時に重宝するでしょう。
キーワード表現「-k」オプションでテスト名の一部から絞り込む
テスト名の一部に共通のキーワードが含まれている場合、 「-k」オプション を使うことで柔軟にフィルタリングが可能です。論理演算子（and, or, not）を組み合わせることもできます。
| コマンド例 | 実行されるテストの条件 |
|---|---|
pytest -k "login" | テスト名や nodeid（ファイル名・クラス名・関数名）に “login” を含むテスト |
pytest -k "login or logout" | “login” または “logout” を含むテスト |
pytest -k "not login" | “login” を含まないテスト |
-kオプション は 部分文字列マッチ と 論理式（and / or / not） を組み合わせたフィルタリング機能であり、正規表現ではありません。複数のテストを横断的に柔軟に絞り込む際に役立ちます。
マーカー機能「-m」を活用して独自のグループ単位で実行する
特定のカテゴリ（例：API連携、データベースアクセスを伴う重い処理など）ごとにテストを分類したい場合は、 マーカー機能（-mオプション） の活用が推奨されます。
カスタムマーカーを定義して特定のテストをタグ付けする
テストコード内で @pytest.mark.slow のようにデコレータを付与することで、独自のタグ付けが行えます。
import pytest
@pytest.mark.slowdef test_heavy_process(): # 時間のかかる処理のテスト assert True実行時は pytest -m slow と入力するだけで、マークされたテストのみが呼び出されます。
pytest.iniへのマーカー登録
カスタムマーカーを使用する際は、警告（PytestUnknownMarkWarning）を避けるために pytest.ini ファイルにマーカーを登録しておくのが一般的です。プロジェクトのルートディレクトリに pytest.ini を作成し、以下のように記述します。
[pytest]markers = slow: marks tests as slow (deselect with '-m "not slow"') api: tests related to external APIsこのように登録しておくことで、チーム開発でも「どのようなマーカーが存在するのか」が明確になり、メンテナンス性が向上します。
pytestの特定テスト実行に関するよくある質問（FAQ）
pytestを利用して効率的に開発を進める中で、特定のテストだけを柔軟に制御したい場面は多々あります。ここでは、開発現場でよく寄せられる疑問とその解決策について詳しく解説します。
Q：前回失敗した特定のテストだけを優先して再実行するには？
大量のテストスイートを実行した際、修正後に 「失敗した箇所だけ」 を素早く確認したい場合があります。その際は、以下のキャッシュ機能を利用したオプションが便利です。
| オプション | 実行内容 |
|---|---|
--lf (--last-failed) | 前回失敗したテストのみを再実行する |
--ff (--failed-first) | 前回失敗したテストを最初に実行し、その後残りのテストを続ける |
pytest --lfこれらのオプションを活用することで、修正と検証のサイクルを大幅に短縮できる可能性があります。
Q：特定のキーワードを含むテストだけを除外して実行することは可能？
「特定のテスト以外をすべて実行したい」というケースでは、 -k オプションと not 演算子を組み合わせる手法が有効です。
例えば、時間のかかる「integration（結合テスト）」という名前が含まれるテストをスキップして、単体テストのみを素早く実行したい場合は、次のように指定します。
pytest -k "not integration"複数の条件を組み合わせることも可能で、 pytest -k "not integration and not slow" のように記述することで、 特定の条件に合致するテストを柔軟に除外 できます。
Q：特定のテスト実行時だけ標準出力（print内容）を確認したい場合は？
デフォルトの設定では、 pytestはテスト成功時の標準出力（ print() 関数などの内容）をキャプチャし、通常は失敗時のみ表示します。デバッグ中に特定のテストの挙動を詳しく追いたい場合は、 -s オプションを使用するのが一般的です。
- 実行例：
pytest tests/test_sample.py -s
このオプションを付与することで、テストコード内に記述した print文の内容がリアルタイムでコンソールに表示 されるようになります。特定のテスト関数に絞り込んで実行するコマンドと組み合わせることで、デバッグ作業の効率化が期待できるでしょう。
まとめ：状況に合わせたpytestの特定テスト実行手法
今回のまとめ：振り返りチェックリスト
- 「::」で繋ぐパス指定をマスターして、修正したコードに関連するテストだけを最小単位で実行する習慣をつける
- キーワード検索（-k）やマーカー（-m） を使い分け、特定の機能群やタグ付けしたグループを一括で効率よく検証する
- 「—lf」での失敗テスト再実行や「-s」でのログ確認など、便利なオプションを組み合わせてデバッグの回転数を上げる
- アドバイス： まずは次のデバッグの際、いつもの「pytest」コマンドに「-k」や「::」を一つ付け加えるところから始めて、開発のリズムを劇的に速めていきましょう！
pytestは、非常に柔軟なテスト選択機能を備えています。開発のフェーズや目的に応じて、最適な実行コマンドを使い分けることで、 無駄な待ち時間を減らし、開発サイクルを高速化させる ことが期待できるでしょう。
今回ご紹介した主要な実行方法を、以下の表にまとめました。
| 実行対象 | コマンド例 | 主な活用シーン |
|---|---|---|
| ディレクトリ・ファイル | pytest tests/api/ | 特定の機能群をまとめて確認したい場合 |
| クラス・関数（::） | pytest test_file.py::test_func | 修正箇所の挙動をピンポイントで確認したい場合 |
| キーワード（-k） | pytest -k "login" | 命名規則に基づき、関連テストを横断的に実行したい場合 |
| マーカー（-m） | pytest -m "smoke" | 実行速度やテストの種類でグループ分けしたい場合 |
| 失敗テスト再実行 | pytest --lf | 前回失敗したテストのみを素早く検証したい場合 |
| 出力確認（-s） | pytest tests/test_file.py -s | デバッグ時にprint文の内容をリアルタイムで確認したい場合 |
これらの手法を組み合わせることで、数千件規模のテストスイートを持つプロジェクトであっても、必要なテストのみを実行することで、テスト時間を大幅に短縮できる可能性があります（実行時間はテスト内容や外部依存の有無によって変動します）。
開発効率を最大化するpytest実行のコツ
特定のテストだけを実行する技術を習得したら、さらに一歩進んで 開発効率を最大化するための工夫 を取り入れてみるのが良いでしょう。以下のポイントを意識することで、デバッグやリファクタリングの質が向上する可能性があります。
- 「—lf（—last-failed）」との組み合わせ
特定のファイルやキーワードで絞り込んだ上で、さらに「前回失敗したテストだけ」を実行したい場合は、
pytest -k "keyword" --lfのように記述します。これにより、 ** 修正が正しく反映されたかを最短ルートで確認 ** できるでしょう。 - 「-v」オプションによる可視化
特定のテストに絞って実行する際は、
-v（verbose）オプションを付与して、どのテストメソッドが実行されているかを明示的に表示させるのが一般的です。意図しないテストまで実行されていないかをチェックするのに役立つでしょう。 - CI/CDでのマーカー活用
ローカル開発では
-kによる曖昧検索が便利ですが、CI（継続的インテグレーション）環境では、 カスタムマーカーを用いた厳密な制御 が推奨される傾向にあります。slowマーカーが付いた重いテストを夜間ビルドに回すといった運用により、開発フローのボトルネックを解消できるかもしれません。
pytestの機能を最大限に引き出すことは、単にテストを楽にするだけでなく、 ソフトウェアの品質を高く保つための土台 になります。まずは身近な関数のピンポイント実行から始めて、徐々にプロジェクトに最適な実行スタイルを構築してみてはいかがでしょうか。
あわせて読みた関連記事：
【参考情報】
- Python公式ドキュメント（unittestとの比較）
- pytest documentation: Cache: working with last failures
- pytest documentation: How to run specific tests
- pytest documentation: Python test discovery
Pythonユーザにお勧めの本
言語仕様を深く解説。なんとなく書ける状態から、自信を持って書ける状態へ引き上げてくれます。
Python1年生 第2版 体験してわかる！会話でまなべる！プログラミングのしくみ
イラスト中心で、プログラミングの楽しさを教えてくれる。ワクワクしながら学べる入門書です。
以上で本記事の解説を終わります。
よいITライフを！
Pythonユーザにお勧めの本
スッキリわかるPython入門 第2版 スッキリわかるシリーズ
対話形式でスラスラ読める。複雑な概念もキャラクターが分かりやすく解説してくれます。
人気記事
- 1
- 2
- 3
- 4
- 5
ストレス社会で働くITエンジニアの休息に
対話形式でスラスラ読める。複雑な概念もキャラクターが分かりやすく解説してくれます。