Playwright ページ操作の基本

この章では、Playwright がウェブページと実際に対話する方法と、最もよく使うページ操作 API について学びます。

ページナビゲーション

ページナビゲーションは最も一般的な操作です。Playwright はページを開く、リフレッシュする、ページ遷移を制御するための複数の API を提供しています。

1. ページを開く（page.goto）

await page.goto('https://example.com');

よく使うパラメータ：

  • url: アクセスするURL
  • timeout: タイムアウト時間、デフォルト30秒

  • waitUntil: ページ読み込みを待つ条件

    • 'load': 待機loadイベント（ページとリソースが全て読み込まれる）
    • 'domcontentloaded': DOMコンテンツの読み込み完了を待つ
    • 'networkidle': ネットワークがアイドルになるのを待つ

例

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

2. ページのリフレッシュ（page.reload）

現在のページをリフレッシュします。

await page.reload({ waitUntil: 'networkidle' });

3. 進む / 戻る（page.goBack / page.goForward）

ブラウザーの進む・戻るボタンをシミュレートします。

await page.goto('https://example.com');
await page.goto('https://playwright.dev');

await page.goBack();   // 返回 example.com
await page.goForward(); // 前进到 playwright.dev

4. ページの読み込み待機

特定の要素の読み込みを明示的に待つ必要がある場合があります。Playwright はスマート待機メカニズムを提供しています。

await page.waitForLoadState('networkidle'); // 等待网络空闲
await page.waitForSelector('#main-content'); // 等待元素出现

要素の特定

ページと対話するには、まず対象の要素を特定する必要があります。Playwright はさまざまなセレクターを提供しています。

1. CSSセレクター

最もよく使われる特定方法で、フロントエンド開発と同じです。

await page.click('#login-button');     // 通过 id
await page.click('.btn-primary');      // 通过 class
await page.click('form > button');     // 通过层级关系

2. XPathセレクター

XPath 式を使用して要素を特定します。

await page.click('//button[text()="登录"]');
await page.click('//input[@name="username"]');

XPath はより柔軟ですが、可読性が低いため、最初の選択肢としては推奨されません。

3. テキスト内容による特定

要素の表示テキストを使用して特定します。

await page.click('text=登录');
await page.click('button:has-text("提交")');

4. 属性による特定

属性を直接使用して選択します。

await page.fill('input[name="email"]', '[email protected]');
await page.click('[data-test="submit-button"]');

5. ロケーター戦略のベストプラクティス

  • 一意で安定したセレクターを優先的に使用する（例：data-testid、data-test属性）
  • 動的な id や class 名に依存しないようにする
  • 使用するpage.getByRole、page.getByTextなどの読みやすさに優れた方法（Playwright 5.x 推奨）

例


await page.getByRole('button', { name: '送信' }).click();
await page.getByPlaceholder('ユーザー名を入力してください').fill('admin');

基本操作

Playwright はクリック、入力、キーボード、マウス操作を含むさまざまな要素との対話方法をサポートしています。

1. クリック操作（page.click）

await page.click('#submit');

オプションパラメータ：

  • button：'left' | 'right' | 'middle'（デフォルトは左クリック）
  • clickCount: クリック回数（ダブルクリック時は2に設定）
  • modifiers: キーボードのコンビネーションキー（例：['Control']）

例

await page.click('#submit', { button: 'right' }); // 右クリック
await page.dblclick('#submit'); // ダブルクリック

2. テキスト入力（fill vs type）

  • fill(selector, value): 入力欄をクリアして新しい値を入力（推奨、ほとんどの場合に使用）
  • type(selector, text): 一文字ずつの入力をシミュレート（遅延付きで、実際のユーザーに近い）

例

await page.fill('input[name="username"]', 'test_user');
await page.type('input[name="search"]', 'playwright', { delay: 200 });

3. キーボード操作

  • press: キーの入力をシミュレート
  • keyboard.type: テキストを連続入力
  • keyboard.press: 特定のキーを押す（コンビネーションキー可）

例

await page.press('input[name="username"]', 'Enter');
await page.keyboard.type('Hello World!');
await page.keyboard.press('Control+A'); // 全選択
await page.keyboard.press('Backspace'); // 削除

4. マウス操作

Playwright は完全なマウス制御を提供します：

  • hover: マウスホバー
  • mouse.move(x, y): 座標に移動
  • mouse.click(x, y): 座標をクリック
  • mouse.down / mouse.up: マウスボタンを押す／離す
  • dragAndDrop: 要素のドラッグ（Playwright 1.18+）

例

await page.hover('#menu'); // ホバー
await page.mouse.move(100, 200); // 座標に移動
await page.mouse.click(120, 220); // 座標をクリック
await page.dragAndDrop('#item1', '#dropzone'); // ターゲット領域にドラッグ

完全な例：ログインをシミュレートしてスクリーンショットを撮る

以下は、ナビゲーション、要素の特定、入力、クリックなどの基本操作を示す完全な Playwright スクリプトです。

例

const { chromium } = require('playwright');

(async () => {
  // 1. ブラウザーを起動し、新しいページを作成する
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  // 2. ログインページに移動する
  await page.goto('https://github.com/login');
  console.log(`現在のページタイトル：${await page.title()}`);

  // 3. 要素の特定と入力
  // ユーザー名の入力欄を特定し、ユーザー名を入力する
  await page.locator('#login_field').fill('your_username');
  // パスワードの入力欄を特定し、パスワードを入力する
  await page.locator('#password').fill('your_password');

  // 4. ログインボタンをクリックする
  // .getByRole() を使用する方がより堅牢なロケーター方法です
  await page.getByRole('button', { name: 'Sign in' }).click();

  // 5. ページのナビゲーション完了を待ち、ログイン成功を確認する
  await page.waitForURL('https://github.com/');

  // 6. スクリーンショットを保存して、ログイン状態を確認する
  await page.screenshot({ path: 'github_homepage.png' });
  console.log('ログイン成功、スクリーンショットを保存しました');

  // 7. ブラウザーを閉じる
  await browser.close();
})();

実行方法：

  • プロジェクトディレクトリにコードを保存します（ファイル名：github_login.js。
  • ターミナルで実行しますnode github_login.js。

よく使うAPI一覧表

カテゴリ メソッド / プロパティ 説明
ページナビゲーション page.goto(url[, options]) ページを開く
page.reload([options]) ページをリフレッシュ
page.goBack([options]) 戻る
page.goForward([options]) 進む
page.waitForLoadState([state]) ページの読み込み状態を待つ
要素の特定 page.locator(selector) 汎用ロケーター
page.getByRole(role, options) ロールによる特定
page.getByText(text) テキストによる特定
page.getByPlaceholder(text) プレースホルダーによる特定
page.getByLabel(text) ラベルによる特定
基本操作 page.click(selector[, options]) 要素をクリック
page.dblclick(selector) ダブルクリック
page.fill(selector, value) テキスト入力（クリアして入力）
page.type(selector, text[, options]) 一文字ずつの入力をシミュレート
page.press(selector, key) 要素上でキーを押す
page.keyboard.type(text) キーボード入力
page.keyboard.press(key) キーボードのキー押下（コンビネーションキー含む）
page.hover(selector) ホバー
page.mouse.move(x, y) マウスを移動
page.mouse.click(x, y[, options]) 座標クリック
page.dragAndDrop(src, dest) 要素のドラッグ
その他の拡張