Playwright + pytest テスト構成ベストプラクティス｜フォルダ設計・fixture・mark運用を実務レベルで解説

Playwrightとpytestをただつなぐだけでなく、フォルダ構成・fixture設計・mark運用を最初から正しく設計することで、長期的に保守できるテスト自動化基盤を構築できます。

PlaywrightとPythonを組み合わせれば、簡単にE2Eテストを書くことができます。しかし、テストが増えてくると次のような問題に直面することがよくあります。

• fixtureが増えてどこに書けばいいかわからない
• セレクタがテストコードのあちこちに散らばる
• CIでどのテストを実行するか管理できない

この記事では、こうした問題を防ぐためのPlaywright × pytestのベストプラクティス構成を、フォルダ設計からfixture・conftest.py・pytest.iniまで一気通貫で解説します。

① 推奨フォルダ構成

まずは全体のフォルダ構成を確認します。小規模プロジェクト向けのシンプル版と、中〜大規模向けの拡張版の2パターンを紹介します。

シンプル版（小規模・学習用）

my_project/
├── pages/                    # Page Object Model（ページ操作クラス）
│   ├── __init__.py
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # テストファイル
│   ├── conftest.py           # 共通fixture
│   ├── test_login.py
│   └── test_inventory.py
├── pytest.ini                # pytest設定
└── requirements.txt

拡張版（中〜大規模・チーム運用向け）

my_project/
├── pages/                    # Page Object Model
│   ├── __init__.py
│   ├── base_page.py          # 全ページ共通の基底クラス
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # テストファイル
│   ├── conftest.py           # セッション・ブラウザ系fixture
│   ├── e2e/                  # E2Eテスト（フロー全体）
│   │   ├── conftest.py       # E2E専用fixture
│   │   └── test_purchase_flow.py
│   ├── smoke/                # スモークテスト（最小限の動作確認）
│   │   └── test_login_smoke.py
│   └── regression/           # 回帰テスト
│       └── test_cart.py
├── utils/                    # ヘルパー関数・定数
│   ├── __init__.py
│   └── constants.py          # URL・テストデータ定数
├── reports/                  # テストレポート出力先
├── pytest.ini
└── requirements.txt

② pytest.ini の完成形

プロジェクトルートに置く pytest.ini です。これがあるだけでチーム全員が同じ設定でテストを実行できます。

# pytest.ini
[pytest]
# テスト検索パス
testpaths = tests

# デフォルトオプション
addopts =
    -v
    --tb=short
    --html=reports/report.html
    --self-contained-html

# カスタムマーク登録（未登録だと警告が出る）
markers =
    smoke: スモークテスト（最小限の動作確認・毎回実行）
    regression: 回帰テスト（リリース前に実行）
    e2e: E2Eテスト（フロー全体・時間がかかる）
    slow: 実行時間が長いテスト

# ログ設定
log_cli = true
log_cli_level = INFO
log_format = %(asctime)s %(levelname)s %(message)s
log_date_format = %Y-%m-%d %H:%M:%S

③ conftest.py の階層設計

conftest.pyは「どのスコープのfixtureか」によって置き場所を分けるのがベストプラクティスです。

tests/conftest.py（プロジェクト全体で共有）

# tests/conftest.py
import pytest
from playwright.sync_api import sync_playwright

# ============================================================
# ブラウザ・ページ系fixture（セッションスコープ）
# ============================================================

@pytest.fixture(scope="session")
def browser_instance():
    """テスト全体で1つのブラウザインスタンスを共有する"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        yield browser
        browser.close()

@pytest.fixture(scope="function")
def page(browser_instance):
    """テストごとに新しいページ（タブ）を作成する"""
    context = browser_instance.new_context(
        viewport={"width": 1280, "height": 720}
    )
    page = context.new_page()
    yield page
    context.close()  # テスト終了後にコンテキストを閉じる

# ============================================================
# 認証系fixture
# ============================================================

@pytest.fixture(scope="session")
def base_url():
    """テスト対象のベースURLを返す"""
    # 実際のコードでは https:// を付けてください（例："https://www.saucedemo.com"）
    return "www.saucedemo.com"

@pytest.fixture
def valid_credentials():
    """正常系テスト用のログイン情報"""
    return {
        "username": "standard_user",
        "password": "secret_sauce"
    }

@pytest.fixture
def locked_out_credentials():
    """ロックアウトユーザーのログイン情報（異常系テスト用）"""
    return {
        "username": "locked_out_user",
        "password": "secret_sauce"
    }

# ============================================================
# ログイン済みページfixture（よく使うのでまとめる）
# ============================================================

@pytest.fixture
def logged_in_page(page, base_url, valid_credentials):
    """ログイン済みの状態でpageを返すfixture"""
    page.goto(f"https://{base_url}/")
    page.fill("#user-name", valid_credentials["username"])
    page.fill("#password", valid_credentials["password"])
    page.click("#login-button")
    page.wait_for_url("**/inventory.html")
    return page

tests/e2e/conftest.py（E2Eテスト専用）

# tests/e2e/conftest.py
import pytest

@pytest.fixture
def cart_items():
    """E2Eテスト用カートアイテムのテストデータ"""
    return ["Sauce Labs Backpack", "Sauce Labs Bike Light"]

@pytest.fixture
def shipping_info():
    """E2Eテスト用配送情報"""
    return {
        "first_name": "テスト",
        "last_name": "太郎",
        "postal_code": "100-0001"
    }

④ Page Object Model の実装

pytestと組み合わせるPage Object Modelの実装例です。基底クラスに共通処理をまとめるのがポイントです。

pages/base_page.py（基底クラス）

# pages/base_page.py
from playwright.sync_api import Page

class BasePage:
    """全ページ共通の操作をまとめた基底クラス"""

    def __init__(self, page: Page):
        self.page = page

    def navigate(self, url: str):
        """指定URLに遷移する"""
        self.page.goto(url)

    def get_title(self) -> str:
        """ページタイトルを返す"""
        return self.page.title()

    def take_screenshot(self, name: str):
        """スクリーンショットを保存する"""
        self.page.screenshot(path=f"reports/{name}.png")

pages/login_page.py

# pages/login_page.py
from pages.base_page import BasePage

class LoginPage(BasePage):
    """ログインページの操作クラス"""

    # ロケーター定数（セレクタを一箇所で管理）
    USERNAME_INPUT = "#user-name"
    PASSWORD_INPUT = "#password"
    LOGIN_BUTTON   = "#login-button"
    ERROR_MESSAGE  = ".error-message-container h3"

    def login(self, username: str, password: str):
        """ログインを実行する"""
        self.page.fill(self.USERNAME_INPUT, username)
        self.page.fill(self.PASSWORD_INPUT, password)
        self.page.click(self.LOGIN_BUTTON)

    def get_error_message(self) -> str:
        """エラーメッセージのテキストを返す"""
        return self.page.locator(self.ERROR_MESSAGE).text_content()

⑤ テストファイルの実装

fixtureとPage Objectを組み合わせたテストファイルの完成形です。

tests/smoke/test_login_smoke.py

# tests/smoke/test_login_smoke.py
import pytest
from pages.login_page import LoginPage

@pytest.mark.smoke
def test_ログイン_正常系(page, base_url, valid_credentials):
    """スモーク：正常なログインが成功することを確認"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        valid_credentials["username"],
        valid_credentials["password"]
    )
    assert page.url.endswith("/inventory.html"), \
        f"ログイン後のURLが期待値と異なります: {page.url}"

@pytest.mark.smoke
def test_ログイン_パスワード誤り(page, base_url):
    """スモーク：誤ったパスワードでエラーメッセージが表示されることを確認"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login("standard_user", "wrong_password")
    error = login_page.get_error_message()
    assert "Epic sadface" in error

@pytest.mark.smoke
def test_ログイン_ロックアウト(page, base_url, locked_out_credentials):
    """スモーク：ロックアウトユーザーでエラーが表示されることを確認"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        locked_out_credentials["username"],
        locked_out_credentials["password"]
    )
    error = login_page.get_error_message()
    assert "locked out" in error

tests/e2e/test_purchase_flow.py

# tests/e2e/test_purchase_flow.py
import pytest

@pytest.mark.e2e
@pytest.mark.slow
def test_購入フロー_正常系(logged_in_page, cart_items, shipping_info):
    """E2E：ログイン〜購入完了までのフローをテスト"""
    page = logged_in_page

    # 商品をカートに追加
    page.click("[data-test='add-to-cart-sauce-labs-backpack']")
    page.click("[data-test='add-to-cart-sauce-labs-bike-light']")

    # カートに移動
    page.click(".shopping_cart_link")
    assert page.url.endswith("/cart.html")

    # チェックアウト開始
    page.click("[data-test='checkout']")
    page.fill("[data-test='firstName']", shipping_info["first_name"])
    page.fill("[data-test='lastName']", shipping_info["last_name"])
    page.fill("[data-test='postalCode']", shipping_info["postal_code"])
    page.click("[data-test='continue']")

    # 注文確認・完了
    page.click("[data-test='finish']")
    success_msg = page.locator(".complete-header").text_content()
    assert "Thank you" in success_msg

⑥ mark を使ったテスト実行制御

markを設定しておくことで、CI/CDのフェーズに応じて実行するテストセットを柔軟に切り替えられます。

# スモークテストだけ実行（PR・pushのたびに）
pytest -m smoke

# スモーク・回帰テストを実行（mainマージ前）
pytest -m "smoke or regression"

# E2Eを除いた全テスト（高速に済ませたいとき）
pytest -m "not e2e"

# slowを除いた全テスト
pytest -m "not slow"

# 全テスト実行（夜間スケジュール）
pytest

⑦ GitHub Actions との連携

markとGitHub Actionsを組み合わせることで、フェーズごとに実行するテストを自動で切り替えられます。

# .github/workflows/playwright.yml（抜粋）

jobs:
  smoke:
    name: スモークテスト（PR・push）
    runs-on: ubuntu-latest
    steps:
      # ... セットアップ省略 ...
      - name: スモークテスト実行
        run: pytest -m smoke

  regression:
    name: 回帰テスト（mainへのマージ後）
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      # ... セットアップ省略 ...
      - name: 回帰テスト実行
        run: pytest -m "smoke or regression"

  nightly:
    name: 夜間フルテスト
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    steps:
      # ... セットアップ省略 ...
      - name: 全テスト実行
        run: pytest

⑧ 実行結果サンプル

$ pytest -m smoke -v

========================= test session starts ==========================
platform linux -- Python 3.11.0, pytest-7.4.0
collected 8 items / 5 deselected / 3 selected

tests/smoke/test_login_smoke.py::test_ログイン_正常系       PASSED  [ 33%]
tests/smoke/test_login_smoke.py::test_ログイン_パスワード誤り  PASSED  [ 66%]
tests/smoke/test_login_smoke.py::test_ログイン_ロックアウト  PASSED  [100%]

========================== 3 passed in 5.21s ===========================

FAQ

⚠️ Playwright + pytest 構成でよくあるはまりポイント7選

構成を正しく組んでいても踏みやすい落とし穴があります。事前に把握しておくことで、余計なデバッグ時間を省けます。

# ❌ NG
cd tests
pytest

# ✅ 推奨
cd my_project    # pytest.ini のある場所
pytest

📋 この記事のまとめ

最初から完璧な構成を目指す必要はありません。まずはシンプル版のフォルダ構成からスタートし、テストが増えてきたタイミングで少しずつ拡張版に近づけていくのが実務的なアプローチです。