できない.dev

pytest で「fixture 'xxx' not found」が出てフィクスチャを使えない

fixture 'xxx' not found は、フィクスチャを上位の conftest.py へ移すか、プラグインを入れれば直る。
綴り違いも含め、pytest --fixtures の一覧で切り分けられる。

公開: 更新:

症状できない · exit 1
pytest -q
…
==================================== ERRORS ====================================
__________________________ ERROR at setup of test_get __________________________
file /tmp/tmp.TRocSsq3g3/tests/api/test_api.py, line 1
  def test_get(client):
解決後できた · exit 0
pytest -q
...                                                                      [100%]
3 passed in 0.01s

2026-10-24 に python:3.12(pytest 8.4.2) で実際に打って取った出力。検証環境の詳細

要約

テスト関数の引数に書いた名前のフィクスチャが見つからないと、テストは実行前のセットアップで ERROR になる。

file /app/tests/api/test_api.py, line 1
  def test_get(client):
E       fixture 'client' not found
>       available fixtures: cache, capfd, capfdbinary, caplog, capsys, ...
>       use 'pytest --fixtures [testpath]' for help on them.

公式ドキュメントのとおり、フィクスチャが使えるかどうかは「テストの側から見て、定義された範囲に入っているか」で決まる。
conftest.py に書いたフィクスチャは、その conftest.py があるディレクトリとその配下のテストにだけ見える。
available fixtures の一覧に目的の名前が無ければ、定義はテストから見えていない。

実行例

conftest.py を兄弟ディレクトリの tests/db/ に置いたままだと、tests/api/ のテストは fixture 'client' not found で ERROR になる。
pytest-mock を入れていない mocker も、同じ ERROR になる。
conftest.py を tests/ へ移して pytest-mock を入れると、3 本とも通る。

$ pytest -q
E.E                                                                      [100%]
==================================== ERRORS ====================================
__________________________ ERROR at setup of test_get __________________________
file /tmp/tmp.TRocSsq3g3/tests/api/test_api.py, line 1
  def test_get(client):
E       fixture 'client' not found
>       available fixtures: cache, capfd, capfdbinary, caplog, capsys, capsysbinary, capteesys, doctest_namespace, monkeypatch, pytestconfig, record_property, record_testsuite_property, record_xml_attribute, recwarn, tmp_path, tmp_path_factory, tmpdir, tmpdir_factory
>       use 'pytest --fixtures [testpath]' for help on them.
 
/tmp/tmp.TRocSsq3g3/tests/api/test_api.py:1
__________________________ ERROR at setup of test_cwd __________________________
file /tmp/tmp.TRocSsq3g3/tests/test_mock.py, line 4
  def test_cwd(mocker):
E       fixture 'mocker' not found
>       available fixtures: cache, capfd, capfdbinary, caplog, capsys, capsysbinary, capteesys, doctest_namespace, monkeypatch, pytestconfig, record_property, record_testsuite_property, record_xml_attribute, recwarn, tmp_path, tmp_path_factory, tmpdir, tmpdir_factory
>       use 'pytest --fixtures [testpath]' for help on them.
 
/tmp/tmp.TRocSsq3g3/tests/test_mock.py:4
=========================== short test summary info ============================
ERROR tests/api/test_api.py::test_get
ERROR tests/test_mock.py::test_cwd
1 passed, 2 errors in 0.01s
$ echo $?
1
$ mv tests/db/conftest.py tests/conftest.py
$ pytest --fixtures tests/api/test_api.py | grep -A1 'from conftest'
------------------------ fixtures defined from conftest ------------------------
client -- tests/conftest.py:5
$ pip install pytest-mock
$ pytest -q
...                                                                      [100%]
3 passed in 0.01s
$ echo $?
0

— 2026-10-24 時点の出力

検証環境Python 3.12.15 / Git 2.47.3 / pytest 8.4.2 / 2026-10-24 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.15
  • Git 2.47.3
  • pytest 8.4.2

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. conftest.py を共通の上位ディレクトリへ移す

フィクスチャを使うテストが tests/api/ と tests/db/ にまたがるなら、両方を含む tests/ に置く。

tests/
├── conftest.py      # client はここに置く
├── api/
│   └── test_api.py
└── db/
    └── test_db.py

conftest.py のフィクスチャは、テストファイル側で import しなくても使える。
階層ごとに conftest.py を置いた場合は、各階層のフィクスチャがその配下のテストに加わる。

2. 共有するフィクスチャは conftest.py に書く

# tests/conftest.py
import pytest
 
 
@pytest.fixture
def user():
    return {"name": "alice"}

1 つのテストファイルでしか使わないフィクスチャは、そのファイルに置いたままでよい。

3. プラグインを依存に入れる

pip install pytest-mock

プラグインのフィクスチャは、インストールするだけでテスト全体から使えるようになる。
requirements-dev.txt などの開発用依存にも書いておく。

4. 見えているフィクスチャを一覧で確かめる

pytest --fixtures tests/api/test_api.py

fixtures defined from conftest の見出しの下に、名前と定義場所(client -- tests/conftest.py:3 のような形)が並ぶ。
ここに出てこなければ、そのテストからは見えていない。
名前が出ているのに not found になるなら、テスト側の引数の綴りを確かめる。

よくある原因

  1. conftest.py の場所がずれている。
    tests/db/conftest.py に書いたフィクスチャは、tests/api/test_api.py からは見えない。
    兄弟のディレクトリは範囲の外になる。
  2. テストファイルの中で定義している。
    test_one.py に書いたフィクスチャは test_one.py のテストだけが使える。
    同じディレクトリの test_two.py から要求すると not found になる。
    クラスの中で定義したフィクスチャも、そのクラスのテストに限られる。
  3. プラグインを入れていない。
    mocker は pytest-mock が提供するフィクスチャで、pytest 本体には無い。
    CI 用の依存に入れ忘れると、手元では通るのに CI だけ落ちる。
  4. 名前の綴りが違う。
    引数 clinet はフィクスチャ client とは別物として扱われる。
    ファイル名を conftest.py 以外(confest.py など)にすると、中身は読み込まれない。