ハンドル

はじめに

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

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

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

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

API リファレンス

JSHandleを取得する最も簡単な方法は次のとおりです。

JSHandle jsHandle = page.evaluateHandle("window");
//  Use jsHandle for evaluations.

要素ハンドル

推奨されません

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

ElementHandleが必要な場合は、Page.waitForSelector()またはFrame.waitForSelector()メソッドで取得することを推奨します。これらのAPIは、要素がアタッチされ表示されるまで待機します。

// Get the element handle
JSHandle jsHandle = page.waitForSelector("#box");
ElementHandle elementHandle = jsHandle.asElement();

// Assert bounding box for the element
BoundingBox boundingBox = elementHandle.boundingBox();
assertEquals(100, boundingBox.width);

// Assert attribute for the element
String classNames = elementHandle.getAttribute("class");
assertTrue(classNames.contains("highlighted"));

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

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

// Create new array in page.
JSHandle myArrayHandle = page.evaluateHandle("() => {\n" +
  "  window.myArray = [1];\n" +
  "  return myArray;\n" +
  "}");

// Get the length of the array.
int length = (int) page.evaluate("a => a.length", myArrayHandle);

// Add one more element to the array using the handle
Map<String, Object> arg = new HashMap<>();
arg.put("myArray", myArrayHandle);
arg.put("newElement", 2);
page.evaluate("arg => arg.myArray.add(arg.newElement)", arg);

// Release the object when it is no longer needed.
myArrayHandle.dispose();

ハンドルライフサイクル

ハンドルは、Page.evaluateHandle()、Page.querySelector()、Page.querySelectorAll()などのページメソッド、またはそれに対応するフレームメソッドであるFrame.evaluateHandle()、Frame.querySelector()、Frame.querySelectorAll()を使用して取得できます。作成されたハンドルは、ページが遷移するか、JSHandle.dispose()メソッドで手動で破棄されない限り、ガベージコレクションからオブジェクトを保持します。

APIリファレンス

LocatorとElementHandleの比較

注意

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

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

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

ElementHandle handle = page.querySelector("text=Submit");
handle.hover();
handle.click();

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

Locator locator = page.getByText("Submit");
locator.hover();
locator.click();

はじめに​

API リファレンス​

要素ハンドル​

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

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

APIリファレンス​

LocatorとElementHandleの比較​