ハンドル

はじめに

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

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

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

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

API リファレンス

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

var jsHandle = await page.EvaluateHandleAsync("window");
//  Use jsHandle for evaluations.

要素ハンドル

推奨されません

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

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

// Get the element handle
var jsHandle = await page.WaitForSelectorAsync("#box");
var elementHandle = jsHandle as ElementHandle;

// Assert bounding box for the element
var boundingBox = await elementHandle.BoundingBoxAsync();
Assert.AreEqual(100, boundingBox.Width);

// Assert attribute for the element
var classNames = await elementHandle.GetAttributeAsync("class");
Assert.True(classNames.Contains("highlighted"));

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

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

// Create new array in page.
var myArrayHandle = await page.EvaluateHandleAsync(@"() => {
    window.myArray = [1];
    return myArray;
}");

// Get the length of the array.
var length = await page.EvaluateAsync<int>("a => a.length", myArrayHandle);

// Add one more element to the array using the handle
await page.EvaluateAsync("arg => arg.myArray.add(arg.newElement)",
    new { myArray = myArrayHandle, newElement = 2 });

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

ハンドルライフサイクル

ハンドルは、Page.EvaluateHandleAsync()、Page.QuerySelectorAsync()、Page.QuerySelectorAllAsync()などのページメソッド、またはそれらのフレーム対応物であるFrame.EvaluateHandleAsync()、Frame.QuerySelectorAsync()、Frame.QuerySelectorAllAsync()を使用して取得できます。作成されたハンドルは、ページがナビゲートするか、JsHandle.DisposeAsync()メソッドで手動で破棄されない限り、ガベージコレクションからオブジェクトを保持します。

APIリファレンス

LocatorとElementHandleの比較

注意

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

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

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

var handle = await page.QuerySelectorAsync("text=Submit");
await handle.HoverAsync();
await handle.ClickAsync();

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

var locator = page.GetByText("Submit");
await locator.HoverAsync();
await locator.ClickAsync();

はじめに​

API リファレンス​

要素ハンドル​

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

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

APIリファレンス​

LocatorとElementHandleの比較​