pytest でテストが見つからず実行できない(collected 0 items / no tests ran)
pytest は命名規則に合うファイル・関数・クラスだけを集める。
test_*.py か *_test.py のファイル、test で始まる関数、__init__ の無い Test で始まるクラスに揃え、pytest --collect-only で何が集まるかを確かめる。
公開: 更新:
pytest ============================= test session starts ============================== platform linux -- Python 3.12.15, pytest-8.4.2, pluggy-1.7.0 rootdir: /tmp/tmp.IMURlUeF5w collected 0 items ============================ no tests ran in 0.00s =============================
pytest -q ... [100%] 3 passed in 0.00s
2026-10-25 に python:3.12(pytest 8.4.2) で実際に打って取った出力。検証環境の詳細
要約
テストを書いたのに、pytest が 1 件も実行しないまま終わる。
============================= test session starts ==============================
rootdir: /app
collected 0 items
============================ no tests ran in 0.00s =============================pytest は、決まった命名規則に合うものだけをテストとして集める。
既定の規則は次のとおりだ。
- ファイル:
test_*.pyまたは*_test.py - 関数: 名前が
testで始まるもの(クラスの外) - クラス: 名前が
Testで始まり、__init__を持たないもの。
その中のtestで始まるメソッドが対象になる
1 件も集まらないとき、pytest は終了コード 5 で終わる。
CI ではこれが失敗として扱われるので、「テストは通っているはずなのにジョブが赤い」という形でも気付く。
実行例
pytest 8.4.2 では、ファイル名が check_math.py のままだと collected 0 items になり、終了コードは 5 で終わる。
ファイル名を直しても、関数名が check_ で始まりテストクラスに __init__ があると 0 件のままで、PytestCollectionWarning が出る。
名前を揃えて前準備を setup_method に移すと、2 件が集まって通る。python_files に check_*.py だけを書くと test_*.py が外れて 1 件しか集まらないが、並べて書くと 3 件とも通る。
$ pytest
============================= test session starts ==============================
platform linux -- Python 3.12.15, pytest-8.4.2, pluggy-1.7.0
rootdir: /tmp/tmp.IMURlUeF5w
collected 0 items
============================ no tests ran in 0.00s =============================
$ echo $?
5$ pytest --collect-only -q
=============================== warnings summary ===============================
tests/test_math.py:5
/tmp/tmp.IMURlUeF5w/tests/test_math.py:5: PytestCollectionWarning: cannot collect test class 'TestThing' because it has a __init__ constructor (from: tests/test_math.py)
class TestThing:
-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
no tests collected in 0.00s
$ echo $?
5$ pytest --collect-only -q
tests/test_math.py::test_add
tests/test_math.py::TestThing::test_x
2 tests collected in 0.00s$ pytest -q
.. [100%]
2 passed in 0.00s
$ echo $?
0$ cat pytest.ini
[pytest]
python_files = check_*.py$ pytest --collect-only -q
tests/check_extra.py::test_extra
1 test collected in 0.00s$ cat pytest.ini
[pytest]
python_files = test_*.py check_*.py$ pytest -q
... [100%]
3 passed in 0.00s
$ echo $?
0— 2026-10-25 時点の出力
検証環境Python 3.12.15 / Git 2.47.3 / pytest 8.4.2 / 2026-10-25 検証
- 検証日
- 実行環境
python:3.12Debian GNU/Linux 13 (trixie)- バージョン
- Python 3.12.15
- Git 2.47.3
- pytest 8.4.2
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. 名前を規則に揃える
# tests/test_calc.py
def test_add():
assert 1 + 1 == 2
class TestCalc:
def test_sub(self):
assert 2 - 1 == 12. クラスの前準備は init 以外で行う
テストクラスではインスタンスの初期化を pytest に任せる。
前準備はフィクスチャか、各テストの前に呼ばれる setup_method に書く。
class TestThing:
def setup_method(self):
self.x = 1
def test_x(self):
assert self.x == 13. 収集結果を先に確かめる
pytest --collect-only -qテストを実行せずに、集まったテストの一覧だけを表示する。
0 件なら no tests collected と出るので、名前を直すたびにこれで確かめる。
4. 独自の命名を使うなら既定も並べて書く
check_*.py も集めたい場合は、python_files に既定の test_*.py と並べて書く。
# pytest.ini
[pytest]
python_files = test_*.py check_*.py既定の規則は、python_files を書いた時点で使われなくなる。check_*.py だけを書くと、今度は test_*.py が集まらなくなる。
よくある原因
- ファイル名が規則に合っていない。
check_math.pyやtests.pyは収集されない。 - 関数名・クラス名が規則に合っていない。
def check_add():やclass UserTest:は、ファイル名が正しくても対象にならない。 - テストクラスに
__init__がある。
クラスごと外され、PytestCollectionWarning: cannot collect test class 'TestThing' because it has a __init__ constructorという警告だけが出る。
警告の一覧は結果の下にまとめて出るので見落としやすい。 - 設定や引数で外している。
python_filesに独自のパターンだけを書いた、norecursedirsにtestsを入れた、-kの条件にどのテストも合わない、のいずれでも 0 件になる(-kのときは1 deselectedのように表示される)。