【Python】pytest fixtureの使い方!前処理・後処理を解説

【Python】pytest fixtureの使い方!前処理・後処理を解説

PR Amazonのアソシエイトとして、ITナレッジライフは適格販売により収入を得ています。

記事の文字数:5,882 / 総アクセス数:2 views

Pythonのテストフレームワークpytestにおけるfixture(フィクスチャ)の使い方を徹底解説!基本構文からyieldを使った前処理・後処理、実行単位を制御するscope設定、conftest.pyによるファイル間の共通化、組み込みfixtureの活用法まで実機検証コード付きで紹介します。

Pythonユーザにお勧めの本 ↗

初心者向け

1週間でPythonの基礎が学べる本

難易度
実用性
読みやすさ

「絶対に挫折させない」という著者の強い意志を感じる、プログラミングの「最初の1冊」としておすすめできる良書です。

人気

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

難易度
実用性
読みやすさ

対話形式でスラスラ読める。複雑な概念もキャラクターが分かりやすく解説してくれます。

独習Python

難易度
実用性
網羅性

言語仕様を深く解説。なんとなく書ける状態から、自信を持って書ける状態へ引き上げてくれます。

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

難易度
実用性
読みやすさ

イラスト中心で、プログラミングの楽しさを教えてくれる。ワクワクしながら学べる入門書です。

PythonPython [パイソン]汎用プログラミング言語で単体テストを記述していると、「テスト用のダミーデータ作成」や「データベース接続の初期化・切断」といった同じ準備コードが各テスト関数に重複してしまい、管理が煩雑になることがあります。

Pythonの代表的なテストフレームワークである pytest では、 fixture(フィクスチャ) と呼ばれる機能を使うことで、テスト実行前の準備処理(Setup)や実行後の片付け処理(Teardown)をテスト本体からきれいに分離・共通化できます。なお、特定のテスト関数やファイルだけを選んで実行する方法については pytestで特定のテストだけを実行する方法 でも詳しく解説しています。

この記事では、@pytest.fixture の基本的な書き方から、yield を使った前処理・後処理の実装、scope による実行回数の制御、conftest.py を用いた複数ファイル間での共有、さらに実務で役立つ組み込みフィクスチャの活用法まで、実機で検証したコード例とともに分かりやすく解説します。

この記事でわかること

  • pytest の fixture(フィクスチャ)の役割と @pytest.fixture の基本構文
  • yield を使ってテストの前処理(Setup)と後処理(Teardown)を記述する方法
  • scope 引数(function, class, module, package, session)による実行単位の制御
  • conftest.py を使ってインポート不要で複数テストファイル間に fixture を共有する方法
  • params によるパラメータ化テストと、標準搭載の組み込み fixture(tmp_path など)の使い方

確認した環境

本記事で解説するコードおよび出力結果は、以下の環境で動作を確認しています。

※ Python 3.9は2025年10月31日にサポートが終了しています。本記事の環境は動作検証時のものです。新規開発では、サポート期間内のPythonバージョンの利用を推奨します。

pytestのfixture(フィクスチャ)とは?

fixture(フィクスチャ)とは、テストを実行するために必要な 前提条件・初期データ・外部リソースの準備と後片付けを担う仕組み です。

従来の unittest モジュール(詳細は Pythonのunittestとmockの使い方 を参照)では、クラス内の setUp() や tearDown() メソッドに前処理・後処理を記述するのが一般的でした。しかしこの方式では、クラス内のすべてのテストメソッドに対して同じ前処理が実行されるため、「特定のテストにだけこのデータを渡したい」「複数の前処理を柔軟に組み合わせたい」といったケースでコードが複雑になりやすい課題がありました。

pytest の fixture を活用すると、以下のメリットが得られます。

  • 依存性の明示的な注入: 必要な fixture の関数名をテスト関数の引数に書くだけで、自動的に前処理が実行され戻り値を受け取れる
  • 高い再利用性: 複数の fixture を組み合わせたり、別ファイルのテストから共通利用したりできる
  • 後処理の安全な実行: 前処理が完了していれば、テスト本体の途中でアサーションエラーや例外が発生しても、定義したクリーンアップ処理(Teardown)を確実に実行できる
flowchart LR A["1. 前処理 (Setup)
データ作成・リソース初期化"] --> B["2. テスト実行 (Test)
引数としてデータを受け取り検証"] B --> C["3. 後処理 (Teardown)
リソース解放・一時データ削除"]
スポンサーリンク

@pytest.fixtureの基本的な使い方

fixture を使う最も基本的な手順は、準備用の関数に @pytest.fixture デコレータ(デコレータの仕組みは Pythonデコレータの解説 を参照)を付与し、その 関数名をテスト関数の引数として指定する だけです。

テストデータを供給する基本コード例

以下の例では、テスト用のユーザー辞書データ(Pythonの辞書操作は Python辞書の使い方 を参照)を返す sample_user フィクスチャを定義し、2つのテスト関数から利用しています。

test_basic.py
import pytest
@pytest.fixture
def sample_user():
# テストごとに新しい辞書データを生成して返す
return {"id": 1, "name": "Alice", "role": "admin"}
def test_user_name(sample_user):
assert sample_user["name"] == "Alice"
def test_user_role(sample_user):
assert sample_user["role"] == "admin"

pytest -v コマンドでこのテストファイルを実行すると、以下のように各テスト関数に対して sample_user() が自動的に呼び出され、その戻り値が引数として渡されます。

Terminal window
pytest test_basic.py -v

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 2 items
test_basic.py::test_user_name PASSED [ 50%]
test_basic.py::test_user_role PASSED [100%]
============================== 2 passed in 0.01s ===============================

デフォルトでは、テスト関数が1つ実行されるたびに sample_user() が新しく呼び出されます。そのため、一方のテスト関数内で辞書の中身を書き換えたとしても、もう一方のテスト関数には影響せず、テスト間の独立性が保たれます。

yieldを使った前処理(Setup)と後処理(Teardown)の実装

データベース接続のクローズや一時ファイルの削除など、テスト終了後に必ず 後処理(Teardown) を行いたい場合は、fixture 関数内で return の代わりに yield を使用します。

yield前後の実行順序の仕組み

fixture 関数内で yield を使うと、処理のタイミングが以下のように分かれます。

  1. yield より前の記述: テスト関数が実行される直前に 前処理(Setup) として実行される
  2. yield <値> の部分: 指定した <値> がテスト関数の引数に渡され、テスト本体が実行される(値を渡さない場合は yield のみ記述可能)
  3. yield より後の記述: fixture のスコープに応じた終了タイミングで 後処理(Teardown) として実行される。デフォルトの function スコープでは、テスト関数の実行終了後に実行される

実際に標準出力を表示する -s オプションを付けて、前処理・テスト本体・後処理の実行順序を確認してみましょう。

test_yield.py
import pytest
@pytest.fixture
def db_connection():
print("\n[Setup] DB接続を開始します")
conn = {"connected": True, "records": ["item1", "item2"]}
yield conn
print("\n[Teardown] DB接続をクローズします")
conn["connected"] = False
def test_fetch_records(db_connection):
print(" -> テスト実行中: レコード件数の検証")
assert db_connection["connected"] is True
assert len(db_connection["records"]) == 2
Terminal window
pytest test_yield.py -v -s

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 1 item
test_yield.py::test_fetch_records
[Setup] DB接続を開始します
-> テスト実行中: レコード件数の検証
PASSED
[Teardown] DB接続をクローズします
============================== 1 passed in 0.01s ===============================

出力結果から、[Setup] → テスト実行中 → PASSED → [Teardown] の順に処理が進んでいることがわかります。

[!TIP] テストが失敗しても後処理は実行される yield までの前処理(Setup)が正常に完了していれば、テスト関数内の assert が失敗したり例外が発生したりしても、yield より後の後処理(Teardown)はスキップされずに実行されます。with 文(コンテキストマネージャ)と組み合わせて with open(...) as f: yield f のように記述することも可能です。

ただし、前処理の途中で例外が発生して yield に到達しなかった場合、その fixture の後処理は実行されません(すでに正常にセットアップが完了していた別の fixture の後処理は実行されます)。データベース接続や外部リソースの初期化処理では、この点にも注意が必要です。

スポンサーリンク

scope引数でfixtureの実行単位(スコープ)を制御する

デフォルトの fixture はテスト関数ごとに毎回実行されますが、データベースのコンテナ起動や重い初期データのロードなど、毎回実行するとテスト全体の時間が長くなる処理もあります。

そのような場合は、@pytest.fixture(scope="...") のように scope 引数 を指定することで、fixture の生成・破棄を行う単位(スコープ)を変更できます。

指定可能な5つのスコープ一覧

pytest で指定できる scope の種類と実行タイミングは以下の5段階です(参照: pytest公式ドキュメント: Fixture scopes)。

スコープ名実行・破棄される単位主な用途
function (デフォルト)テスト関数ごとに1回通常のテストデータ生成、副作用を分離したい処理
classテストクラスごとに1回同一クラス内のメソッド間で状態を共有したい場合
moduleテストファイル(.py)ごとに1回ファイル内で共通利用するAPIAPI [エーピーアイ]Application Programming Interface。異なるソフトウェア間の接続口クライアントやDBテーブル準備
packagefixtureが定義されたパッケージ内のテストで共有(サブパッケージを含む)パッケージ単位での共通リソース初期化
sessionpytest コマンド実行全体で1回DockerDocker [ドッカー]コンテナ型仮想化プラットフォームコンテナ起動、テスト用DBのスキーマ作成など重い処理

scope=“module” の動作検証

scope="module" を指定した場合に、同じファイル内の2つのテスト関数で1度だけ初期化が行われることを確認してみましょう。

test_scope.py
import pytest
@pytest.fixture(scope="module")
def shared_resource():
print("\n[Setup] モジュール共通リソースを初期化")
return {"count": 0}
def test_first(shared_resource):
assert shared_resource["count"] == 0
def test_second(shared_resource):
assert shared_resource["count"] == 0
Terminal window
pytest test_scope.py -v -s

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 2 items
test_scope.py::test_first
[Setup] モジュール共通リソースを初期化
PASSED
test_scope.py::test_second PASSED
============================== 2 passed in 0.01s ===============================

[Setup] モジュール共通リソースを初期化 は最初の test_first の直前に1回だけ出力されます。test_second でも同じ fixture が利用され、[Setup] モジュール共通リソースを初期化 が1回しか出力されないことから、同じモジュール内で fixture のインスタンスが共有されていることが確認できます。

[!WARNING] 広いスコープでの状態変更(ミューテーション)に注意 module や session スコープの fixture が返すオブジェクトを特定のテスト関数内で書き換えてしまうと、後続のテスト結果が実行順序に依存する原因になります。広いスコープを使う際は、読み取り専用のデータにするか、各テスト関数用の子 fixture(function スコープ)でトランザクションのロールバックを行う設計が推奨されます。

conftest.pyで複数テストファイル間にfixtureを共有する

プロジェクトが大きくなりテストファイルが複数に分かれると、同じ fixture を複数のファイルで使いたくなります。その際に各テストファイルで fixture を import するのは非推奨であり、pytest では conftest.py という特別な名前のファイルに fixture を配置します。

conftest.pyの仕組みとコード例

テストディレクトリに conftest.py を作成して fixture を定義しておくと、pytest が実行時に自動的にそのファイルを読み込みます。同じディレクトリおよび配下のサブディレクトリにあるすべてのテストファイルから、 import 文なしで直接引数に指定して利用 できます。

conftest.py
import pytest
@pytest.fixture
def app_config():
return {"env": "test", "timeout": 5}

同じディレクトリにある test_service.py から、import なしで app_config を呼び出してみます。

test_service.py
def test_config_env(app_config):
assert app_config["env"] == "test"
assert app_config["timeout"] == 5
Terminal window
pytest test_service.py -v

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 1 item
test_service.py::test_config_env PASSED [100%]
============================== 1 passed in 0.01s ===============================

このように、プロジェクト全体で使う共通 fixture はルート直下の tests/conftest.py に置き、特定の機能(例: APIテストのみ)で使う fixture は tests/api/conftest.py に配置するといった階層管理が可能です。

スポンサーリンク

実務で役立つfixtureの応用テクニックと組み込み機能

最後に、実務のテストコードで頻繁に使われるオプション設定と、pytest に標準搭載されている便利な組み込み fixture を紹介します。

1. params引数でfixtureをパラメータ化する

同じ前処理ロジックに対して複数の異なる入力パターンをテストしたい場合は、@pytest.fixture(params=[...]) を指定し、引数に組み込みの request オブジェクトを受け取って request.param を返します。

test_params.py
import pytest
@pytest.fixture(params=[100, 250, 500])
def price(request):
return request.param
def test_tax_included(price):
tax_included = int(price * 1.1)
assert tax_included > price
Terminal window
pytest test_params.py -v

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 3 items
test_params.py::test_tax_included[100] PASSED [ 33%]
test_params.py::test_tax_included[250] PASSED [ 66%]
test_params.py::test_tax_included[500] PASSED [100%]
============================== 3 passed in 0.01s ===============================

1つのテスト関数から [100], [250], [500] の3件のテストケースが自動生成され、それぞれ独立して判定されます。

2. autouse=Trueで引数指定なしに自動適用する

すべてのテスト関数に対して無条件で適用したい前処理(環境変数のリセットやロガーの初期化など)がある場合は、@pytest.fixture(autouse=True) を指定します。

import pytest
@pytest.fixture(autouse=True)
def setup_clean_env():
# 各テスト関数の前に自動で実行される処理
yield
# 各テスト関数の後に自動で実行される処理

autouse=True を設定すると、テスト関数の引数に fixture 名を書かなくても対象スコープ内の全テストに自動適用されます。ただし、テスト関数側を見ただけではどの前処理が動いているか判別しにくくなるため、本当に全テストで必要な処理に限定して使うのが無難です。

3. 組み込みfixture(tmp_path・monkeypatch・capsys)の活用

pytest には、自作しなくても最初から引数に書くだけで使える 組み込み fixture(Built-in fixtures) が多数用意されています。代表的なものは以下の3つです。

  • tmp_path: テスト関数ごとに独立した一時ディレクトリを pathlib.Path オブジェクトとして提供する。デフォルトでは直近3回分のテスト実行セッションのディレクトリが保持され、古いものは自動的に整理されるため、通常は手動削除が不要
  • monkeypatch: 環境変数(monkeypatch.setenv)や辞書、オブジェクトの属性などをそのテストの間だけ安全に差し替え、テスト終了後に自動で元に戻す
  • capsys: 標準出力(stdout)および標準エラー出力(stderr)への出力をキャプチャし、capsys.readouterr() で文字列として検証できるようにする

以下は、ファイル入出力のテストで頻繁に使われる tmp_path の実行例です。

test_builtin.py
def test_create_temp_file(tmp_path):
file_path = tmp_path / "sample.txt"
file_path.write_text("Hello, pytest!", encoding="utf-8")
assert file_path.read_text(encoding="utf-8") == "Hello, pytest!"
Terminal window
pytest test_builtin.py -v

実行結果:

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0 -- /tmp/pytest-venv/bin/python3
cachedir: .pytest_cache
rootdir: /tmp/pytest-demo
collecting ... collected 1 item
test_builtin.py::test_create_temp_file PASSED [100%]
============================== 1 passed in 0.01s ===============================

tmp_path を使えば、プロジェクトの作業ディレクトリを汚すことなくファイル生成や読み書きのテストを安全に実行できます。

まとめ

この記事では、Pythonのテストフレームワーク pytest における fixture(フィクスチャ)の基本から実践的な活用法までを解説しました。

押さえておきたい要点

  • @pytest.fixture を付けた関数名をテスト関数の引数に指定するだけで、前処理の結果を受け取れる
  • 関数内で yield を使うと、yield の前が前処理(Setup)、後が後処理(Teardown)として実行される
  • 重い初期化処理は scope 引数(module や session など)で実行単位を広げられるが、状態の書き換えによるテスト間の干渉に注意する
  • 複数のテストファイルで共有したい fixture は conftest.py に定義することで、import なしで利用できる
  • 一時ディレクトリを扱う tmp_path や環境変数を差し替える monkeypatch などの組み込み fixture を活用すると、テストコードをより簡潔に記述できる

fixture を適切に設計することで、重複コードのない見通しの良いテストスイートを構築できます。ぜひ日々のPython開発に取り入れてみてください。

あわせて読みたい

Pythonでのテスト手法や関連機能についてさらに理解を深めたい方は、以下の記事もあわせてご覧ください。

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

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

pytestでテスト実行の待ち時間を短縮!ファイル、クラス、関数、キーワード(-k)、マーカー(-m)で特定のテストだけをピンポイントに実行する方法を解説。修正箇所の確認やデバッグ効率が格段に上がり、開発スピードを劇的に向上させます。

【Python】unittestとmockの使い方を解説!
ITナレッジライフ

【Python】unittestとmockの使い方を解説!

Pythonでのソフトウェア開発において、単体テスト(unittest)は品質を確保するために不可欠な要素です。本記事では、Python標準ライブラリのunittestを使ったテストの基本から、unittest.mockを活用して外部依存を排除する方法 まで、実践的な実装方法を解説します。

【Python】デコレータ徹底解説|基礎からわかりやすく解説!
ITナレッジライフ

【Python】デコレータ徹底解説|基礎からわかりやすく解説!

Pythonのデコレータは、関数やクラスの振る舞いを柔軟に拡張できる便利な機能です。本記事では、初心者でも理解しやすいコード例と実行結果を交えて、デコレータの基本的な仕組みから、実践的な応用例まで詳しく解説します。Pythonの開発を効率化し、可読性の高いコードを書けるようになりましょう!

【Python】dataclassの使い方!基本構文から実践テクニックまで
ITナレッジライフ

【Python】dataclassの使い方!基本構文から実践テクニックまで

Pythonのdataclass(データクラス)の使い方を徹底解説!通常のクラスとの違い、自動生成される特殊メソッド、frozenによる不変オブジェクト化、field関数やasdictの活用テクニックまで、実機で検証した豊富なコード例とともに分かりやすく紹介します。


以上で本記事の解説を終わります。
よいITライフを!
スポンサーリンク
ITナレッジライフ 運営者
この記事を書いた人

Z (ITナレッジライフ)

現役のITエンジニア。Linux、プログラミング、IT用語など、日々の業務で得た「痒いところに手が届く」技術情報を発信しています。

プロフィールと編集ポリシーを見る →
スポンサーリンク

Pythonユーザにお勧めの本 ↗

初心者向け

1週間でPythonの基礎が学べる本

難易度
実用性
読みやすさ

「絶対に挫折させない」という著者の強い意志を感じる、プログラミングの「最初の1冊」としておすすめできる良書です。

スポンサーリンク

人気記事


記事を評価

Thanks!
目次
Scroll to Top