Playwright入門｜Pythonでブラウザ自動化を始める手順を初心者向けに解説

Playwright は Microsoft が開発したブラウザ自動化ライブラリです。Selenium に比べて設定が少なく・自動待機が標準搭載で・モダンな書き方ができます。本記事ではインストールから最初のテスト実行まで、コマンド1つずつ丁寧に解説します。

📌 この記事の対象読者

📖 この記事を読むとできること

筆者は複数のプロジェクトで Playwright を使った E2E テストを実践しています。
Selenium から Playwright に移行したプロジェクトもあり、両者の違いを実務の観点で比較できます。
本記事は「初日に動くテストを書く」を目標に、詰まりやすいポイントを先回りして解説します。

Playwright とは？Selenium との違い

Playwright が急速に普及した理由

2020年以降、Playwright は E2E テストツールとして急速に普及しました。その背景には以下の理由があります。

① インストールする

まず Python 環境が用意できていることを確認してください（Python環境構築ガイド）。
venv を有効化した状態でインストールします。

# Playwright 本体と pytest プラグインをインストール
pip install playwright pytest-playwright

# ブラウザ本体のインストール（Chromium・Firefox・WebKit）
playwright install

インストール確認：

playwright --version
# Playwright 1.x.x  と表示されれば OK

② まず動かしてみる（スクリプト形式）

pytest を使う前に、まずシンプルなスクリプトで Playwright の動作を確認します。

# first_playwright.py
from playwright.sync_api import sync_playwright


def main() -> None:
    with sync_playwright() as p:
        # ブラウザを起動（headless=False でブラウザウィンドウを表示）
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()

        # ページを開く
        page.goto("https://example.com")  # サンプルURL

        # タイトルを確認
        print(page.title())

        # スクリーンショットを撮る
        page.screenshot(path="screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

python first_playwright.py

ブラウザが開いてページが表示されれば成功です。screenshot.png も保存されます。

③ pytest でテストを書く

実務では pytest と組み合わせてテストを管理します。pytest-playwright をインストール済みなら、page fixture が自動で使えます。

最初のテストファイル

# test_first.py
from playwright.sync_api import Page, expect


def test_page_title(page: Page) -> None:
    page.goto("https://example.com")  # サンプルURL
    assert "Example" in page.title()
    # Playwright らしい書き方は expect を使う方法もある
    # expect(page).to_have_title("Example Domain")


def test_heading_visible(page: Page) -> None:
    page.goto("https://example.com")  # サンプルURL
    heading = page.get_by_role("heading", name="Example Domain")
    expect(heading).to_be_visible()  # Playwright らしい書き方

pytest test_first.py -v

正常な出力例：

========================= test session starts ==========================
collected 2 items

test_first.py::test_page_title    PASSED    [ 50%]
test_first.py::test_heading_visible PASSED  [100%]

========================== 2 passed in 2.34s ==========================

ログインフォームのテスト（実践例）

# test_login.py
from playwright.sync_api import Page, expect


def test_login_success(page: Page) -> None:
    page.goto("https://example.com/login")  # サンプルURL

    # メールアドレスを入力
    page.get_by_label("メールアドレス").fill("user@example.com")

    # パスワードを入力
    page.get_by_label("パスワード").fill("password123")

    # ログインボタンをクリック
    page.get_by_role("button", name="ログイン").click()

    # ダッシュボードに遷移したことを確認
    expect(page).to_have_url("https://example.com/dashboard")  # サンプルURL


def test_login_invalid_password(page: Page) -> None:
    page.goto("https://example.com/login")  # サンプルURL

    page.get_by_label("メールアドレス").fill("user@example.com")
    page.get_by_label("パスワード").fill("wrong-password")
    page.get_by_role("button", name="ログイン").click()

    # エラーメッセージが表示されることを確認
    expect(page.get_by_test_id("error-message")).to_be_visible()
    expect(page.get_by_test_id("error-message")).to_contain_text("パスワードが正しくありません")

④ expect でアサーションを書く

Playwright の expect は Web ページ向けに特化したアサーションで、条件が満たされるまで自動でリトライします。

⑤ conftest.py でテストを整理する

ベース URL やブラウザ設定は conftest.py にまとめると、テストファイルをシンプルに保てます。

# conftest.py
import pytest
from playwright.sync_api import Page


BASE_URL = "https://example.com"  # サンプルURL


@pytest.fixture
def logged_in_page(page: Page) -> Page:
    """ログイン済みの状態で page を返す fixture"""
    page.goto(f"{BASE_URL}/login")
    page.get_by_label("メールアドレス").fill("user@example.com")
    page.get_by_label("パスワード").fill("password123")
    page.get_by_role("button", name="ログイン").click()
    page.wait_for_url(f"{BASE_URL}/dashboard")
    return page

# test_dashboard.py
from playwright.sync_api import Page, expect


def test_dashboard_shows_username(logged_in_page: Page) -> None:
    expect(logged_in_page.get_by_test_id("user-name")).to_contain_text("テスト 太郎")

pytest.ini でブラウザ・ヘッドレスモードを設定する

# pytest.ini
[pytest]
addopts =
    --browser chromium
    --headed

# コマンドラインでも指定できる
pytest --browser chromium              # Chromium を使う
pytest --browser firefox               # Firefox を使う
pytest --headed                        # ブラウザウィンドウを表示する
pytest --headless                      # ヘッドレスモード（CI 用）
pytest --slowmo 500                    # 操作を500ms遅くしてデバッグしやすくする

⑥ Codegen でテストコードを自動生成する

Codegen はブラウザを操作しながら、その操作を自動でテストコードに変換するツールです。
ロケーターの書き方に迷ったときの出発点として使えます。

# Codegen を起動（URL はテスト対象のページに合わせる）
playwright codegen https://example.com  # サンプルURL

ブラウザが開くので操作すると、隣のウィンドウにコードが生成されます。

⑦ スクリーンショットと Trace Viewer

スクリーンショット

# ページ全体のスクリーンショット
page.screenshot(path="screenshots/result.png", full_page=True)

# 特定の要素だけをキャプチャ
page.get_by_test_id("error-message").screenshot(path="screenshots/error.png")

Trace Viewer（テスト失敗の詳細確認）

Trace Viewer はテストの実行過程をステップごとに録画できるツールです。テストが失敗したときに「どの操作でどんな状態だったか」を視覚的に確認できます。

# テスト失敗時に自動でトレースを保存する
pytest --tracing=retain-on-failure

# トレースを開いて確認する
playwright show-trace trace.zip

Playwright 入門ではまりやすいポイント 7選

よくある質問（FAQ）

まとめ

Playwright は自動待機・Trace Viewer・Codegen が標準搭載されており、Selenium より設定が少なく、初めてブラウザ自動化を学ぶ方にも取り組みやすいツールです。
まず playwright codegen でどんなコードが生成されるか試してみるだけでも、全体像が把握できます。

次のステップとして、テストが増えてきたら Page Object Model（POM） でコードを整理するか、GitHub Actions で CI に組み込む方法に進みましょう。