メインコンテンツにスキップ

ハンドル

はじめに​

Playwright は、ページ DOM 要素またはページ内のその他のオブジェクトへのハンドルを作成できます。これらのハンドルは Playwright プロセス内に存在しますが、実際のオブジェクトはブラウザ内に存在します。ハンドルには 2 つのタイプがあります。

  • JSHandle は、ページ内の任意の JavaScript オブジェクトを参照します。
  • ElementHandle は、ページ内の DOM 要素を参照します。要素に対してアクションを実行したり、そのプロパティをアサートしたりするための追加メソッドがあります。

ページ内の DOM 要素は JavaScript オブジェクトでもあるため、任意の ElementHandle は JSHandle でもあります。

ハンドルは、ページ内のこれらの実際のオブジェクトに対して操作を実行するために使用されます。ハンドルで評価したり、ハンドルプロパティを取得したり、評価パラメータとしてハンドルを渡したり、ページオブジェクトを JSON などにシリアライズしたりできます。これらのメソッドについては、JSHandle クラス API を参照してください。

API リファレンス​

JSHandle を取得する最も簡単な方法を次に示します。

js_handle = page.evaluate_handle('window')
#  Use jsHandle for evaluations.

要素ハンドル​

推奨されません

ElementHandle の使用は推奨されません。代わりに Locator オブジェクトとウェブファーストアサーションを使用してください。

ElementHandle が必要な場合は、page.wait_for_selector() メソッドまたは frame.wait_for_selector() メソッドを使用してフェッチすることをお勧めします。これらの API は、要素がアタッチされ、表示されるのを待ちます。

# Get the element handle
element_handle = page.wait_for_selector('#box')

# Assert bounding box for the element
bounding_box = element_handle.bounding_box()
assert bounding_box.width == 100

# Assert attribute for the element
class_names = element_handle.get_attribute('class')
assert 'highlighted' in class_names

パラメータとしてのハンドル​

ハンドルは、page.evaluate() および同様のメソッドに渡すことができます。次のスニペットは、ページに新しい配列を作成し、データで初期化し、この配列へのハンドルを Playwright に返します。その後、後続の評価でハンドルを使用します。

# Create new array in page.
my_array_handle = page.evaluate_handle("""() => {
  window.myArray = [1];
  return myArray;
}""")

# Get current length of the array.
length = page.evaluate("a => a.length", my_array_handle)

# Add one more element to the array using the handle
page.evaluate("(arg) => arg.myArray.push(arg.newElement)", {
  'myArray': my_array_handle,
  'newElement': 2
})

# Release the object when it's no longer needed.
my_array_handle.dispose()

ハンドルライフサイクル​

ハンドルは、page.evaluate_handle()、page.query_selector()、または page.query_selector_all() などのページメソッド、またはそれらのフレームカウンターパートである frame.evaluate_handle()、frame.query_selector()、または frame.query_selector_all() を使用して取得できます。作成されたハンドルは、ページがナビゲートするか、ハンドルが js_handle.dispose() メソッドを介して手動で破棄されない限り、ガベージコレクションからのオブジェクトを保持します。

API リファレンス​

Locator vs ElementHandle​

注意

ElementHandle の使用は、静的なページで広範な DOM トラバーサルを実行する必要があるまれな場合にのみ推奨されます。すべてのユーザーアクションとアサーションには、代わりにロケーターを使用してください。

Locator と ElementHandle の違いは、後者が特定の要素を指すのに対し、Locator はその要素を取得する方法のロジックをキャプチャすることです。

以下の例では、ハンドルはページの特定の DOM 要素を指しています。その要素がテキストを変更したり、React によってまったく異なるコンポーネントをレンダリングするために使用されたりした場合でも、ハンドルは依然としてその非常に古い DOM 要素を指しています。これにより、予期しない動作が発生する可能性があります。

handle = page.query_selector("text=Submit")
handle.hover()
handle.click()

ロケーターを使用すると、ロケーターが使用されるたびに、最新の DOM 要素がセレクターを使用してページ内で特定されます。したがって、以下のスニペットでは、基になる DOM 要素が 2 回特定されます。

locator = page.get_by_text("Submit")
locator.hover()
locator.click()