Frame

すべての時点で、ページはpage.mainFrame()およびframe.childFrames()メソッドを介して現在のフレームツリーを公開します。

Frameオブジェクトのライフサイクルは、ページオブジェクト上でディスパッチされる3つのイベントによって制御されます。

page.on('frameattached') - フレームがページにアタッチされたときに発生します。フレームはページに一度だけアタッチできます。
page.on('framenavigated') - フレームが異なるURLへのナビゲーションをコミットしたときに発生します。
page.on('framedetached') - フレームがページからデタッチされたときに発生します。フレームはページから一度だけデタッチできます。

フレームツリーをダンプする例

const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

(async () => {
  const browser = await firefox.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com/chrome/browser/canary.html');
  dumpFrameTree(page.mainFrame(), '');
  await browser.close();

  function dumpFrameTree(frame, indent) {
    console.log(indent + frame.url());
    for (const child of frame.childFrames())
      dumpFrameTree(child, indent + '  ');
  }
})();

メソッド

`addScriptTag`

v1.9より前に追加

frame.addScriptTag

スクリプトのonloadが発火したとき、またはスクリプトコンテンツがフレームに注入されたときに、追加されたタグを返します。

指定されたURLまたはコンテンツを持つ<script>タグをページに追加します。

使用法

await frame.addScriptTag();
await frame.addScriptTag(options);

引数

options Object (オプション)
- content string (オプション)#
  
  フレームに注入する生のJavaScriptコンテンツ。
- path string (オプション)#
  
  フレームに注入するJavaScriptファイルへのパス。pathが相対パスの場合、現在の作業ディレクトリに対して解決されます。
- type string (オプション)#
  
  スクリプトのタイプ。JavaScript ES6モジュールをロードするには 'module' を使用します。詳細についてはscriptを参照してください。
- url string (オプション)#
  
  追加するスクリプトのURL。

戻り値

Promise<ElementHandle>#

`addStyleTag`

v1.9より前に追加

frame.addStyleTag

スタイルシートのonloadが発火したとき、またはCSSコンテンツがフレームに注入されたときに、追加されたタグを返します。

指定されたURLを持つ<link rel="stylesheet">タグ、またはコンテンツを持つ<style type="text/css">タグをページに追加します。

使用法

await frame.addStyleTag();
await frame.addStyleTag(options);

引数

options Object (オプション)
- content string (オプション)#
  
  フレームに注入する生のCSSコンテンツ。
- path string (オプション)#
  
  フレームに注入するCSSファイルへのパス。pathが相対パスの場合、現在の作業ディレクトリに対して解決されます。
- url string (オプション)#
  
  <link>タグのURL。

戻り値

Promise<ElementHandle>#

`childFrames`

v1.9より前に追加

frame.childFrames

使用法

frame.childFrames();

戻り値

Array<Frame>#

`content`

v1.9より前に追加

frame.content

DOCTYPEを含むフレームの完全なHTMLコンテンツを取得します。

使用法

await frame.content();

戻り値

Promise<string>#

`dragAndDrop`

追加バージョン: v1.13

frame.dragAndDrop

使用法

await frame.dragAndDrop(source, target);
await frame.dragAndDrop(source, target, options);

引数

source string#

ドラッグする要素を検索するためのセレクター。セレクターを満たす要素が複数ある場合、最初の要素が使用されます。
target string#

ドロップ先の要素を検索するためのセレクター。セレクターを満たす要素が複数ある場合、最初の要素が使用されます。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- sourcePosition Object (オプション)追加バージョン: v1.14#
  - x number
  - y number
  要素のパディングボックスの左上隅を基準としたこの点で、ソース要素をクリックします。指定されていない場合、要素の表示されているいずれかの点が使用されます。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- targetPosition Object (オプション)追加バージョン: v1.14#
  - x number
  - y number
  要素のパディングボックスの左上隅を基準としたこの点で、ターゲット要素にドロップします。指定されていない場合、要素の表示されているいずれかの点が使用されます。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)#
  
  設定すると、このメソッドは操作可能性 (actionability) チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するのに便利です。

戻り値

Promise<void>#

`evaluate`

v1.9より前に追加

frame.evaluate

pageFunctionの戻り値を返します。

frame.evaluate()に渡された関数がPromiseを返す場合、frame.evaluate()はそのプロミスが解決されるのを待ってその値を返します。

frame.evaluate()に渡された関数が非シリアライズ可能 (Serializable)な値を返す場合、frame.evaluate()はundefinedを返します。Playwrightは、JSONでシリアライズできない追加の値（-0、NaN、Infinity、-Infinity）の転送もサポートしています。

使用法

const result = await frame.evaluate(([x, y]) => {
  return Promise.resolve(x * y);
}, [7, 8]);
console.log(result); // prints "56"

関数の代わりに文字列を渡すこともできます。

console.log(await frame.evaluate('1 + 2')); // prints "3"

ElementHandleインスタンスは、frame.evaluate()の引数として渡すことができます。

const bodyHandle = await frame.evaluate('document.body');
const html = await frame.evaluate(([body, suffix]) =>
  body.innerHTML + suffix, [bodyHandle, 'hello'],
);
await bodyHandle.dispose();

引数

pageFunction function | string#

ページコンテキストで評価される関数。
arg EvaluationArgument (オプション)#

pageFunctionに渡すオプション引数。

戻り値

Promise<Serializable>#

`evaluateHandle`

v1.9より前に追加

frame.evaluateHandle

pageFunctionの戻り値をJSHandleとして返します。

frame.evaluate()とframe.evaluateHandle()の唯一の違いは、frame.evaluateHandle()がJSHandleを返すことです。

frame.evaluateHandle()に渡された関数がPromiseを返す場合、frame.evaluateHandle()はそのプロミスが解決されるのを待ってその値を返します。

使用法

// Handle for the window object
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));

関数の代わりに文字列を渡すこともできます。

const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.

JSHandleインスタンスは、frame.evaluateHandle()の引数として渡すことができます。

const aHandle = await frame.evaluateHandle(() => document.body);
const resultHandle = await frame.evaluateHandle(([body, suffix]) =>
  body.innerHTML + suffix, [aHandle, 'hello'],
);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();

引数

pageFunction function | string#

ページコンテキストで評価される関数。
arg EvaluationArgument (オプション)#

pageFunctionに渡すオプション引数。

戻り値

Promise<JSHandle>#

`frameElement`

v1.9より前に追加

frame.frameElement

このフレームに対応するframeまたはiframe要素ハンドルを返します。

これはelementHandle.contentFrame()の逆です。返されるハンドルは実際には親フレームに属することに注意してください。

frameElement()が返される前にフレームがデタッチされた場合、このメソッドはエラーをスローします。

使用法

const frameElement = await frame.frameElement();
const contentFrame = await frameElement.contentFrame();
console.log(frame === contentFrame);  // -> true

戻り値

Promise<ElementHandle>#

`frameLocator`

追加バージョン: v1.17

frame.frameLocator

iframeを操作する場合、iframeに入り、そのiframe内の要素を選択できるフレームロケーターを作成できます。

使用法

以下のスニペットは、my-frameというIDを持つiframe内のテキスト「Submit」を持つ要素を検索します（例: <iframe id="my-frame">）。

const locator = frame.frameLocator('#my-iframe').getByText('Submit');
await locator.click();

引数

selector string#

DOM要素を解決する際に使用するセレクター。

戻り値

FrameLocator#

`getByAltText`

追加バージョン: v1.27

frame.getByAltText

要素をaltテキストで検索できるようにします。

使用法

例えば、このメソッドはaltテキスト「Playwright logo」で画像を見つけます。

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

引数

text string | RegExp#

要素を検索するためのテキスト。
options Object (オプション)
- exact boolean (オプション)#
  
  完全一致 (大文字小文字を区別し、文字列全体を照合) を行うかどうか。デフォルトはfalseです。正規表現による検索の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator#

`getByLabel`

追加バージョン: v1.27

frame.getByLabel

関連付けられた<label>またはaria-labelledby要素のテキスト、またはaria-label属性によって、入力要素を検索できるようにします。

使用法

例えば、このメソッドは以下のDOMにおいてラベル「Username」と「Password」で入力を見つけます。

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

引数

text string | RegExp#

要素を検索するためのテキスト。
options Object (オプション)
- exact boolean (オプション)#
  
  完全一致 (大文字小文字を区別し、文字列全体を照合) を行うかどうか。デフォルトはfalseです。正規表現による検索の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator#

`getByPlaceholder`

追加バージョン: v1.27

frame.getByPlaceholder

プレースホルダーテキストで入力要素を検索できるようにします。

使用法

例えば、以下のDOM構造を考えてみましょう。

<input type="email" placeholder="name@example.com" />

プレースホルダーテキストで入力を検索した後、入力に値を設定できます。

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');

引数

text string | RegExp#

要素を検索するためのテキスト。
options Object (オプション)
- exact boolean (オプション)#
  
  完全一致 (大文字小文字を区別し、文字列全体を照合) を行うかどうか。デフォルトはfalseです。正規表現による検索の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator#

`getByRole`

追加バージョン: v1.27

frame.getByRole

要素をそのARIAロール、ARIA属性、およびアクセシブルネームで検索できるようにします。

使用法

以下のDOM構造を考えてみましょう。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

各要素をその暗黙的なロールで検索できます。

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

引数

role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"#

必須のARIAロール。
options Object (オプション)
- checked boolean (オプション)#
  
  通常、aria-checkedまたはネイティブの<input type=checkbox>コントロールによって設定される属性。
  
  aria-checkedの詳細についてはこちら。
- disabled boolean (オプション)#
  
  通常、aria-disabledまたはdisabledによって設定される属性。
  
  注
  他のほとんどの属性とは異なり、disabledはDOM階層を通じて継承されます。aria-disabledの詳細についてはこちら。
- exact boolean (オプション)追加バージョン: v1.28#
  
  nameが厳密に一致するかどうか（大文字小文字を区別し、文字列全体を照合）。デフォルトはfalseです。nameが正規表現の場合は無視されます。厳密な一致でも空白はトリムされることに注意してください。
- expanded boolean (オプション)#
  
  通常、aria-expandedによって設定される属性。
  
  aria-expandedの詳細についてはこちら。
- includeHidden boolean (オプション)#
  
  非表示の要素を照合するかどうかを制御するオプション。デフォルトでは、ARIAによって定義される非表示でない要素のみがロールセレクターによって照合されます。
  
  aria-hiddenの詳細についてはこちら。
- level number (オプション)#
  
  通常、heading、listitem、row、treeitemロールに存在する数値属性で、<h1>-<h6>要素にはデフォルト値があります。
  
  aria-levelの詳細についてはこちら。
- name string | RegExp (オプション)#
  
  アクセシブルネームを照合するオプション。デフォルトでは、大文字小文字を区別せずに部分文字列を検索します。この動作を制御するにはexactを使用します。
  
  アクセシブルネームの詳細についてはこちら。
- pressed boolean (オプション)#
  
  通常、aria-pressedによって設定される属性です。
  
  aria-pressedについて詳しくはこちら。
- selected boolean (オプション)#
  
  通常、aria-selectedによって設定される属性です。
  
  aria-selectedについて詳しくはこちら。

戻り値

Locator #

詳細

ロールセレクターはアクセシビリティ監査や適合性テストを置き換えるものではありませんが、ARIAガイドラインに関する早期フィードバックを提供します。

多くのHTML要素には、ロールセレクターによって認識される暗黙的に定義されたロールがあります。サポートされているすべてのロールはこちらで確認できます。ARIAガイドラインは、roleおよび/またはaria-*属性をデフォルト値に設定して暗黙のロールや属性を重複させることを推奨していません。

getByTestId

追加バージョン: v1.27

frame.getByTestId

テストIDで要素を特定します。

使用法

以下のDOM構造を考えてみましょう。

<button data-testid="directions">Itinéraire</button>

要素をそのテストIDで特定できます。

await page.getByTestId('directions').click();

引数

testId string | RegExp #

要素を特定するためのID。

戻り値

Locator #

詳細

デフォルトでは、data-testid属性がテストIDとして使用されます。必要に応じて、selectors.setTestIdAttribute()を使用して、別のテストID属性を設定できます。

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText

追加バージョン: v1.27

frame.getByText

指定されたテキストを含む要素を特定できます。

アクセシブルなロールなどの別の基準で一致させ、その後テキストコンテンツでフィルタリングできるlocator.filter()も参照してください。

使用法

以下のDOM構造を考慮してください。

<div>Hello <span>world</span></div>
<div>Hello</div>

テキストの部分文字列、完全一致文字列、または正規表現で特定できます。

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

// Matches both <div>s
page.getByText(/Hello/);

// Matches second <div>
page.getByText(/^hello$/i);

引数

text string | RegExp #

要素を検索するためのテキスト。
options Object (オプション)
- exact boolean (オプション)#
  
  完全一致 (大文字小文字を区別し、文字列全体を照合) を行うかどうか。デフォルトはfalseです。正規表現による検索の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator #

詳細

テキストによる一致は、厳密な一致であっても常に空白を正規化します。たとえば、複数のスペースを1つにまとめ、改行をスペースに変換し、前後の空白を無視します。

buttonおよびsubmitタイプの入力要素は、テキストコンテンツではなくvalueで一致します。たとえば、テキスト"Log in"で検索すると、<input type=button value="Log in">に一致します。

getByTitle

追加バージョン: v1.27

frame.getByTitle

要素をそのタイトル属性で特定できます。

使用法

以下のDOM構造を考えてみましょう。

<span title='Issues count'>25 issues</span>

タイトルテキストで要素を特定した後、issueの数を確認できます。

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

引数

text string | RegExp #

要素を検索するためのテキスト。
options Object (オプション)
- exact boolean (オプション)#
  
  完全一致 (大文字小文字を区別し、文字列全体を照合) を行うかどうか。デフォルトはfalseです。正規表現による検索の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator #

goto

v1.9より前に追加

frame.goto

メインリソースのレスポンスを返します。複数のリダイレクトがある場合、ナビゲーションは最後のリダイレクトのレスポンスで解決されます。

このメソッドは、以下の場合にエラーをスローします。

SSLエラーが発生した場合 (例: 自己署名証明書の場合)。
ターゲットURLが無効な場合。
ナビゲーション中にタイムアウトを超過した場合。
リモートサーバーが応答しない、または到達不能な場合。
メインリソースのロードに失敗した場合。

このメソッドは、リモートサーバーから404 "Not Found" や 500 "Internal Server Error" を含む有効なHTTPステータスコードが返された場合でもエラーをスローしません。これらのレスポンスのステータスコードはresponse.status()を呼び出すことで取得できます。

注

このメソッドは、エラーをスローするか、メインリソースのレスポンスを返します。唯一の例外は、about:blankへのナビゲーション、または異なるハッシュを持つ同じURLへのナビゲーションであり、これらは成功しnullを返します。

注

ヘッドレスモードはPDFドキュメントへのナビゲーションをサポートしていません。upstream issueを参照してください。

使用法

await frame.goto(url);
await frame.goto(url, options);

引数

url string #

フレームをナビゲートするURL。URLにはスキーム（例: https://）を含める必要があります。
options Object (オプション)
- referer string (オプション)#
  
  Refererヘッダーの値。指定された場合、page.setExtraHTTPHeaders()によって設定されたrefererヘッダーの値よりも優先されます。
- timeout number (オプション)#
  
  操作の最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のnavigationTimeoutオプション、またはbrowserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()、またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (オプション)#
  
  いつ操作が成功したとみなすか。デフォルトはloadです。イベントは以下のいずれかです。
  - 'domcontentloaded' - DOMContentLoadedイベントが発火したときに操作が終了したとみなします。
  - 'load' - loadイベントが発火したときに操作が終了したとみなします。
  - 'networkidle' - 非推奨 少なくとも500ミリ秒間ネットワーク接続がないときに操作が終了したとみなします。テストにはこのメソッドを使用せず、代わりにWebアサーションに依存して準備状況を評価してください。
  - 'commit' - ネットワーク応答が受信され、ドキュメントの読み込みが開始されたときに操作が終了したとみなします。

戻り値

Promise<null | Response>#

isDetached

v1.9より前に追加

frame.isDetached

フレームがデタッチされている場合はtrue、それ以外の場合はfalseを返します。

使用法

frame.isDetached();

戻り値

boolean #

isEnabled

v1.9より前に追加

frame.isEnabled

要素が有効であるかどうかを返します。

使用法

await frame.isEnabled(selector);
await frame.isEnabled(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<boolean>#

locator

追加バージョン: v1.14

frame.locator

このメソッドは、このページ/フレームでアクションを実行するために使用できる要素ロケーターを返します。ロケーターはアクションを実行する直前に要素に解決されるため、同じロケーターに対する一連のアクションは、実際には異なるDOM要素に対して実行される可能性があります。これは、これらのアクション間でDOM構造が変更された場合に発生します。

ロケーターについて詳しくはこちら.

使用法

frame.locator(selector);
frame.locator(selector, options);

引数

selector string #

DOM要素を解決する際に使用するセレクター。
options Object (オプション)
- has Locator (オプション)#
  
  この相対ロケーターに一致する要素を含む結果にメソッドを絞り込みます。例えば、text=Playwrightを持つarticleは、<article><div>Playwright</div></article>に一致します。
  
  内部ロケーターは、外部ロケーターに相対的である必要があり、ドキュメントルートではなく、外部ロケーターの一致からクエリされます。たとえば、<article><content><div>Playwright</div></content></article>内にdivを持つcontentを見つけることができます。しかし、article divを持つcontentを探すと失敗します。これは、内部ロケーターが相対的である必要があり、contentの外部の要素を使用すべきではないためです。
  
  外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターにはFrameLocatorを含めることはできません。
- hasNot Locator (オプション)追加されたバージョン: v1.33#
  
  内部ロケーターに一致する要素を含まない要素に一致します。内部ロケーターは外部ロケーターに対してクエリされます。たとえば、divを持たないarticleは、<article><span>Playwright</span></article>に一致します。
  
  外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターにはFrameLocatorを含めることはできません。
- hasNotText string | RegExp (オプション)追加されたバージョン: v1.33#
  
  指定されたテキストを、子要素や子孫要素を含め、どこかに含まない要素に一致します。文字列が渡された場合、大文字小文字を区別せずに部分文字列を検索します。
- hasText string | RegExp (オプション)#
  
  指定されたテキストを、子要素や子孫要素を含め、どこかに含む要素に一致します。文字列が渡された場合、大文字小文字を区別せずに部分文字列を検索します。例: "Playwright"は<article><div>Playwright</div></article>に一致します。

戻り値

Locator #

name

v1.9より前に追加

frame.name

タグで指定されたフレームの名前属性を返します。

名前が空の場合、代わりにID属性を返します。

注

この値はフレームが作成されたときに一度計算され、後で属性が変更されても更新されません。

使用法

frame.name();

戻り値

string #

page

v1.9より前に追加

frame.page

このフレームを含むページを返します。

使用法

frame.page();

戻り値

Page #

parentFrame

v1.9より前に追加

frame.parentFrame

親フレーム（もしあれば）。デタッチされたフレームとメインフレームはnullを返します。

使用法

frame.parentFrame();

戻り値

null | Frame #

setContent

v1.9より前に追加

frame.setContent

このメソッドは内部的にdocument.write()を呼び出し、そのすべての特定の特性と動作を継承します。

使用法

await frame.setContent(html);
await frame.setContent(html, options);

引数

html string #

ページに割り当てるHTMLマークアップ。
options Object (オプション)
- timeout number (オプション)#
  
  操作の最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のnavigationTimeoutオプション、またはbrowserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()、またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (オプション)#
  
  いつ操作が成功したとみなすか。デフォルトはloadです。イベントは以下のいずれかです。
  - 'domcontentloaded' - DOMContentLoadedイベントが発火したときに操作が終了したとみなします。
  - 'load' - loadイベントが発火したときに操作が終了したとみなします。
  - 'networkidle' - 非推奨 少なくとも500ミリ秒間ネットワーク接続がないときに操作が終了したとみなします。テストにはこのメソッドを使用せず、代わりにWebアサーションに依存して準備状況を評価してください。
  - 'commit' - ネットワーク応答が受信され、ドキュメントの読み込みが開始されたときに操作が終了したとみなします。

戻り値

Promise<void>#

title

v1.9より前に追加

frame.title

ページタイトルを返します。

使用法

await frame.title();

戻り値

Promise<string>#

url

v1.9より前に追加

frame.url

フレームのURLを返します。

使用法

frame.url();

戻り値

string #

waitForFunction

v1.9より前に追加

frame.waitForFunction

pageFunctionがtruthyな値を返したときに解決し、その値を返します。

使用法

frame.waitForFunction()は、ビューポートサイズの変更を監視するために使用できます。

const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

(async () => {
  const browser = await firefox.launch();
  const page = await browser.newPage();
  const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
  await page.setViewportSize({ width: 50, height: 50 });
  await watchDog;
  await browser.close();
})();

frame.waitForFunction関数の述語に引数を渡すには

const selector = '.foo';
await frame.waitForFunction(selector => !!document.querySelector(selector), selector);

引数

pageFunction function | string #

ページコンテキストで評価される関数。
arg EvaluationArgument (オプション)#

pageFunctionに渡すオプションの引数。
options Object (オプション)
- polling number | "raf" (オプション)#
  
  pollingが'raf'の場合、pageFunctionはrequestAnimationFrameコールバックで常に実行されます。pollingが数値の場合、関数が実行される間隔（ミリ秒単位）として扱われます。デフォルトはrafです。
- timeout number (オプション)#
  
  待機する最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<JSHandle>#

waitForLoadState

v1.9より前に追加

frame.waitForLoadState

必要なロード状態に到達するまで待機します。

これは、フレームが要求されたロード状態（デフォルトではload）に達したときに解決されます。このメソッドが呼び出された時点で、ナビゲーションはコミットされている必要があります。現在のドキュメントがすでに必要な状態に達している場合は、すぐに解決されます。

注

ほとんどの場合、Playwrightはすべてのアクションの前に自動的に待機するため、このメソッドは必要ありません。

使用法

await frame.click('button'); // Click triggers navigation.
await frame.waitForLoadState(); // Waits for 'load' state by default.

引数

state "load" | "domcontentloaded" | "networkidle" (オプション)#

待機するオプションのロード状態。デフォルトはloadです。現在のドキュメントの読み込み中にすでに状態に到達している場合、メソッドはすぐに解決されます。以下のいずれかです。
- 'load' - loadイベントが発火するまで待ちます。
- 'domcontentloaded' - DOMContentLoadedイベントが発火するまで待ちます。
- 'networkidle' - 非推奨 少なくとも500ミリ秒間ネットワーク接続がないまで待ちます。テストにはこのメソッドを使用せず、代わりにWebアサーションに依存して準備状況を評価してください。
options Object (オプション)
- timeout number (オプション)#
  
  操作の最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のnavigationTimeoutオプション、またはbrowserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()、またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

waitForURL

追加されたバージョン: v1.11

frame.waitForURL

フレームが指定されたURLにナビゲートするまで待ちます。

使用法

await frame.click('a.delayed-navigation'); // Clicking the link will indirectly cause a navigation
await frame.waitForURL('**/target.html');

引数

url string | RegExp | function(URL):boolean #

ナビゲーションを待機する間に一致させるためのグロブパターン、正規表現パターン、またはURLを受け取る述語。ワイルドカード文字を含まない文字列がパラメータとして渡された場合、このメソッドは文字列と完全に一致するURLへのナビゲーションを待機することに注意してください。
options Object (オプション)
- timeout number (オプション)#
  
  操作の最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のnavigationTimeoutオプション、またはbrowserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()、またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (オプション)#
  
  いつ操作が成功したとみなすか。デフォルトはloadです。イベントは以下のいずれかです。
  - 'domcontentloaded' - DOMContentLoadedイベントが発火したときに操作が終了したとみなします。
  - 'load' - loadイベントが発火したときに操作が終了したとみなします。
  - 'networkidle' - 非推奨 少なくとも500ミリ秒間ネットワーク接続がないときに操作が終了したとみなします。テストにはこのメソッドを使用せず、代わりにWebアサーションに依存して準備状況を評価してください。
  - 'commit' - ネットワーク応答が受信され、ドキュメントの読み込みが開始されたときに操作が終了したとみなします。

戻り値

Promise<void>#

非推奨

$

追加されたバージョン: v1.9

frame.$

非推奨

代わりにロケーターベースのframe.locator()を使用してください。ロケーターについて詳しくはこちら。

フレーム要素を指すElementHandleを返します。

注意

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

このメソッドは、フレーム内で指定されたセレクターに一致する要素を検索します。セレクターに一致する要素がない場合、nullを返します。

使用法

await frame.$(selector);
await frame.$(selector, options);

引数

selector string #

クエリするセレクター。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。

戻り値

Promise<null | ElementHandle>#

$$

追加されたバージョン: v1.9

frame.$$

非推奨

代わりにロケーターベースのframe.locator()を使用してください。ロケーターについて詳しくはこちら。

フレーム要素を指すElementHandlesを返します。

注意

ElementHandleの使用は非推奨です。代わりにLocatorオブジェクトを使用してください。

このメソッドは、フレーム内で指定されたセレクターに一致するすべての要素を検索します。セレクターに一致する要素がない場合、空の配列を返します。

使用法

await frame.$$(selector);

引数

selector string #

クエリするセレクター。

戻り値

Promise<Array<ElementHandle>>#

$eval

追加されたバージョン: v1.9

frame.$eval

非推奨

このメソッドは、要素が操作性チェックを通過するのを待機しないため、テストが不安定になる可能性があります。代わりに、locator.evaluate()、その他のLocatorヘルパーメソッド、またはWebファーストアサーションを使用してください。

pageFunctionの戻り値を返します。

このメソッドは、フレーム内で指定されたセレクターに一致する要素を検索し、それをpageFunctionの最初の引数として渡します。セレクターに一致する要素がない場合、このメソッドはエラーをスローします。

pageFunctionがPromiseを返す場合、frame.$eval()はPromiseが解決されるのを待ち、その値を返します。

使用法

const searchValue = await frame.$eval('#search', el => el.value);
const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');

引数

selector string #

クエリするセレクター。
pageFunction function(Element) | string #

ページコンテキストで評価される関数。
arg EvaluationArgument (オプション)#

pageFunctionに渡すオプションの引数。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。

戻り値

Promise<Serializable>#

$$eval

追加されたバージョン: v1.9

frame.$$eval

非推奨

ほとんどの場合、locator.evaluateAll()、その他のLocatorヘルパーメソッド、およびWebファーストアサーションの方が優れています。

pageFunctionの戻り値を返します。

このメソッドは、フレーム内で指定されたセレクターに一致するすべての要素を検索し、一致する要素の配列をpageFunctionの最初の引数として渡します。

Promiseを返す場合、frame.$$eval()はPromiseが解決されるのを待ち、その値を返します。

使用法

const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);

引数

selector string #

クエリするセレクター。
pageFunction function(Array<Element>) | string #

ページコンテキストで評価される関数。
arg EvaluationArgument (オプション)#

pageFunctionに渡すオプションの引数。

戻り値

Promise<Serializable>#

check

v1.9より前に追加

frame.check

非推奨

代わりにロケーターベースのlocator.check()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、selectorに一致する要素を以下の手順でチェックします。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待ちます。
一致する要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。要素がすでにチェックされている場合、このメソッドはすぐに解決されます。
forceオプションが設定されていない限り、一致する要素に対するアクション可能性チェックを待ちます。チェック中に要素がデタッチされた場合、すべてのアクションが再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心をクリックします。
要素が現在チェックされていることを確認します。そうでない場合、このメソッドはエラーをスローします。

指定されたタイムアウト内にすべてのステップが完了しなかった場合、このメソッドはTimeoutErrorをスローします。タイムアウトに0を渡すと、これを無効にできます。

使用法

await frame.check(selector);
await frame.check(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)追加されたバージョン: v1.11#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定すると、このメソッドは操作可能性 (actionability) チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するのに便利です。

戻り値

Promise<void>#

click

v1.9より前に追加

frame.click

非推奨

代わりにロケーターベースのlocator.click()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、selectorに一致する要素を以下の手順でクリックします。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待ちます。
forceオプションが設定されていない限り、一致する要素に対するアクション可能性チェックを待ちます。チェック中に要素がデタッチされた場合、すべてのアクションが再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心、または指定された位置をクリックします。
noWaitAfterオプションが設定されていない限り、開始されたナビゲーションが成功または失敗するのを待ちます。

使用法

await frame.click(selector);
await frame.click(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- button "left" | "right" | "middle" (オプション)#
  
  デフォルトはleftです。
- clickCount number (オプション)#
  
  デフォルトは1です。UIEvent.detailを参照してください。
- delay number (オプション)#
  
  mousedownとmouseupの間の待機時間（ミリ秒単位）。デフォルトは0です。
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#
  
  押下するモディファイアキー。操作中にこれらのモディファイアキーのみが押下されることを保証し、その後現在のモディファイアキーを元に戻します。指定しない場合、現在押下されているモディファイアキーが使用されます。"ControlOrMeta" は、WindowsとLinuxでは "Control" に、macOSでは "Meta" に解決されます。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは将来的にtrueがデフォルトになります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。このオプションが必要となるのは、アクセスできないページへのナビゲーションなどの例外的なケースに限られます。デフォルトはfalseです。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するが、アクションは実行しない場合に役立ちます。キーボードのmodifiersは、trialに関係なく押下され、これらのキーが押下された場合にのみ表示される要素をテストできます。

戻り値

Promise<void>#

dblclick

v1.9より前に追加

frame.dblclick

非推奨

代わりにロケーターベースのlocator.dblclick()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、selectorに一致する要素を以下の手順でダブルクリックします。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待ちます。
forceオプションが設定されていない限り、一致する要素に対するアクション可能性チェックを待ちます。チェック中に要素がデタッチされた場合、すべてのアクションが再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心、または指定された位置をダブルクリックします。dblclick()の最初のクリックがナビゲーションイベントをトリガーした場合、このメソッドはエラーをスローします。

注

frame.dblclick()は、2つのclickイベントと1つのdblclickイベントをディスパッチします。

使用法

await frame.dblclick(selector);
await frame.dblclick(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- button "left" | "right" | "middle" (オプション)#
  
  デフォルトはleftです。
- delay number (オプション)#
  
  mousedownとmouseupの間の待機時間（ミリ秒単位）。デフォルトは0です。
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#
  
  押下するモディファイアキー。操作中にこれらのモディファイアキーのみが押下されることを保証し、その後現在のモディファイアキーを元に戻します。指定しない場合、現在押下されているモディファイアキーが使用されます。"ControlOrMeta" は、WindowsとLinuxでは "Control" に、macOSでは "Meta" に解決されます。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するが、アクションは実行しない場合に役立ちます。キーボードのmodifiersは、trialに関係なく押下され、これらのキーが押下された場合にのみ表示される要素をテストできます。

戻り値

Promise<void>#

dispatchEvent

v1.9より前に追加

frame.dispatchEvent

非推奨

代わりにロケーターベースのlocator.dispatchEvent()を使用してください。ロケーターについて詳しくはこちら。

以下のスニペットは、要素に対してclickイベントをディスパッチします。要素の表示状態に関係なく、clickがディスパッチされます。これはelement.click()を呼び出すのと同等です。

使用法

await frame.dispatchEvent('button#submit', 'click');

内部的には、指定されたtypeに基づいてイベントのインスタンスを作成し、eventInitプロパティで初期化し、要素にディスパッチします。イベントはデフォルトでcomposed、cancelable、およびバブルします。

eventInitはイベント固有であるため、初期プロパティのリストについてはイベントのドキュメントを参照してください。

ライブオブジェクトをイベントに渡したい場合は、プロパティ値としてJSHandleを指定することもできます。

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await frame.evaluateHandle(() => new DataTransfer());
await frame.dispatchEvent('#source', 'dragstart', { dataTransfer });

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
type string #

DOMイベントの種類: "click"、"dragstart"など。
eventInit EvaluationArgument (オプション)#

オプションのイベント固有の初期化プロパティ。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

fill

v1.9より前に追加

frame.fill

非推奨

代わりにロケーターベースのlocator.fill()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、selectorに一致する要素を待ち、アクション可能性チェックを待ち、要素にフォーカスし、入力して、入力後にinputイベントをトリガーします。入力フィールドをクリアするために空の文字列を渡すこともできます。

ターゲット要素が<input>、<textarea>、または[contenteditable]要素ではない場合、このメソッドはエラーをスローします。ただし、要素が関連するコントロールを持つ<label>要素内にある場合、代わりにそのコントロールに入力されます。

細かなキーボードイベントを送信するには、locator.pressSequentially()を使用してください。

使用法

await frame.fill(selector, value);
await frame.fill(selector, value, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
value string #

<input>、<textarea>、または[contenteditable]要素に入力する値。
options Object (オプション)
- force boolean (オプション)追加バージョン: v1.13#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

focus

v1.9より前に追加

frame.focus

非推奨

代わりにロケーターベースのlocator.focus()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、セレクターに一致する要素を取得し、それにフォーカスを当てます。セレクターに一致する要素がない場合、一致する要素がDOMに現れるまでメソッドは待機します。

使用法

await frame.focus(selector);
await frame.focus(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

getAttribute

v1.9より前に追加

frame.getAttribute

非推奨

代わりにロケーターベースのlocator.getAttribute()を使用してください。ロケーターについて詳しくはこちら。

要素の属性値を返します。

使用法

await frame.getAttribute(selector, name);
await frame.getAttribute(selector, name, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
name string #

値を取得する属性名。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<null | string>#

hover

v1.9より前に追加

frame.hover

非推奨

代わりにロケーターベースのlocator.hover()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、selectorに一致する要素の上にカーソルを移動します。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待ちます。
forceオプションが設定されていない限り、一致する要素に対するアクション可能性チェックを待ちます。チェック中に要素がデタッチされた場合、すべてのアクションが再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心、または指定された位置にカーソルを移動します。

使用法

await frame.hover(selector);
await frame.hover(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#
  
  押下するモディファイアキー。操作中にこれらのモディファイアキーのみが押下されることを保証し、その後現在のモディファイアキーを元に戻します。指定しない場合、現在押下されているモディファイアキーが使用されます。"ControlOrMeta" は、WindowsとLinuxでは "Control" に、macOSでは "Meta" に解決されます。
- noWaitAfter boolean (オプション)追加バージョン: v1.28#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するが、アクションは実行しない場合に役立ちます。キーボードのmodifiersは、trialに関係なく押下され、これらのキーが押下された場合にのみ表示される要素をテストできます。

戻り値

Promise<void>#

innerHTML

v1.9より前に追加

frame.innerHTML

非推奨

代わりにロケーターベースのlocator.innerHTML()を使用してください。ロケーターについて詳しくはこちら。

element.innerHTMLを返します。

使用法

await frame.innerHTML(selector);
await frame.innerHTML(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<string>#

innerText

v1.9より前に追加

frame.innerText

非推奨

代わりにロケーターベースのlocator.innerText()を使用してください。ロケーターについて詳しくはこちら。

element.innerTextを返します。

使用法

await frame.innerText(selector);
await frame.innerText(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<string>#

inputValue

追加バージョン: v1.13

frame.inputValue

非推奨

代わりにロケーターベースのlocator.inputValue()を使用してください。ロケーターについて詳しくはこちら。

選択された<input>または<textarea>または<select>要素のinput.valueを返します。

非入力要素に対してはエラーをスローします。ただし、要素が関連するコントロールを持つ<label>要素内にある場合、コントロールの値を返します。

使用法

await frame.inputValue(selector);
await frame.inputValue(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<string>#

isChecked

v1.9より前に追加

frame.isChecked

非推奨

代わりにロケーターベースのlocator.isChecked()を使用してください。ロケーターについて詳しくはこちら。

要素がチェックされているかどうかを返します。要素がチェックボックスまたはラジオ入力でない場合、エラーをスローします。

使用法

await frame.isChecked(selector);
await frame.isChecked(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<boolean>#

isDisabled

v1.9より前に追加

frame.isDisabled

非推奨

代わりにロケーターベースのlocator.isDisabled()を使用してください。ロケーターについて詳しくはこちら。

要素が非活性であるかどうかを返します。有効の反対です。

使用法

await frame.isDisabled(selector);
await frame.isDisabled(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<boolean>#

isEditable

v1.9より前に追加

frame.isEditable

非推奨

代わりにロケーターベースのlocator.isEditable()を使用してください。ロケーターについて詳しくはこちら。

要素が編集可能であるかどうかを返します。

使用法

await frame.isEditable(selector);
await frame.isEditable(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<boolean>#

isHidden

v1.9より前に追加

frame.isHidden

非推奨

代わりにロケーターベースのlocator.isHidden()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

要素が隠されているかどうかを返します。visibleの反対です。どの要素とも一致しないセレクターは隠されていると見なされます。

使用法

await frame.isHidden(selector);
await frame.isHidden(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  非推奨
  このオプションは無視されます。frame.isHidden()は要素が隠されるのを待たずに即座に返します。

戻り値

Promise<boolean>#

isVisible

v1.9より前に追加

frame.isVisible

非推奨

代わりにロケーターベースのlocator.isVisible()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

要素が表示されているかどうかを返します。どの要素とも一致しないセレクターは表示されていないと見なされます。

使用法

await frame.isVisible(selector);
await frame.isVisible(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  非推奨
  このオプションは無視されます。frame.isVisible()は要素が表示されるのを待たずに即座に返します。

戻り値

Promise<boolean>#

press

v1.9より前に追加

frame.press

非推奨

代わりにロケーターベースのlocator.press()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

keyは、意図するkeyboardEvent.keyの値、またはテキストを生成するための単一の文字を指定できます。key値のスーパーセットはこちらで確認できます。キーの例は次のとおりです。

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp など。

次の修飾子ショートカットもサポートされています: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta。ControlOrMetaはWindowsおよびLinuxではControlに、macOSではMetaに解決されます。

Shiftを押し続けると、keyに対応するテキストが大文字で入力されます。

もしkeyが単一の文字の場合、大文字と小文字を区別するため、aとAの値はそれぞれ異なるテキストを生成します。

key: "Control+o", key: "Control++, key: "Control+Shift+T"のようなショートカットもサポートされています。修飾子を指定すると、修飾子が押され、その後のキーが押されている間も保持されます。

使用法

await frame.press(selector, key);
await frame.press(selector, key, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
key string #

押すキーの名前、またはArrowLeftやaのような生成する文字。
options Object (オプション)
- delay number (オプション)#
  
  keydownとkeyupの間の待機時間（ミリ秒）。デフォルトは0です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは将来的にtrueがデフォルトになります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。このオプションが必要となるのは、アクセスできないページへのナビゲーションなどの例外的なケースに限られます。デフォルトはfalseです。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

selectOption

v1.9より前に追加

frame.selectOption

非推奨

代わりにロケーターベースのlocator.selectOption()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

このメソッドは、セレクターに一致する要素を待ち、actionabilityチェックを待ち、指定されたすべてのオプションが<select>要素に存在するまで待機してから、これらのオプションを選択します。

ターゲット要素が<select>要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連するcontrolを持つ<label>要素内にある場合、代わりにそのコントロールが使用されます。

正常に選択されたオプション値の配列を返します。

指定されたすべてのオプションが選択されると、changeイベントとinputイベントをトリガーします。

使用法

// Single selection matching the value or label
frame.selectOption('select#colors', 'blue');

// single selection matching both the value and the label
frame.selectOption('select#colors', { label: 'Blue' });

// multiple selection
frame.selectOption('select#colors', 'red', 'green', 'blue');

引数

selector string #

クエリするセレクター。
values null | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#
- value string (オプション)
  
  option.valueで一致します。オプションです。
- label string (オプション)
  
  option.labelで一致します。オプションです。
- index number (オプション)
  
  インデックスで一致します。オプションです。
選択するオプション。もし<select>にmultiple属性がある場合、一致するすべてのオプションが選択され、そうでない場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。文字列値は値とラベルの両方に一致します。すべての指定されたプロパティが一致する場合に、オプションは一致すると見なされます。
options Object (オプション)
- force boolean (オプション)追加バージョン: v1.13#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<Array<string>>#

setChecked

追加バージョン: v1.15

frame.setChecked

非推奨

代わりにロケーターベースのlocator.setChecked()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

このメソッドは、セレクターに一致する要素を、以下の手順を実行してチェックまたはチェック解除します。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待機します。
一致した要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。
要素がすでに正しいチェック状態である場合、このメソッドは即座に返します。
一致した要素に対するactionabilityチェックを待ちます。forceオプションが設定されている場合は除きます。チェック中に要素がデタッチされた場合、操作全体が再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心をクリックします。
要素が現在チェックされているか、またはチェック解除されていることを確認します。そうでない場合、このメソッドはエラーをスローします。

指定されたtimeout内にすべての手順が完了しない場合、このメソッドはTimeoutErrorをスローします。タイムアウトにゼロを渡すと、この機能は無効になります。

使用法

await frame.setChecked(selector, checked);
await frame.setChecked(selector, checked, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
checked boolean #

チェックボックスをチェックまたはチェック解除するかどうか。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)#
  
  設定すると、このメソッドは操作可能性 (actionability) チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するのに便利です。

戻り値

Promise<void>#

setInputFiles

v1.9より前に追加

frame.setInputFiles

非推奨

代わりにロケーターベースのlocator.setInputFiles()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

ファイル入力の値をこれらのファイルパスまたはファイルに設定します。filePathsの一部が相対パスの場合、現在の作業ディレクトリを基準に解決されます。空の配列の場合、選択されたファイルをクリアします。

このメソッドは、セレクターがinput要素を指すことを期待します。ただし、要素が関連するcontrolを持つ<label>要素内にある場合、代わりにそのコントロールをターゲットとします。

使用法

await frame.setInputFiles(selector, files);
await frame.setInputFiles(selector, files, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
files string | Array<string> | Object | Array<Object>#
- name string
  
  ファイル名
- mimeType string
  
  ファイルの種類
- buffer Buffer
  
  ファイルの内容
options Object (オプション)
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

tap

v1.9より前に追加

frame.tap

非推奨

代わりにロケーターベースのlocator.tap()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

このメソッドは、以下の手順を実行して、セレクターに一致する要素をタップします。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待機します。
一致した要素に対するactionabilityチェックを待ちます。forceオプションが設定されている場合は除きます。チェック中に要素がデタッチされた場合、操作全体が再試行されます。
必要に応じて要素をビューにスクロールします。
page.touchscreenを使用して要素の中心、または指定されたpositionをタップします。

注

frame.tap()には、ブラウザコンテキストのhasTouchオプションがtrueに設定されている必要があります。

使用法

await frame.tap(selector);
await frame.tap(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#
  
  押下するモディファイアキー。操作中にこれらのモディファイアキーのみが押下されることを保証し、その後現在のモディファイアキーを元に戻します。指定しない場合、現在押下されているモディファイアキーが使用されます。"ControlOrMeta" は、WindowsとLinuxでは "Control" に、macOSでは "Meta" に解決されます。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するが、アクションは実行しない場合に役立ちます。キーボードのmodifiersは、trialに関係なく押下され、これらのキーが押下された場合にのみ表示される要素をテストできます。

戻り値

Promise<void>#

textContent

v1.9より前に追加

frame.textContent

非推奨

代わりにロケーターベースのlocator.textContent()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

element.textContentを返します。

使用法

await frame.textContent(selector);
await frame.textContent(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<null | string>#

type

v1.9より前に追加

frame.type

非推奨

ほとんどの場合、代わりにlocator.fill()を使用する必要があります。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。その場合はlocator.pressSequentially()を使用してください。

テキスト内の各文字に対して、keydown、keypress/input、およびkeyupイベントを送信します。frame.typeは、細かく調整されたキーボードイベントを送信するために使用できます。フォームフィールドに値を入力するには、frame.fill()を使用します。

ControlやArrowDownのような特殊なキーを押すには、keyboard.press()を使用します。

使用法

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
text string #

フォーカスされた要素に入力するテキスト。
options Object (オプション)
- delay number (オプション)#
  
  キー押下間の待機時間（ミリ秒）。デフォルトは0です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<void>#

uncheck

v1.9より前に追加

frame.uncheck

非推奨

代わりにロケーターベースのlocator.uncheck()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

このメソッドは、セレクターに一致する要素を、以下の手順を実行してチェック解除します。

セレクターに一致する要素を見つけます。見つからない場合は、一致する要素がDOMにアタッチされるまで待機します。
一致した要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。要素がすでにチェック解除されている場合、このメソッドは即座に返します。
一致した要素に対するactionabilityチェックを待ちます。forceオプションが設定されている場合は除きます。チェック中に要素がデタッチされた場合、操作全体が再試行されます。
必要に応じて要素をビューにスクロールします。
page.mouseを使用して要素の中心をクリックします。
要素が現在チェック解除されていることを確認します。そうでない場合、このメソッドはエラーをスローします。

使用法

await frame.uncheck(selector);
await frame.uncheck(selector, options);

引数

selector string #

要素を検索するセレクター。複数の要素がセレクターを満たす場合、最初の要素が使用されます。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能性 (actionability) チェックをバイパスするかどうか。デフォルトはfalseです。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)追加されたバージョン: v1.11#
  - x number
  - y number
  要素のパディングボックスの左上隅に対する相対的な点を使用します。指定しない場合、要素の可視点の一部を使用します。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- trial boolean (オプション)追加されたバージョン: v1.11#
  
  設定すると、このメソッドは操作可能性 (actionability) チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。要素がアクションを実行する準備が整うまで待機するのに便利です。

戻り値

Promise<void>#

v1.9より前に追加

frame.waitForNavigation

非推奨

このメソッドは本質的に競合状態になりやすいため、代わりにframe.waitForURL()を使用してください。

フレームナビゲーションを待ち、メインリソースのレスポンスを返します。複数のリダイレクトが発生した場合、ナビゲーションは最後のリダイレクトのレスポンスで解決されます。異なるアンカーへのナビゲーションやHistory APIの使用によるナビゲーションの場合、ナビゲーションはnullで解決されます。

使用法

このメソッドは、フレームが新しいURLに移動するのを待ちます。間接的にフレームをナビゲーションさせるコードを実行する際に役立ちます。この例を検討してください。

// Start waiting for navigation before clicking. Note no await.
const navigationPromise = page.waitForNavigation();
await page.getByText('Navigate after timeout').click();
await navigationPromise;

注

History APIを使用してURLを変更することはナビゲーションと見なされます。

引数

options Object (オプション)
- timeout number (オプション)#
  
  操作の最大時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）。デフォルト値は、設定のnavigationTimeoutオプション、またはbrowserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()、またはpage.setDefaultTimeout()メソッドを使用して変更できます。
- url string | RegExp | function(URL):boolean (オプション)#
  
  ナビゲーションを待機する間に一致させるためのグロブパターン、正規表現パターン、またはURLを受け取る述語。ワイルドカード文字を含まない文字列がパラメータとして渡された場合、このメソッドは文字列と完全に一致するURLへのナビゲーションを待機することに注意してください。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (オプション)#
  
  いつ操作が成功したとみなすか。デフォルトはloadです。イベントは以下のいずれかです。
  - 'domcontentloaded' - DOMContentLoadedイベントが発火したときに操作が終了したとみなします。
  - 'load' - loadイベントが発火したときに操作が終了したとみなします。
  - 'networkidle' - 非推奨 少なくとも500ミリ秒間ネットワーク接続がないときに操作が終了したとみなします。テストにはこのメソッドを使用せず、代わりにWebアサーションに依存して準備状況を評価してください。
  - 'commit' - ネットワーク応答が受信され、ドキュメントの読み込みが開始されたときに操作が終了したとみなします。

戻り値

Promise<null | Response>#

waitForSelector

v1.9より前に追加

frame.waitForSelector

非推奨

代わりに、視認性をアサートするウェブアサーション、またはロケーターベースのlocator.waitFor()を使用してください。ロケーターの詳細についてはこちらをご覧ください。

セレクターで指定された要素がstateオプションを満たした場合に返します。hiddenまたはdetachedを待機している場合はnullを返します。

注

Playwrightは、アクションを実行する前に要素が準備されるのを自動的に待ちます。Locatorオブジェクトとウェブファーストのアサーションを使用すると、コードからwait-for-selectorが不要になります。

セレクターがstateオプション（DOMに表示/非表示になるか、表示/非表示になるか）を満たすまで待機します。メソッドの呼び出し時にセレクターが既に条件を満たしている場合、メソッドは即座に返します。timeoutミリ秒間セレクターが条件を満たさない場合、関数は例外をスローします。

使用法

このメソッドはナビゲーションをまたいで動作します。

const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  for (const currentURL of ['https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
    const element = await page.mainFrame().waitForSelector('img');
    console.log('Loaded image: ' + await element.getAttribute('src'));
  }
  await browser.close();
})();

引数

selector string #

クエリするセレクター。
options Object (オプション)
- state "attached" | "detached" | "visible" | "hidden" (オプション)#
  
  デフォルトは'visible'です。次のいずれかです。
  - 'attached' - 要素がDOMに存在するまで待機します。
  - 'detached' - 要素がDOMに存在しないまで待機します。
  - 'visible' - 要素が空でない境界ボックスを持ち、visibility:hiddenでないまで待機します。コンテンツがない要素、またはdisplay:noneが設定されている要素は、空の境界ボックスを持つため、表示されているとは見なされないことに注意してください。
  - 'hidden' - 要素がDOMからデタッチされるか、空の境界ボックスを持つか、またはvisibility:hiddenであるまで待機します。これは'visible'オプションとは逆です。
- strict boolean (オプション)追加バージョン: v1.14#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大待ち時間（ミリ秒単位）。デフォルトは0（タイムアウトなし）です。デフォルト値は、設定のactionTimeoutオプション、またはbrowserContext.setDefaultTimeout()またはpage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

Promise<null | ElementHandle>#

waitForTimeout

v1.9より前に追加

frame.waitForTimeout

非推奨

本番環境でタイムアウトを待機しないでください。時間を待機するテストは本質的に不安定です。自動的に待機するLocatorアクションとウェブアサーションを使用してください。

指定されたtimeoutミリ秒間待機します。

frame.waitForTimeout()はデバッグ目的でのみ使用すべきであることに注意してください。本番環境でタイマーを使用するテストは不安定になる傾向があります。代わりに、ネットワークイベント、セレクターの可視化などのシグナルを使用してください。

使用法

await frame.waitForTimeout(timeout);

引数

timeout number #

待機するタイムアウト

戻り値

Promise<void>#

メソッド​

addScriptTag​

addStyleTag​

childFrames​

content​

dragAndDrop​

evaluate​

evaluateHandle​

frameElement​

frameLocator​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

goto​

isDetached​

isEnabled​

locator​

name​

page​

parentFrame​

setContent​

title​

url​

waitForFunction​

waitForLoadState​

waitForURL​

非推奨​

$​

$$​

$eval​

$$eval​

check​

click​

dblclick​

dispatchEvent​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isHidden​

isVisible​

press​

selectOption​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForNavigation​

waitForSelector​

waitForTimeout​

メソッド

`addScriptTag`

`addStyleTag`

`childFrames`

`content`

`dragAndDrop`

`evaluate`

`evaluateHandle`

`frameElement`

`frameLocator`

`getByAltText`

`getByLabel`

`getByPlaceholder`

`getByRole`

getByTestId

getByText

getByTitle

goto

isDetached

isEnabled

locator

name

page

parentFrame

setContent

title

url

waitForFunction

waitForLoadState

waitForURL

非推奨

$

$$

$eval

$$eval

check

click

dblclick

dispatchEvent

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isHidden

isVisible

press

selectOption

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForNavigation

waitForSelector

waitForTimeout