Selenium・Playwrightロケーター入門｜CSSセレクター・XPath・data-testidの使い方を解説

Selenium・Playwright でブラウザ自動化をするとき、最初の難関は「要素をどう特定するか」です。CSS セレクターと XPath の書き方を理解すれば、テストコードの安定性が大きく変わります。本記事ではロケーターの基礎から、壊れにくい書き方のコツまで解説します。

📌 この記事の対象読者

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

筆者は複数のプロジェクトで Selenium・Playwright を使ったブラウザ自動化テストを実践してきました。
ロケーターが原因で E2E テストが不安定になるケースは非常に多く、本記事はその経験をもとに実務で使える書き方に絞って解説します。

ロケーターとは何か

ロケーター（Locator）とは、Web ページ上の特定の要素（ボタン・テキストボックス・リンクなど）を見つけるための指定方法です。

Selenium や Playwright がブラウザを操作するとき、「どの要素をクリックするか」「どのテキストボックスに文字を入力するか」をロケーターで指定します。

# ロケーターの例（Selenium）
driver.find_element(By.ID, "login-btn")        # ID で探す
driver.find_element(By.CSS_SELECTOR, "#form input[type='email']")  # CSS で探す
driver.find_element(By.XPATH, "//button[@type='submit']")          # XPath で探す

ロケーターが壊れる＝テストが失敗するという直接的な関係があるため、壊れにくいロケーターを選ぶことがテストの安定性を大きく左右します。

ロケーターの種類と使い分け

CSS セレクターの書き方

CSS セレクターは HTML の構造を使って要素を特定する書き方です。フロントエンド開発者には馴染みが深く、Selenium・Playwright の両方で使えます。

基本的な書き方

# HTML の例
# <input id="email" class="form-input" type="email" name="email" />

# ID で指定（# を付ける）
"#email"

# クラスで指定（. を付ける）
".form-input"

# 属性で指定（[ ] で囲む）
"[type='email']"
"[name='email']"

# タグ + クラスの組み合わせ
"input.form-input"

# 親子関係（スペースで区切る：間接の子孫）
".login-form input"

# 直接の子要素（> で区切る）
".login-form > input"

ロケーター選択フロー

迷ったら「ユーザーが認識できる要素」を優先する考え方が Playwright では推奨されています。画面を見てユーザーが「ログインボタン」と認識できるなら get_by_role("button", name="ログイン")、「メールアドレス欄」と認識できるなら get_by_label("メールアドレス") が自然な選択です。

# data-testid（最も安定）
"[data-testid='login-button']"

# フォームの入力欄
"input[type='email']"
"input[type='password']"
"input[placeholder='メールアドレス']"

# ボタン
"button[type='submit']"
"button.btn-primary"

# リンク
"a[href='/dashboard']"

# 部分一致（^=始まり、$=終わり、*=含む）
"[data-testid^='item-']"    # data-testid が "item-" から始まる要素
"[class*='active']"          # class に "active" を含む要素

XPath の書き方

XPath は XML・HTML ドキュメントを辿るためのクエリ言語です。CSS セレクターより表現力が高く、テキスト内容や要素の兄弟関係など CSS では難しい条件も書けます。

基本的な書き方

# //タグ[@属性='値']  ← 最も基本的な相対 XPath
"//button[@type='submit']"
"//input[@id='email']"

# テキスト内容で指定（多言語サービスでは注意）
"//button[text()='ログイン']"
"//button[contains(text(),'ログイン')]"   # 部分一致

# 複数条件（and で結ぶ）
"//input[@type='text' and @name='username']"

# 親要素から指定（./）
"//form[@id='login-form']//button[@type='submit']"

# 絶対 XPath（非推奨：HTML 構造が変わると即壊れる）
# /html/body/div[1]/main/form/button[2]  ← これは使わない

CSS vs XPath の使い分け

Selenium でのロケーターの使い方

Selenium 4.x では By クラスを使って要素を指定します。

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # サンプルURL

# 要素を取得して操作する
email_input = driver.find_element(By.ID, "email")
email_input.send_keys("user@example.com")          # テキスト入力

password_input = driver.find_element(By.CSS_SELECTOR, "input[type='password']")
password_input.send_keys("password123")            # テキスト入力

submit_btn = driver.find_element(By.CSS_SELECTOR, "[data-testid='login-button']")
submit_btn.click()                                 # クリック

# 要素が表示されるまで待機してから取得・操作（推奨）
wait = WebDriverWait(driver, 10)
error_msg = wait.until(
    EC.presence_of_element_located((By.CSS_SELECTOR, "[data-testid='error-message']"))
)
assert "パスワードが正しくありません" in error_msg.text

Selenium vs Playwright：待機戦略の違い

Playwright でのロケーターの使い方

Playwright は Selenium より新しいロケーター API を持っており、意味のある（セマンティックな）ロケーターが使えます。HTML 構造ではなく「役割」や「テキスト」で指定するため、デザイン変更に強いのが特徴です。

Selenium vs Playwright：ロケーター機能比較

推奨されるロケーター

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com/login")  # サンプルURL

    # data-testid で指定（最も安定）
    page.get_by_test_id("login-button").click()

    # role + name で指定（ARIA ロールを活用）
    page.get_by_role("button", name="ログイン").click()
    page.get_by_role("textbox", name="メールアドレス").fill("user@example.com")

    # テキスト内容で指定
    page.get_by_text("ログイン").click()                # 完全一致
    page.get_by_text("ログ", exact=False).click()       # 部分一致

    # label テキストでフォーム要素を指定
    page.get_by_label("メールアドレス").fill("user@example.com")

    # プレースホルダーで指定
    page.get_by_placeholder("example@email.com").fill("user@example.com")

    # CSS セレクターで指定（従来通り使える）
    page.locator("[data-testid='login-button']").click()
    page.locator("input[type='password']").fill("password123")

    browser.close()

Playwright のロケーター優先順位

data-testid で壊れにくいテストを作る

data-testid 属性はテスト専用の識別子で、デザイン変更やリファクタリングの影響を受けません。開発チームと協力してテスト対象の要素に付与することで、メンテナンスコストを大幅に下げられます。

<!-- HTML 側に data-testid を付与する -->
<button type="submit" data-testid="login-submit-btn">
  ログイン
</button>

<input type="email"
       data-testid="login-email-input"
       placeholder="メールアドレス" />

# Selenium での使用
driver.find_element(By.CSS_SELECTOR, "[data-testid='login-submit-btn']").click()

# Playwright での使用
page.get_by_test_id("login-submit-btn").click()
page.get_by_test_id("login-email-input").fill("user@example.com")

ロケーターではまりやすいポイント 7選

よくある質問（FAQ）

まとめ

ロケーターの選び方を改善するだけで、テストの安定性は大きく変わります。
まず手持ちのテストコードで絶対 XPath や動的クラス名を使っているロケーターを探して、data-testid や属性ベースのロケーターに書き換えるところから始めてみましょう。

ロケーターが安定すれば、次のステップとして Page Object Model（POM）を使ったテストコードの整理に取り組むとさらに保守しやすくなります。