Playwright for Python 入門

概要

Playwright for Python (pytestフレームワークを使用) に関する記事があまり見当たらなかったため、こちらにまとめます。

Playwrightとは

Microsoft製のブラウザテスト(E2Eテスト)自動化ツール。クロスプラットフォーム、クロスブラウザ対応で、自動Wait/Retry、コード自動生成機能を備える等、モダンなフレームワークとなっています。2026年2月現在、Node.js, Python, Java, .NETに対応。
ちなみに類似ツールである「Cypress」「Selenium」とのシェア争いは、Googleトレンドによるとこんな感じです。

インストール

早速インストールに進みます。

• pipの場合

pip install pytest-playwright

• condaの場合

conda config --add channels conda-forge
conda config --add channels microsoft
conda install pytest-playwright

ここでインストールするのは、Pythonのテストフレームワークである「pytest」のプラグインとしてのPlaywrightです。もちろんPure PlaywrightでもE2Eテストは可能ですが、pytestの仕組みと併せて使用することで様々な恩恵を得られます。詳細については後述。

• 下記コマンドで必要なブラウザがインストールされます。
  SeleniumではOSにインストールしたブラウザを利用しますが、Playwrightでは専用のブラウザがPlaywrightの管理する領域にインストールされます。テスト時のデフォルトブラウザはChromiumです。

playwright install

環境

当方の環境です。

名称	バージョン
Playwright	1.55.0
pytest-playwright	0.7.2
pytest	9.0.2
Python	3.13.5
OS	macOS 15.7.3 (Sequoia)

使用方法

基本項目を以下に説明します。

1. 最小コード

[test_example.py]

def test_example(page):
    page.goto("https://example.com")

※ファイル名と関数名はtest_で始める必要があります。

たったこれだけです。ブラウザの起動/終了はPlaywrightが全て自動で行ってくれます。
実際にはfixtureという仕組みでブラウザ/コンテキスト/タブの開閉が実行されるのですが、本記事ではまず動かすことに重点を置くため、説明はここでは割愛します。

また、冒頭でパッケージのimportも不要です。これはpytestのプラグインとしてplaywrightを起動させるためです。

2. 実行方法

• 基本

pytest

⇨ カレントディレクトリから再帰的にtest_*.pyを探し全てのファイルを実行します。

• テスト結果詳細を表示します (-v: verbose)

pytest -v

• テスト結果簡略版を表示します (-q: quiet)

pytest -q

• 特定のファイルのみ実行します

pytest test_example.py

• 特定のファイルの特定の関数のみ実行します

pytest test_example.py::test_example

• 画面ありモードで実行 (--headed)

pytest --headed

　※デフォルトはヘッドレス (画面なし) モードです。

• ブラウザ指定 (--browser)

pytest --browser firefox

• スローモーション実行 (--slowmo)

pytest --slowmo 500

　上記例では、各操作の間に500ms空けます。

3. 基本操作

• goto()：ページ移動
• click()：クリック
• fill()：フォーム入力

[test_login.py]

def test_login_success(page):
    page.goto("https://www.saucedemo.com/")
    page.locator("#user-name").fill("standard_user")
    page.locator("#password").fill("secret_sauce")
    page.locator("#login-button").click()

• locatorについては後述。ここではCSSセレクタで要素を指定しています。

4. Locator

Locatorは、ページ上の要素を見つける手段です。SeleniumやCypressでは、XPathやCSSセレクタで要素を指定するのが基本ですが、Playwrightの思想はそれとは異なっています。ユーザの操作視点で、そして画面レイアウト変更に強い指定方法を採用しているのが特徴です。

1. get_by_role()：アクセシビリティロールで指定
2. get_by_label()：label要素のテキストで指定
3. get_by_placeholder()：プレースホルダで指定
4. get_by_alt_text()：代替テキストで指定
5. get_by_text()：画面上のテキストで指定
6. CSSセレクタとXPathは最終手段

get_by_role()

アクセシビリティのロールと名前で要素を指定します。
ポイントは、要素にrole属性が付いていなくても機能することです。例えば、ブラウザがアクセシビリティツリーで"ボタン"だと認識していれば、buttonタグでなくても、ロールは"button"になります。
各要素のアクセシビリティ情報は、ブラウザのデベロッパーツールで下記のように確認できます。

<button class="btn btn_primary">Add to cart</button>

page.get_by_role("button", name="Add to cart").click()

get_by_label()

<label>Password <input type="password" /></label>

page.get_by_label("Password").fill("secret")

get_by_placeholder()

<input type="email" placeholder="[e-mail]" />

page.get_by_placeholder("[e-mail]").fill("[e-mail]")

get_by_alt_text()

<img alt="playwright logo" src="/img/playwright-logo.svg" width="100" />

page.get_by_alt_text("playwright logo").click()

get_by_text()

<span>Welcome, John</span>

expect(page.get_by_text("Welcome, John")).to_be_visible()

• expect (アサーション) については後述。ここではテキスト (Welcome, John) で要素を探し、それが可視であることを確認しています。

locator()

CSSセレクタまたはXPathで要素を指定します。
引数には、セレクタ, XPath 何れも記述することができます。

page.locator("button").click()
page.locator("//button").click()

5. Assertion

期待した結果と、実際の結果が一致しているかをチェックする仕組みです。
Playwrightでは、画面の状態チェックにはexpect, 純粋な値比較にはPython標準のassertを使用します。

• expect(対象).to_be_〜, to_have_〜, to_contain_〜
• assert 実際 == 期待

[例]

# 要素が可視であること
expect(page.get_by_text("Checkout: Complete!")).to_be_visible()
# ページのURLが〜であること
expect(page).to_have_url("https://www.saucedemo.com/inventory.html")
# ページのタイトルが〜であること
expect(page).to_have_title("Swag Labs")
# 要素のテキストが〜に一致すること
expect(page.locator(".title")).to_have_text("Welcome, Test User!")
# 要素のテキストに〜が含まれていること
expect(page.locator('.title')).to_contain_text("Welcome")

assert value == 10

6. 自動Wait/Retry

Playwrightのexpectには自動Wait/Retry機能が付いてます。Seleniumでは自身でwaitやリトライ処理を書く必要がありますが、expectは自動で要素が現れるまで待機してくれます。これによりコーディングの省力化およびテストの安定化が見込めます。原則、明示的Waitは書かないというのがPlaywrightの思想です。

サンプル

テストサイト

下記のデモサイトを利用します。
https://www.saucedemo.com/

サンプルコード

ECサイトへログインし、商品をカートに入れ、必要事項を入力の上、購入を済ませ、ログアウトするまでの流れをテストします。
（本来テストケースはもう少し細かい粒度にすべきですが、今回は便宜上一連の流れを1つのテストケースにまとめています）

[test_checkout.py]

from playwright.sync_api import expect

def test_checkout_oneitem(page):
    # ログイン
    page.goto("https://www.saucedemo.com/")
    page.get_by_placeholder("Username").fill("standard_user")
    page.get_by_placeholder("Password").fill("secret_sauce")
    page.get_by_role("button", name="Login").click()
    # ログイン確認
    expect(page.get_by_text("Products")).to_be_visible()
    expect(page).to_have_url("https://www.saucedemo.com/inventory.html")
    expect(page).to_have_title("Swag Labs")
    # カートにアイテムを1つ入れる
    page.get_by_role("button", name="Add to cart").first.click()
    # カートアイコンをクリック
    page.locator(".shopping_cart_link").click()
    # Checkoutボタンをクリック
    page.get_by_role("button", name="Checkout").click()
    # 氏名/郵便番号を入力
    page.get_by_role("textbox", name="First Name").fill("Ryunosuke")
    page.get_by_role("textbox", name="Last Name").fill("Shintani")
    page.get_by_role("textbox", name="Zip/Postal Code").fill("1234567")
    # Continueボタンをクリック
    page.get_by_role("button", name="Continue").click()
    # Finishボタンをクリック
    page.get_by_role("button", name="Finish").click()
    # Thank you for your order!が表示されたことを確認
    expect(page.get_by_role("heading", name="Thank you for your order!")).to_be_visible()
    # Checkout: Complete!が表示されたことを確認
    expect(page.get_by_text("Checkout: Complete!")).to_be_visible()
    # 完了マークが表示されたことを確認
    expect(page.get_by_alt_text("Pony Express")).to_be_visible()
    # URLのチェック
    expect(page).to_have_url("https://www.saucedemo.com/checkout-complete.html")
    # Back Homeボタンをクリック
    page.get_by_role("button", name="Back Home").click()
    # メニューボタンをクリック
    page.get_by_role("button", name="Open Menu").click()
    # Logoutをクリック
    page.get_by_role("link", name="Logout").click()
    # ログアウト確認
    expect(page).to_have_url("https://www.saucedemo.com/")
    expect(page.get_by_role("button", name="Login")).to_be_visible()

• Locatorで複数の要素がヒットした場合、.firstや.nth(x)で要素を絞り込むことができます。
  • .first：1番目の要素を取得
  • .last：最後の要素を取得
  • .nth(x)：x番目の要素を取得 (xは0,1,2,...)

[実行]

% pytest -v --headed test_checkout.py
========================================= test session starts =========================================
platform darwin -- Python 3.13.5, pytest-9.0.2, pluggy-1.6.0 -- /opt/miniconda3/envs/pw/bin/python3.13
cachedir: .pytest_cache
rootdir: /Users/ryunosuke/dev/py/projects/pw_test
plugins: playwright-0.7.2, base-url-2.1.0
collected 1 item

test_checkout.py::test_checkout_oneitem[chromium] PASSED [100%]

========================================== 1 passed in 11.12s ==========================================
%

以上でPlaywright for Python入門編は完了です。