pytest parametrizeの使い方｜ids・pytest.param・indirectでテストデータを整理する方法

pytest parametrizeは、同じテストを異なるデータで繰り返し実行するための仕組みです。基本の書き方はすぐ覚えられる一方で、「失敗したテストの名前が読みにくい」「特定のケースだけスキップしたい」「fixtureにデータを渡したい」といった場面で手が止まりがちです。この記事では、ids、pytest.param、indirect、複数の重ね掛け、Playwrightでの使い方、外部データの読み込みを、実務で起きやすい失敗例と合わせて整理します。

最大のポイントは「parametrizeは1ケースが1テストになる。だから、名前と管理のしやすさが保守性を左右する」という点です。データを並べるだけで終わらせず、idsとpytest.paramで1件ずつ扱えるようにしておくと、失敗時の調査が楽になります。

parametrizeを使い始めると、次のような場面に遭遇しやすくなります。

• 失敗したテストの名前がtest_login[\u30e1\u30fc...]のようになり、どのケースか分からない
• 「このケースだけ既知の不具合なので、一時的に外したい」が、全体を止めずにできない
• 乱数を使ったデータで、pytest-xdistの並列実行が収集エラーになる
• 組み合わせを足していくうちに、テスト数が100件を超えて実行が遅くなる

これらは、parametrizeの周辺機能を押さえると整理しやすくなります。

pytest parametrizeとは

@pytest.mark.parametrizeは、1つのテスト関数に複数の入力データを渡し、データの数だけテストを生成する仕組みです。テストのロジックは1つのまま、入力と期待値だけを変えて検証できます。

import pytest
from playwright.sync_api import Page, expect

@pytest.mark.parametrize(
    "email, password, message",
    [
        ("", "Passw0rd!", "メールアドレスを入力してください"),
        ("user@example.com", "", "パスワードを入力してください"),
        ("invalid", "Passw0rd!", "メールアドレスの形式が正しくありません"),
    ],
)
def test_login_validation(page: Page, email: str, password: str, message: str) -> None:
    page.goto("https://example.com/login")  # 実際のURLに置き換える
    page.get_by_label("メールアドレス").fill(email)
    page.get_by_label("パスワード").fill(password)
    page.get_by_role("button", name="ログイン").click()

    expect(page.get_by_text(message)).to_be_visible()

forループとparametrizeの違い

選ぶときの目安：ケースごとに結果を確認したい、特定のケースだけ実行やスキップをしたい場合はparametrizeが向いています。セットアップが重く、1回の流れの中で複数の値をまとめて確認したいだけなら、ループのほうが軽く済みます。

① idsでテスト名を読みやすくする

parametrizeで生成されたテストには、パラメータの値からテストIDが自動生成されます。複数の値を組み合わせる場合やオブジェクトを渡す場合は、意図した名前にならないこともあるため、idsで明示すると管理しやすくなります。日本語などASCII以外の値は、エスケープされた表示になることがあり、読みにくくなる場合があります。

@pytest.mark.parametrize(
    "email, password, message",
    [
        ("", "Passw0rd!", "メールアドレスを入力してください"),
        ("user@example.com", "", "パスワードを入力してください"),
        ("invalid", "Passw0rd!", "メールアドレスの形式が正しくありません"),
    ],
    ids=["email_empty", "password_empty", "email_invalid_format"],
)
def test_login_validation(page: Page, email: str, password: str, message: str) -> None:
    ...

# ids を付けると、テスト名は次のようになる
tests/test_login.py::test_login_validation[email_empty]
tests/test_login.py::test_login_validation[password_empty]
tests/test_login.py::test_login_validation[email_invalid_format]

# 特定のケースだけを実行できる
pytest "tests/test_login.py::test_login_validation[email_empty]"
pytest -k "email_invalid_format"

データクラスでケースをまとめる

from dataclasses import dataclass

@dataclass(frozen=True)
class LoginCase:
    case_id: str
    email: str
    password: str
    message: str

CASES = [
    LoginCase("email_empty", "", "Passw0rd!", "メールアドレスを入力してください"),
    LoginCase("password_empty", "user@example.com", "", "パスワードを入力してください"),
]

@pytest.mark.parametrize("case", CASES, ids=lambda c: c.case_id)
def test_login_validation(page: Page, case: LoginCase) -> None:
    page.goto("https://example.com/login")  # 実際のURLに置き換える
    page.get_by_label("メールアドレス").fill(case.email)
    page.get_by_label("パスワード").fill(case.password)
    page.get_by_role("button", name="ログイン").click()

    expect(page.get_by_text(case.message)).to_be_visible()

② pytest.paramでケースごとに属性を付ける

import pytest

@pytest.mark.parametrize(
    "email, password, message",
    [
        pytest.param("", "Passw0rd!", "メールアドレスを入力してください", id="email_empty"),
        pytest.param("user@example.com", "", "パスワードを入力してください", id="password_empty"),
        pytest.param(
            "a" * 300 + "@example.com",
            "Passw0rd!",
            "メールアドレスが長すぎます",
            id="email_too_long",
            marks=pytest.mark.xfail(reason="既知の不具合（チケット管理番号を記載）", strict=True),
        ),
    ],
)
def test_login_validation(page: Page, email: str, password: str, message: str) -> None:
    ...

③ parametrizeを重ねて組み合わせを作る

# 2つ重ねると、全組み合わせ（直積）がテストになる
@pytest.mark.parametrize("width, height", [(375, 667), (1280, 720)], ids=["mobile", "desktop"])
@pytest.mark.parametrize("language", ["ja", "en", "ko"])
def test_top_page(page: Page, width: int, height: int, language: str) -> None:
    page.set_viewport_size({"width": width, "height": height})
    page.goto(f"https://example.com/{language}/")
    ...
# → 2 × 3 = 6 件のテストが生成される

④ indirect=Trueでfixtureにデータを渡す

通常のparametrizeは、テスト関数の引数に値をそのまま渡します。indirect=Trueを指定すると、同名のfixtureに値が渡され、fixtureの中で加工してからテストに渡せるようになります。ロールごとにログイン状態を作る場面などで便利です。

# conftest.py
from collections.abc import Iterator

import pytest
from playwright.sync_api import Browser, Page

@pytest.fixture
def role_page(request: pytest.FixtureRequest, browser: Browser) -> Iterator[Page]:
    role = request.param  # parametrize の値がここに渡される
    context = browser.new_context(storage_state=f"auth/{role}.json")
    page = context.new_page()
    yield page
    context.close()

# tests/test_admin_menu.py
import pytest
from playwright.sync_api import Page, expect

@pytest.mark.parametrize(
    "role_page, expected_visible",
    [("admin", True), ("viewer", False)],
    indirect=["role_page"],
    ids=["admin_can_see", "viewer_cannot_see"],
)
def test_admin_menu(role_page: Page, expected_visible: bool) -> None:
    role_page.goto("https://example.com/dashboard")
    menu = role_page.get_by_role("link", name="ユーザー管理")
    if expected_visible:
        expect(menu).to_be_visible()
    else:
        expect(menu).to_have_count(0)

⑤ JSONファイルからテストデータを読み込む

データファイルは、次のような形式を想定しています。id・email・password・messageのキーが1つでも欠けると、テスト実行前の収集段階でエラーになります。

# tests/data/login_cases.json
[
  {
    "id": "email_empty",
    "email": "",
    "password": "Passw0rd!",
    "message": "メールアドレスを入力してください"
  },
  {
    "id": "password_empty",
    "email": "user@example.com",
    "password": "",
    "message": "パスワードを入力してください"
  }
]

import json
from pathlib import Path
from typing import Any

import pytest
from playwright.sync_api import Page, expect

DATA_FILE = Path(__file__).parent / "data" / "login_cases.json"

def load_cases() -> list[Any]:
    rows = json.loads(DATA_FILE.read_text(encoding="utf-8"))
    return [
        pytest.param(row["email"], row["password"], row["message"], id=row["id"])
        for row in rows
    ]

@pytest.mark.parametrize("email, password, message", load_cases())
def test_login_validation(page: Page, email: str, password: str, message: str) -> None:
    page.goto("https://example.com/login")  # 実際のURLに置き換える
    page.get_by_label("メールアドレス").fill(email)
    page.get_by_label("パスワード").fill(password)
    page.get_by_role("button", name="ログイン").click()

    expect(page.get_by_text(message)).to_be_visible()

実務でよくある失敗パターン

FAQ

📋 まとめ

まずは、いまテスト内でforループを回している箇所を1つ選んで、ids付きのparametrizeに置き換えてみてください。失敗したときに、どのケースか一目で分かるようになります。