【pytest】特定のテストだけを実行する方法！ファイル・クラス・関数ごとに解説

Pythonの単体テストで「修正した箇所だけ確認したいのに、全件実行で時間がかかる」と悩んでいませんか？テストコードが増えるほど、実行の効率化は不可欠です。

本記事では、pytestで特定のテストだけを指定して実行するコマンドを分かりやすく解説します。ファイルやクラス単位の指定から、便利なキーワード検索、マーカー機能まで網羅。状況に合わせた最適な実行手法をマスターして、開発スピードを劇的に向上させましょう。

記事のポイント

• ファイル・クラス・関数単位での指定に加え、「::」を繋ぐことで特定のメソッドまでピンポイントに実行できます。
• 「-k」オプションを使えば、テスト名に含まれるキーワードから柔軟に対象を絞り込んだり、特定のテストを除外したりできます。
• マーカー機能（-m）を活用することで、独自のタグを付けたグループ単位での一括実行が可能になり、テスト管理が容易になります。
• 前回失敗したテストのみを再実行する「—lf」や、実行時のログを表示する「-s」など、デバッグ効率を高める便利なオプションも紹介しています。
• 状況に応じた最適な実行コマンドを使い分けることで、無駄な待ち時間を減らし、開発サイクルを大幅に高速化できます。

pytestで特定のテストだけを効率的に実行する4つの指定方法

pytestは、プロジェクト全体ではなく 特定のテストだけ を選択して実行する柔軟な機能を備えています。開発中に修正した箇所の動作確認を素早く行うために、以下の4つの手法を使い分けるのが一般的です。これらをマスターすることで、テストの待ち時間を大幅に短縮し、開発サイクルを高速化できる可能性があります。

ファイル名やディレクトリを指定してテストを実行する

もっとも基本的な方法は、コマンドの引数にファイルパスやディレクトリパスを直接渡す方法です。

1
pytest tests/unit/
2

3
pytest tests/test_sample.py

特定のモジュールに関連するテストだけをまとめて確認したい場合に、もっとも直感的で使いやすい方法と言えるでしょう。

関数名やクラス名を「::」で繋いでピンポイントに実行する

ファイル内の特定のテスト関数やクラスだけを狙い撃ちしたい場合は、 「::」（ダブルコロン） を使ったノードID指定が便利です。

1
pytest tests/test_sample.py::test_success

クラス内の特定のメソッドだけを指定する方法

テストがクラス（TestClassなど）にまとめられている場合は、さらにコロンを繋いでメソッドを指定します。

1
pytest tests/test_sample.py::TestClass::test_method_one

複雑なテストファイルの中から、今まさにデバッグしている箇所だけを動かしたい時に重宝するでしょう。

キーワード表現「-k」オプションでテスト名の一部から絞り込む

テスト名の一部に共通のキーワードが含まれている場合、 「-k」オプション を使うことで柔軟にフィルタリングが可能です。論理演算子（and, or, not）を組み合わせることもできます。

-kオプション は 部分文字列マッチ と 論理式（and / or / not） を組み合わせたフィルタリング機能であり、正規表現ではありません。複数のテストを横断的に柔軟に絞り込む際に役立ちます。

マーカー機能「-m」を活用して独自のグループ単位で実行する

特定のカテゴリ（例：API連携、データベースアクセスを伴う重い処理など）ごとにテストを分類したい場合は、 マーカー機能（-mオプション） の活用が推奨されます。

カスタムマーカーを定義して特定のテストをタグ付けする

テストコード内で @pytest.mark.slow のようにデコレータを付与することで、独自のタグ付けが行えます。

1
import pytest
2

3
@pytest.mark.slow
4
def test_heavy_process():
5
    # 時間のかかる処理のテスト
6
    assert True

実行時は pytest -m slow と入力するだけで、マークされたテストのみが呼び出されます。

pytest.iniへのマーカー登録

カスタムマーカーを使用する際は、警告（PytestUnknownMarkWarning）を避けるために pytest.ini ファイルにマーカーを登録しておくのが一般的です。プロジェクトのルートディレクトリに pytest.ini を作成し、以下のように記述します。

1
[pytest]
2
markers =
3
    slow: marks tests as slow (deselect with '-m "not slow"')
4
    api: tests related to external APIs

このように登録しておくことで、チーム開発でも「どのようなマーカーが存在するのか」が明確になり、メンテナンス性が向上します。

pytestの特定テスト実行に関するよくある質問（FAQ）

pytestを利用して効率的に開発を進める中で、特定のテストだけを柔軟に制御したい場面は多々あります。ここでは、開発現場でよく寄せられる疑問とその解決策について詳しく解説します。

Q：前回失敗した特定のテストだけを優先して再実行するには？

大量のテストスイートを実行した際、修正後に 「失敗した箇所だけ」 を素早く確認したい場合があります。その際は、以下のキャッシュ機能を利用したオプションが便利です。

1
pytest --lf

これらのオプションを活用することで、修正と検証のサイクルを大幅に短縮できる可能性があります。

＼ITエンジニアにお勧めの一冊／

世界一流エンジニアの思考法

マイクロソフトで活躍する著者が教える、生産性を向上させるマインドセットと仕事術。

Amazonで詳細を見る

Q：特定のキーワードを含むテストだけを除外して実行することは可能？

「特定のテスト以外をすべて実行したい」というケースでは、 -k オプションと not 演算子を組み合わせる手法が有効です。

例えば、時間のかかる「integration（結合テスト）」という名前が含まれるテストをスキップして、単体テストのみを素早く実行したい場合は、次のように指定します。

1
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実行のコツ

特定のテストだけを実行する技術を習得したら、さらに一歩進んで 開発効率を最大化するための工夫 を取り入れてみるのが良いでしょう。以下のポイントを意識することで、デバッグやリファクタリングの質が向上する可能性があります。

• 「—lf（—last-failed）」との組み合わせ 特定のファイルやキーワードで絞り込んだ上で、さらに「前回失敗したテストだけ」を実行したい場合は、 pytest -k "keyword" --lf のように記述します。これにより、 ** 修正が正しく反映されたかを最短ルートで確認 ** できるでしょう。
• 「-v」オプションによる可視化 特定のテストに絞って実行する際は、 -v （verbose）オプションを付与して、どのテストメソッドが実行されているかを明示的に表示させるのが一般的です。意図しないテストまで実行されていないかをチェックするのに役立つでしょう。
• CI/CDでのマーカー活用 ローカル開発では -k による曖昧検索が便利ですが、CI（継続的インテグレーション）環境では、 カスタムマーカーを用いた厳密な制御 が推奨される傾向にあります。 slow マーカーが付いた重いテストを夜間ビルドに回すといった運用により、開発フローのボトルネックを解消できるかもしれません。

pytestの機能を最大限に引き出すことは、単にテストを楽にするだけでなく、 ソフトウェアの品質を高く保つための土台 になります。まずは身近な関数のピンポイント実行から始めて、徐々にプロジェクトに最適な実行スタイルを構築してみてはいかがでしょうか。

あわせて読みた関連記事：

• 【Python】unittest.mockでテストを効率化！使い方とMockオブジェクトの基本

【参考情報】

• Python公式ドキュメント（unittestとの比較）
• pytest documentation: Cache: working with last failures
• pytest documentation: How to run specific tests
• pytest documentation: Python test discovery

Kindle Unlimited

「読み放題」で知識の幅を広げる

1冊数千円する専門書から、ビジネス書、実用書、雑誌まで幅広いジャンルが定額で読み放題。ITスキルの向上はもちろん、日々の情報収集や教養を深めるのにも最適です。まずは30日間の無料体験から。

• 📚 技術書も月額定額で読み放題
• 📱 PC・タブレット・スマホでいつでもどこでも
• ✨ 30日間の無料体験

無料で30日間試してみる

Pythonユーザにお勧めの本

人気

スッキリわかるPython入門 第2版 スッキリわかるシリーズ

Amazonで詳細を見る 🔴 楽天で見る

独習Python

Amazonで詳細を見る 🔴 楽天で見る

Python1年生 第2版 体験してわかる！会話でまなべる！プログラミングのしくみ

Amazonで詳細を見る 🔴 楽天で見る