Frame

В каждый момент времени страница предоставляет текущее дерево фреймов с помощью методов page.mainFrame() и frame.childFrames().

Жизненный цикл объекта Frame контролируется тремя событиями, отправляемыми объектом страницы:

• 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​

Возвращает добавленный тег при срабатывании события onload таблицы стилей или после внедрения содержимого CSS во фрейм.

Добавляет тег <script> на страницу с указанным URL или содержимым.

Использование

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

Аргументы

• options Object (необязательно)

  • content string (необязательно)

    Исходный код JavaScript для внедрения во фрейм.

  • path string (необязательно)

    Путь к файлу JavaScript для внедрения во фрейм. Если path — относительный путь, он разрешается относительно текущего рабочего каталога.

  • type string (необязательно)

    Тип скрипта. Используйте 'module', чтобы загрузить модуль JavaScript ES6. Подробнее см. в разделе script.

  • url string (необязательно)

    URL добавляемого скрипта.

Возвращает

• Promise<ElementHandle>

addStyleTag​

Возвращает добавленный тег при срабатывании события onload таблицы стилей или после внедрения содержимого CSS во фрейм.

Добавляет тег <link rel="stylesheet"> на страницу с указанным URL или тег <style type="text/css"> с содержимым.

Использование

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

Аргументы

• options Object (необязательно)

  • content string (необязательно)

    Исходный код CSS для внедрения во фрейм.

  • path string (необязательно)

    Путь к файлу CSS для внедрения во фрейм. Если path — относительный путь, он разрешается относительно текущего рабочего каталога.

  • url string (необязательно)

    URL тега <link>.

Возвращает

• Promise<ElementHandle>

childFrames​

Использование

frame.childFrames();

Возвращает

• Array<Frame>

content​

Получает полное HTML-содержимое фрейма, включая doctype.

Использование

await frame.content();

Возвращает

• Promise<string>

dragAndDrop​

Использование

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

Аргументы

• source string

  Селектор для поиска перетаскиваемого элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• target string

  Селектор для поиска элемента, на который нужно перетащить объект. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • force boolean (необязательно)

    Нужно ли пропустить проверки возможности выполнения действия. По умолчанию false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright страницу до элемента перед выполнением действия. По умолчанию "auto": элемент прокручивается в область просмотра, если это необходимо, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано "none", Playwright не прокручивает страницу до элемента, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это полезно, чтобы проверить, доступен ли элемент пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • sourcePosition Object (необязательно)

    • x number

    • y number

    Щелчок по исходному элементу в указанной точке относительно его верхнего левого угла внутренней области. Если точка не задана, используется видимая точка элемента.

  • steps number (необязательно)

    По умолчанию 1. Отправляет n интерполированных событий mousemove, имитируя перемещение между mousedown и mouseup перетаскивания. Если задано значение 1, в конечной точке отправляется одно событие mousemove.

  • strict boolean (необязательно)

    Если задано значение true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • targetPosition Object (необязательно)

    • x number

    • y number

    Отпускает кнопку мыши над целевым элементом в указанной точке относительно его верхнего левого угла внутренней области. Если точка не задана, используется видимая точка элемента.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если задано, этот метод только выполняет проверки возможности выполнения действия, не выполняя само действие. По умолчанию false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его.

Возвращает

• Promise<void>

evaluate​

Возвращает результат выполнения pageFunction.

Если функция, переданная в frame.evaluate(), возвращает Promise, frame.evaluate() дождётся выполнения промиса и вернёт его значение.

Если функция, переданная в frame.evaluate(), возвращает значение, которое не является сериализуемым, 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.evaluateHandle('document.body');
const html = await frame.evaluate(([body, suffix]) =>
  body.innerHTML + suffix, [bodyHandle, 'hello'],
);
await bodyHandle.dispose();

Аргументы

• pageFunction function | string

  Функция для выполнения в контексте страницы.

• arg EvaluationArgument (необязательно)

  Необязательный аргумент, передаваемый в pageFunction.

• options Object (необязательно)

  • exposeFunctions boolean (необязательно)

    Если задано значение true, функции, переданные внутри arg, становятся доступными на странице и могут вызываться из функции страницы. При вызове функция возвращает Promise со своим результатом. Внутри каждая функция предоставляется через page.exposeFunction(), поэтому технически она доступна из всех фреймов и контекстов страницы. Предоставленные функции удаляются при навигации верхнего уровня. По умолчанию false; в этом случае функции не сериализуются, и их передача вызывает ошибку.

Возвращает

• Promise<Serializable>

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.

• options Object (необязательно)

  • exposeFunctions boolean (необязательно)

    Если задано значение true, функции, переданные внутри arg, становятся доступными на странице и могут вызываться из функции страницы. При вызове функция возвращает Promise со своим результатом. Внутри каждая функция предоставляется через page.exposeFunction(), поэтому технически она доступна из всех фреймов и контекстов страницы. Предоставленные функции удаляются при навигации верхнего уровня. По умолчанию false; в этом случае функции не сериализуются, и их передача вызывает ошибку.

Возвращает

• Promise<JSHandle>

frameElement​

Возвращает дескриптор элемента frame или iframe, соответствующего этому фрейму.

Этот метод является обратным по отношению к elementHandle.contentFrame(). Обратите внимание, что возвращаемый дескриптор фактически принадлежит родительскому фрейму.

Метод вызывает ошибку, если фрейм был отсоединён до того, как frameElement() вернёт результат.

Использование

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

Возвращает

• Promise<ElementHandle>

frameLocator​

При работе с iframe можно создать локатор фрейма, который войдёт в iframe и позволит выбирать элементы внутри него.

Если вызвать метод без селектора, поиск начнётся в этом фрейме или в любом из вложенных в него iframe, поэтому нет необходимости сначала находить каждый iframe. Обратите внимание: остальная часть локатора разрешается внутри одного фрейма, как и любой другой локатор. Если ему соответствуют элементы в нескольких фреймах, возникает ошибка.

Использование

Следующий фрагмент находит элемент с текстом "Submit" в iframe с идентификатором my-frame, например <iframe id="my-frame">:

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

Следующий фрагмент находит кнопку либо в этом фрейме, либо в одном из вложенных в него iframe:

const locator = frame.frameLocator().getByRole('button');
await locator.click();

Аргументы

• selector string (необязательно)

  Селектор, соответствующий элементу фрейма. Если он не указан, локатор ищет соответствие в этом фрейме или в любом из вложенных в него iframe.

Возвращает

• FrameLocator

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​

Позволяет находить элементы ввода по тексту связанного элемента <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​

Позволяет находить элементы ввода по тексту заполнителя.

Использование

Например, рассмотрим следующую 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​

Позволяет находить элементы по их роли 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.

  • description string | RegExp (необязательно)

    Параметр для сопоставления с доступным описанием. По умолчанию сопоставление не учитывает регистр и выполняется по подстроке. Используйте exact, чтобы изменить это поведение.

    Подробнее о доступном описании.

  • disabled boolean (необязательно)

    Атрибут, обычно задаваемый с помощью aria-disabled или disabled.

    примечание

    В отличие от большинства других атрибутов, disabled наследуется по иерархии DOM. Подробнее: aria-disabled.

  • exact boolean (необязательно)

    Определяет, должны ли имя и описание совпадать точно: с учетом регистра и полностью. По умолчанию — false. Не учитывается, если значение является регулярным выражением. Обратите внимание: при точном сопоставлении пробелы всё равно обрезаются.

  • 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​

Находит элемент по идентификатору теста.

Использование

Рассмотрим следующую структуру DOM.

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

Элемент можно найти по его идентификатору теста:

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

Аргументы

• testId string | RegExp

  Идентификатор, по которому нужно найти элемент.

Возвращает

• Locator

Подробности

По умолчанию в качестве идентификатора теста используется атрибут data-testid. При необходимости используйте selectors.setTestIdAttribute(), чтобы настроить другой атрибут идентификатора теста.

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

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

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

Подробности

При сопоставлении по тексту пробелы всегда нормализуются, даже при точном совпадении. Например, несколько пробелов заменяются одним, переносы строк — пробелами, а начальные и конечные пробелы игнорируются.

Элементы ввода типа button и submit сопоставляются по значению value, а не по текстовому содержимому. Например, поиск по тексту "Log in" находит <input type=button value="Log in">.

getByTitle​

Позволяет находить элементы по атрибуту title.

Использование

Рассмотрим следующую структуру DOM.

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

После поиска по тексту заголовка можно проверить количество проблем:

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

Аргументы

• text string | RegExp

  Текст, по которому нужно найти элемент.

• options Object (необязательно)

  • exact boolean (необязательно)

    Определяет, искать ли точное совпадение: с учетом регистра и полностью. По умолчанию — false. Игнорируется при поиске по регулярному выражению. Обратите внимание: при точном совпадении пробелы всё равно обрезаются.

Возвращает

• Locator

goto​

Возвращает ответ на запрос основного ресурса. При нескольких перенаправлениях навигация завершится ответом последнего перенаправления.

Метод выдаст ошибку в следующих случаях:

• возникла ошибка SSL (например, при использовании самоподписанных сертификатов).
• целевой URL недействителен.
• во время навигации истёк тайм-аут.
• удалённый сервер не отвечает или недоступен.
• не удалось загрузить основной ресурс.

Метод не выдаст ошибку, если удалённый сервер вернул любой допустимый код состояния HTTP, включая 404 «Не найдено» и 500 «Внутренняя ошибка сервера». Код состояния такого ответа можно получить, вызвав response.status().

примечание

Метод либо выдаёт ошибку, либо возвращает ответ на запрос основного ресурса. Исключение составляют переход к about:blank или переход на тот же URL с другим хешем: они завершаются успешно и возвращают null.

примечание

Режим без графического интерфейса не поддерживает переход к PDF-документу. См. исходную задачу.

Использование

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

Аргументы

• url string

  URL, на который нужно перейти во фрейме. URL должен включать схему, например https://.

• options Object (необязательно)

  • referer string (необязательно)

    Значение заголовка Referer. Если оно указано, то будет иметь приоритет над значением заголовка referer, заданным с помощью page.setExtraHTTPHeaders().

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время выполнения операции в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра navigationTimeout в конфигурации или методов browserContext.setDefaultNavigationTimeout(), browserContext.setDefaultTimeout(), page.setDefaultNavigationTimeout() или page.setDefaultTimeout().

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (необязательно)

    Когда считать операцию завершённой; по умолчанию — load. Возможные события:

    • 'domcontentloaded' — считать операцию завершённой при возникновении события DOMContentLoaded.
    • 'load' — считать операцию завершённой при возникновении события load.
    • 'networkidle' — НЕ РЕКОМЕНДУЕТСЯ считать операцию завершённой, если в течение как минимум 500 мс отсутствуют сетевые соединения. Не используйте этот метод для тестирования; вместо этого проверяйте готовность с помощью веб-утверждений.
    • 'commit' — считать операцию завершённой, когда получен ответ сети и началась загрузка документа.

Возвращает

• Promise<null | Response>

isDetached​

Возвращает true, если фрейм отсоединён, и false в противном случае.

Использование

frame.isDetached();

Возвращает

• boolean

isEnabled​

Возвращает, включён ли элемент.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если селектор соответствует нескольким элементам, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<boolean>

locator​

Метод возвращает локатор элемента, с помощью которого можно выполнять действия на этой странице / во фрейме. Локатор разрешается в элемент непосредственно перед выполнением действия, поэтому серия действий с одним и тем же локатором фактически может выполняться над разными элементами DOM. Это происходит, если структура DOM изменилась между действиями.

Подробнее о локаторах.

Подробнее о локаторах.

Использование

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

Аргументы

• selector string

  Селектор, используемый для поиска элемента DOM.

• options Object (необязательно)

  • has Locator (необязательно)

    Сужает результаты метода до тех, которые содержат элементы, соответствующие этому относительному локатору. Например, article, в котором есть text=Playwright, соответствует <article><div>Playwright</div></article>.

    Внутренний локатор должен быть относительным к внешнему; поиск начинается с соответствия внешнего локатора, а не с корня документа. Например, можно найти content, в котором есть div, внутри <article><content><div>Playwright</div></content></article>. Однако поиск content, в котором есть article div, завершится неудачей, поскольку внутренний локатор должен быть относительным и не должен использовать элементы за пределами content.

    Обратите внимание: внешний и внутренний локаторы должны принадлежать одному фрейму. Внутренний локатор не должен содержать FrameLocator.

  • hasNot Locator (необязательно)

    Находит элементы, не содержащие элемент, соответствующий внутреннему локатору. Внутренний локатор применяется к внешнему. Например, article, в котором нет div, соответствует <article><span>Playwright</span></article>.

    Обратите внимание: внешний и внутренний локаторы должны принадлежать одному фрейму. Внутренний локатор не должен содержать FrameLocator.

  • hasNotText string | RegExp (необязательно)

    Находит элементы, внутри которых нет указанного текста, в том числе в дочерних или вложенных элементах. Если передана строка string, сопоставление не учитывает регистр и выполняется по подстроке.

  • hasText string | RegExp (необязательно)

    Находит элементы, внутри которых содержится указанный текст, в том числе в дочерних или вложенных элементах. Если передана строка string, сопоставление не учитывает регистр и выполняется по подстроке. Например, "Playwright" соответствует <article><div>Playwright</div></article>.

Возвращает

• Locator

name​

Возвращает атрибут name фрейма, заданный в теге.

Если атрибут name пуст, возвращает атрибут id.

примечание

Это значение вычисляется один раз при создании фрейма и не обновляется, если атрибут изменится позднее.

Использование

frame.name();

Возвращает

• string

page​

Возвращает страницу, содержащую этот фрейм.

Использование

frame.page();

Возвращает

• Page

parentFrame​

Родительский фрейм, если он есть. Для отсоединённых и главных фреймов возвращается null.

Использование

frame.parentFrame();

Возвращает

• null | Frame

setContent​

Этот метод внутри вызывает document.write(), наследуя все его специфические характеристики и поведение.

Использование

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

Аргументы

• html string

  HTML-разметка для добавления на страницу.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время выполнения операции в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра navigationTimeout в конфигурации или методов browserContext.setDefaultNavigationTimeout(), browserContext.setDefaultTimeout(), page.setDefaultNavigationTimeout() или page.setDefaultTimeout().

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (необязательно)

    Условие успешного завершения операции; по умолчанию — load. Возможны следующие события:

    • 'domcontentloaded' — считать операцию завершённой, когда произойдёт событие DOMContentLoaded.
    • 'load' — считать операцию завершённой, когда произойдёт событие load.
    • 'networkidle' — НЕ РЕКОМЕНДУЕТСЯ считать операцию завершённой, если сетевые подключения отсутствуют не менее 500 мс. Не используйте этот метод для тестирования; вместо этого оценивайте готовность с помощью веб-проверок.
    • 'commit' — считать операцию завершённой, когда получен сетевой ответ и началась загрузка документа.

Возвращает

• Promise<void>

title​

Возвращает заголовок страницы.

Использование

await frame.title();

Возвращает

• Promise<string>

url​

Возвращает URL фрейма.

Использование

frame.url();

Возвращает

• string

waitForFunction​

Возвращает значение, когда pageFunction возвращает истинное значение.

Использование

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.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время ожидания в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<JSHandle>

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 мс. Не используйте этот метод для тестирования; вместо этого оценивайте готовность с помощью веб-проверок.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить ожидание с помощью AbortSignal. Если сигнал прерван, ожидание будет отменено, а операция вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время выполнения операции в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра navigationTimeout в конфигурации или методов browserContext.setDefaultNavigationTimeout(), browserContext.setDefaultTimeout(), page.setDefaultNavigationTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<void>

waitForURL​

Ожидает перехода фрейма по указанному URL.

Использование

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

Аргументы

• url string | RegExp | URLPattern | function(URL):boolean

  Шаблон glob, регулярное выражение, шаблон URL или предикат, принимающий URL для сопоставления во время ожидания перехода. Обратите внимание: если параметр — строка без подстановочных знаков, метод будет ждать перехода на URL, в точности совпадающий с этой строкой.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить ожидание с помощью AbortSignal. Если сигнал прерван, ожидание будет отменено, а операция вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время выполнения операции в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра navigationTimeout в конфигурации или методов browserContext.setDefaultNavigationTimeout(), browserContext.setDefaultTimeout(), page.setDefaultNavigationTimeout() или page.setDefaultTimeout().

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (необязательно)

    Условие успешного завершения операции; по умолчанию — load. Возможны следующие события:

    • 'domcontentloaded' — считать операцию завершённой, когда произойдёт событие DOMContentLoaded.
    • 'load' — считать операцию завершённой, когда произойдёт событие load.
    • 'networkidle' — НЕ РЕКОМЕНДУЕТСЯ считать операцию завершённой, если сетевые подключения отсутствуют не менее 500 мс. Не используйте этот метод для тестирования; вместо этого оценивайте готовность с помощью веб-проверок.
    • 'commit' — считать операцию завершённой, когда получен сетевой ответ и началась загрузка документа.

Возвращает

• Promise<void>

Устаревшие методы​

$​

Не рекомендуется

Вместо этого используйте frame.locator(), основанный на локаторе. Подробнее о локаторах.

Возвращает ElementHandle, указывающий на элемент фрейма.

предупреждение

Использование ElementHandle не рекомендуется; вместо этого используйте объекты Locator и веб-проверки.

Метод находит во фрейме элемент, соответствующий указанному селектору. Если совпадений нет, возвращает null.

Использование

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

Аргументы

• selector string

  Селектор для поиска.

• options Object (необязательно)

  • strict boolean (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует нескольким элементам, вызов выдаёт исключение.

Возвращает

• Promise<null | ElementHandle>

$$​

Не рекомендуется

Вместо этого используйте frame.locator(), основанный на локаторе. Подробнее о локаторах.

Возвращает ElementHandle для элементов фрейма.

предупреждение

Использование ElementHandle не рекомендуется; вместо этого используйте объекты Locator.

Метод находит во фрейме все элементы, соответствующие указанному селектору. Если совпадений нет, возвращает пустой массив.

Использование

await frame.$$(selector);

Аргументы

• selector string

  Селектор для поиска.

Возвращает

• Promise<Array<ElementHandle>>

$eval​

Не рекомендуется

Этот метод не ожидает прохождения элементом проверок возможности взаимодействия, поэтому тесты могут быть нестабильными. Вместо этого используйте locator.evaluate(), другие вспомогательные методы Locator или веб-проверки.

Возвращает значение, возвращённое pageFunction.

Метод находит во фрейме элемент, соответствующий указанному селектору, и передаёт его первым аргументом в pageFunction. Если совпадений нет, метод выдаёт ошибку.

Если pageFunction возвращает Promise, метод frame.$eval() дождётся выполнения промиса и вернёт его значение.

Использование

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 (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует нескольким элементам, вызов выдаёт исключение.

Возвращает

• Promise<Serializable>

$$eval​

Не рекомендуется

В большинстве случаев лучше подходят locator.evaluateAll(), другие вспомогательные методы Locator и веб-проверки.

Возвращает значение, возвращённое pageFunction.

Метод находит во фрейме все элементы, соответствующие указанному селектору, и передаёт массив найденных элементов первым аргументом в pageFunction.

Если pageFunction возвращает Promise, метод frame.$$eval() дождётся выполнения промиса и вернёт его значение.

Использование

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​

Не рекомендуется

Вместо этого используйте locator.check(), основанный на локаторе. Подробнее о локаторах.

Этот метод устанавливает флажок для элемента, соответствующего selector, выполняя следующие шаги:

1. Находит элемент, соответствующий selector. Если такого элемента нет, ожидает появления соответствующего элемента в DOM.
2. Убеждается, что найденный элемент — это флажок или переключатель. Если это не так, метод выдаёт ошибку. Если флажок уже установлен, метод немедленно возвращает управление.
3. Ожидает прохождения найденным элементом проверок возможности взаимодействия, если не задан параметр force. Если во время проверок элемент отсоединяется от DOM, действие выполняется повторно.
4. При необходимости прокручивает страницу, чтобы элемент оказался в области просмотра.
5. Использует page.mouse, чтобы щёлкнуть по центру элемента.
6. Убеждается, что флажок установлен. Если это не так, метод выдаёт ошибку.

Если выполнение всех шагов занимает больше времени, чем указано в параметре timeout, метод выдаёт ошибку TimeoutError. Передача нулевого значения отключает тайм-аут.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если ему соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • force boolean (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не влияет на поведение.

    Этот параметр не влияет на поведение.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла области внутренних отступов элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright элемент в область видимости перед выполнением действия. По умолчанию — "auto": элемент прокручивается в область видимости при необходимости, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано значение "none", Playwright не прокручивает элемент, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это удобно для проверки того, что пользователь может добраться до элемента без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выдаёт исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, этот метод выполняет только проверки возможности выполнения действия, не выполняя само действие. По умолчанию — false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его.

Возвращает

• Promise<void>

click​

Не рекомендуется

Вместо этого используйте locator.click(), основанный на локаторе. Подробнее о локаторах.

Этот метод щёлкает по элементу, соответствующему селектору, выполняя следующие шаги:

1. Находит элемент, соответствующий селектору. Если такого элемента нет, ожидает его появления в DOM.
2. Ожидает прохождения проверок возможности выполнения действия для найденного элемента, если не задан параметр force. Если во время проверок элемент отсоединяется, вся операция повторяется.
3. При необходимости прокручивает страницу, чтобы элемент оказался в области видимости.
4. Использует page.mouse, чтобы щёлкнуть по центру элемента или в указанной позиции.
5. Ожидает успешного завершения или сбоя инициированной навигации, если не задан параметр noWaitAfter.

Если все шаги вместе не завершатся за указанное время тайм-аута, этот метод выдаст ошибку TimeoutError. Передача нулевого значения отключает тайм-аут.

Использование

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 (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)

    Модификаторы клавиатуры, которые нужно нажать. Гарантирует, что во время операции будут нажаты только эти модификаторы, а затем восстанавливает исходное состояние модификаторов. Если параметр не указан, используются уже нажатые модификаторы. "ControlOrMeta" соответствует "Control" в Windows и Linux и "Meta" в macOS.

  • noWaitAfter boolean (необязательно)

    Устарело

    В будущем для этого параметра значением по умолчанию станет true.

    Действия, инициирующие навигацию, ожидают её выполнения и начала загрузки страниц. От ожидания можно отказаться, установив этот флаг. Этот параметр нужен только в исключительных случаях, например при переходе на недоступные страницы. По умолчанию — false.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла области внутренних отступов элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright элемент в область видимости перед выполнением действия. По умолчанию — "auto": элемент прокручивается в область видимости при необходимости, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано значение "none", Playwright не прокручивает элемент, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это удобно для проверки того, что пользователь может добраться до элемента без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выдаёт исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, этот метод выполняет только проверки возможности выполнения действия, не выполняя само действие. По умолчанию — false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его. Обратите внимание: клавиатура modifiers будет нажата независимо от trial, чтобы можно было тестировать элементы, которые видны только при нажатии этих клавиш.

Возвращает

• Promise<void>

dblclick​

Не рекомендуется

Вместо этого используйте locator.dblclick(), основанный на локаторе. Подробнее о локаторах.

Этот метод выполняет двойной щелчок по элементу, соответствующему селектору, выполняя следующие шаги:

1. Находит элемент, соответствующий селектору. Если такого элемента нет, ожидает его появления в DOM.
2. Ожидает прохождения проверок возможности выполнения действия для найденного элемента, если не задан параметр force. Если во время проверок элемент отсоединяется, вся операция повторяется.
3. При необходимости прокручивает страницу, чтобы элемент оказался в области видимости.
4. Использует page.mouse, чтобы выполнить двойной щелчок по центру элемента или в указанной позиции. Если первый щелчок dblclick() инициирует навигацию, этот метод выдаст ошибку.

Если все шаги вместе не завершатся за указанное время тайм-аута, этот метод выдаст ошибку TimeoutError. Передача нулевого значения отключает тайм-аут.

Примечание

frame.dblclick() отправляет два события click и одно событие 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 (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)

    Модификаторы клавиатуры, которые нужно нажать. Гарантирует, что во время операции будут нажаты только эти модификаторы, а затем восстанавливает исходное состояние модификаторов. Если параметр не указан, используются уже нажатые модификаторы. "ControlOrMeta" соответствует "Control" в Windows и Linux и "Meta" в macOS.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не влияет на поведение.

    Этот параметр не влияет на поведение.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла области внутренних отступов элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright элемент в область видимости перед выполнением действия. По умолчанию — "auto": элемент прокручивается в область видимости при необходимости, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано значение "none", Playwright не прокручивает элемент, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это удобно для проверки того, что пользователь может добраться до элемента без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выдаёт исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, этот метод выполняет только проверки возможности выполнения действия, не выполняя само действие. По умолчанию — false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его. Обратите внимание: клавиатура modifiers будет нажата независимо от trial, чтобы можно было тестировать элементы, которые видны только при нажатии этих клавиш.

Возвращает

• Promise<void>

dispatchEvent​

Не рекомендуется

Вместо этого используйте locator.dispatchEvent(), основанный на локаторе. Подробнее о локаторах.

Приведённый ниже фрагмент отправляет событие click для элемента. Независимо от видимости элемента отправляется событие click. Это эквивалентно вызову element.click().

Использование

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

Внутри метод создаёт экземпляр события на основе указанного типа, инициализирует его свойствами eventInit и отправляет для элемента. По умолчанию события являются composed, cancelable и всплывают.

Поскольку eventInit зависит от типа события, обратитесь к документации по событиям, чтобы ознакомиться со списками начальных свойств:

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

Также можно указать 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 (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выдаёт исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<void>

fill​

Не рекомендуется

Вместо этого используйте locator.fill(), основанный на локаторе. Подробнее о локаторах.

Этот метод ожидает появления элемента, соответствующего селектору, прохождения проверок возможности выполнения действия, переводит фокус на элемент, заполняет его и после заполнения отправляет событие 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 (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не имеет эффекта.

    Этот параметр не имеет эффекта.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<void>

focus​

Не рекомендуется

Вместо этого используйте locator.focus() на основе локатора. Подробнее о локаторах.

Этот метод находит элемент с помощью селектора и устанавливает на него фокус. Если элемент, соответствующий селектору, отсутствует, метод ожидает его появления в DOM.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<void>

getAttribute​

Не рекомендуется

Вместо этого используйте locator.getAttribute() на основе локатора. Подробнее о локаторах.

Возвращает значение атрибута элемента.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• name string

  Имя атрибута, значение которого нужно получить.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<null | string>

hover​

Не рекомендуется

Вместо этого используйте locator.hover() на основе локатора. Подробнее о локаторах.

Этот метод наводит указатель на элемент, соответствующий селектору, выполняя следующие шаги:

1. Найти элемент, соответствующий селектору. Если такого элемента нет, дождаться его появления в DOM.
2. Дождаться прохождения проверок возможности выполнения действия для найденного элемента, если не задан параметр force. Если во время проверок элемент будет отсоединён от DOM, действие будет повторено.
3. При необходимости прокрутить страницу, чтобы элемент оказался в видимой области.
4. Использовать page.mouse, чтобы навести указатель на центр элемента или на указанную позицию.

Если выполнение всех шагов не завершится за указанный тайм-аут, метод выбросит ошибку TimeoutError. Передача нулевого значения отключает тайм-аут.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • force boolean (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)

    Клавиши-модификаторы, которые нужно нажать. Гарантирует, что во время операции будут нажаты только эти модификаторы, после чего восстанавливает исходное состояние. Если параметр не указан, используются уже нажатые модификаторы. "ControlOrMeta" соответствует "Control" в Windows и Linux и "Meta" в macOS.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не имеет эффекта.

    Этот параметр не имеет эффекта.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла внутренней области элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в видимой области перед выполнением действия. По умолчанию — "auto": элемент прокручивается при необходимости, включая прокрутку вложенных прокручиваемых контейнеров. Если задано значение "none", Playwright не прокручивает страницу, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это полезно, чтобы проверить, доступен ли элемент пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, метод выполняет только проверки возможности выполнения действия, пропуская само действие. По умолчанию — false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его. Обратите внимание: клавиши modifiers будут нажаты независимо от trial, что позволяет тестировать элементы, видимые только при нажатии этих клавиш.

Возвращает

• Promise<void>

innerHTML​

Не рекомендуется

Вместо этого используйте locator.innerHTML() на основе локатора. Подробнее о локаторах.

Возвращает element.innerHTML.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<string>

innerText​

Не рекомендуется

Вместо этого используйте locator.innerText() на основе локатора. Подробнее о локаторах.

Возвращает element.innerText.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<string>

inputValue​

Не рекомендуется

Вместо этого используйте locator.inputValue() на основе локатора. Подробнее о локаторах.

Возвращает input.value для выбранного элемента <input>, <textarea> или <select>.

Для элементов, не являющихся полями ввода, выбрасывается ошибка. Однако если элемент находится внутри элемента <label>, связанного с элементом управления, возвращается значение этого элемента управления.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал прерван, операция будет отменена и будет выброшена ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов выбрасывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0, то есть без тайм-аута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<string>

isChecked​

Не рекомендуется

Вместо этого используйте locator.isChecked() на основе локатора. Подробнее о локаторах.

Возвращает, отмечен ли элемент. Выбрасывает ошибку, если элемент не является флажком или переключателем.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

Возвращает

• Promise<boolean>

isDisabled​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.isDisabled(). Подробнее см. в разделе локаторы.

Возвращает, отключён ли элемент; противоположное состояние описано в разделе доступен.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

Возвращает

• Promise<boolean>

isEditable​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.isEditable(). Подробнее см. в разделе локаторы.

Возвращает, является ли элемент редактируемым.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

Возвращает

• Promise<boolean>

isHidden​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.isHidden(). Подробнее см. в разделе локаторы.

Возвращает, скрыт ли элемент; противоположное состояние описано в разделе видимый. Элемент, соответствующий селектору, но отсутствующий на странице, считается скрытым.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Устарело

    Этот параметр игнорируется. frame.isHidden() не ждёт, пока элемент станет скрытым, и сразу возвращает результат.

Возвращает

• Promise<boolean>

isVisible​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.isVisible(). Подробнее см. в разделе локаторы.

Возвращает, является ли элемент видимым. Элемент, соответствующий селектору, но отсутствующий на странице, считается невидимым.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Устарело

    Этот параметр игнорируется. frame.isVisible() не ждёт, пока элемент станет видимым, и сразу возвращает результат.

Возвращает

• Promise<boolean>

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 соответствует Control в Windows и Linux и Meta в macOS.

Удерживание 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.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

Возвращает

• Promise<void>

selectOption​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.selectOption(). Подробнее см. в разделе локаторы.

Этот метод ожидает появления элемента, соответствующего селектору, прохождения проверок готовности к действию, а также появления всех указанных параметров в элементе <select>, после чего выбирает эти параметры.

Если целевой элемент не является элементом <select>, метод вызывает ошибку. Однако если элемент находится внутри элемента <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 (необязательно)

    Нужно ли пропустить проверки готовности к действию. По умолчанию — false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если задано значение true, вызов требует, чтобы селектор соответствовал одному элементу. Если заданный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() либо page.setDefaultTimeout().

Возвращает

• Promise<Array<string>>

setChecked​

Не рекомендуется

Вместо этого используйте метод на основе локатора locator.setChecked(). Подробнее см. в разделе локаторы.

Этот метод устанавливает или снимает флажок элемента, соответствующего селектору, выполняя следующие действия:

1. Находит элемент, соответствующий селектору. Если такого элемента нет, ожидает появления соответствующего элемента в DOM.
2. Проверяет, что найденный элемент — флажок или переключатель. Если это не так, метод вызывает ошибку.
3. Если элемент уже имеет нужное состояние, метод сразу возвращает результат.
4. Ожидает прохождения проверок готовности к действию для найденного элемента, если не задан параметр force. Если во время проверок элемент отсоединяется от DOM, действие выполняется повторно.
5. При необходимости прокручивает страницу до элемента.
6. Использует page.mouse, чтобы щёлкнуть по центру элемента.
7. Проверяет, что теперь элемент отмечен или не отмечен. Если это не так, метод вызывает ошибку.

Если все действия в совокупности не завершились за указанный период timeout, метод вызывает ошибку TimeoutError. Передача нулевого значения отключает тайм-аут.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• checked boolean

  Следует ли установить или снять флажок.

• options Object (необязательно)

  • force boolean (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не оказывает никакого эффекта.

    Этот параметр не оказывает никакого эффекта.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла области внутренних отступов элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в области просмотра перед выполнением действия. По умолчанию используется "auto": элемент прокручивается в область просмотра при необходимости, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано "none", Playwright не прокручивает страницу, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это полезно, чтобы проверить, доступен ли элемент пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал будет прерван, операция отменится и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — тайм-аут отсутствует. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, этот метод выполняет только проверки возможности выполнения действия, пропуская само действие. По умолчанию false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его.

Возвращает

• Promise<void>

setInputFiles​

Не рекомендуется

Вместо этого используйте locator.setInputFiles(), работающий с локаторами. Подробнее о локаторах.

Задает для поля ввода файла указанные пути к файлам или файлы. Если некоторые из filePaths являются относительными путями, они разрешаются относительно текущего рабочего каталога. Если передан пустой массив, выбранные файлы очищаются.

Этот метод ожидает, что селектор указывает на элемент input. Однако, если элемент находится внутри элемента <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 (необязательно)

    Устарело

    Этот параметр не оказывает никакого эффекта.

    Этот параметр не оказывает никакого эффекта.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал будет прерван, операция отменится и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — тайм-аут отсутствует. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<void>

tap​

Не рекомендуется

Вместо этого используйте locator.tap(), работающий с локаторами. Подробнее о локаторах.

Этот метод нажимает на элемент, соответствующий селектору, выполняя следующие действия:

1. Находит элемент, соответствующий селектору. Если такого элемента нет, ожидает его появления в DOM.
2. Ожидает успешного прохождения проверок возможности выполнения действия для найденного элемента, если не задан параметр force. Если во время проверок элемент отсоединяется от DOM, действие выполняется повторно.
3. При необходимости прокручивает страницу, чтобы элемент оказался в области просмотра.
4. С помощью page.touchscreen нажимает на центр элемента или на указанную позицию.

Если все действия не будут выполнены за указанный период тайм-аута, метод вызовет ошибку TimeoutError. Передача нулевого тайм-аута отключает его.

Примечание

Для frame.tap() требуется, чтобы для параметра hasTouch контекста браузера было задано значение true.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • force boolean (необязательно)

    Следует ли пропустить проверки возможности выполнения действия. По умолчанию false.

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)

    Модификаторы, которые нужно нажать. Гарантирует, что во время операции будут нажаты только эти модификаторы, после чего восстанавливает их исходное состояние. Если параметр не указан, используются модификаторы, нажатые в данный момент. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не оказывает никакого эффекта.

    Этот параметр не оказывает никакого эффекта.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла области внутренних отступов элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright страницу, чтобы элемент оказался в области просмотра перед выполнением действия. По умолчанию используется "auto": элемент прокручивается в область просмотра при необходимости, в том числе прокручиваются вложенные прокручиваемые контейнеры. Если задано "none", Playwright не прокручивает страницу, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это полезно, чтобы проверить, доступен ли элемент пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал будет прерван, операция отменится и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — тайм-аут отсутствует. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если параметр задан, этот метод выполняет только проверки возможности выполнения действия, пропуская само действие. По умолчанию false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его. Обратите внимание: клавиши modifiers нажимаются независимо от trial, чтобы можно было тестировать элементы, видимые только при нажатых клавишах.

Возвращает

• Promise<void>

textContent​

Не рекомендуется

Вместо этого используйте locator.textContent(), работающий с локаторами. Подробнее о локаторах.

Возвращает element.textContent.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал будет прерван, операция отменится и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — тайм-аут отсутствует. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<null | string>

type​

Устарело

В большинстве случаев вместо этого следует использовать locator.fill(). Нажимать клавиши по одной нужно только при наличии на странице специальной обработки клавиатуры — в этом случае используйте 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 (необязательно)

    Устарело

    Этот параметр не оказывает никакого эффекта.

    Этот параметр не оказывает никакого эффекта.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал будет прерван, операция отменится и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, селектор должен соответствовать одному элементу. Если указанный селектор соответствует более чем одному элементу, вызов вызовет исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию 0 — тайм-аут отсутствует. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации либо методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

• Promise<void>

uncheck​

Не рекомендуется

Вместо этого используйте locator.uncheck(), работающий с локаторами. Подробнее о локаторах.

Этот метод снимает флажок элемента, соответствующего селектору, выполняя следующие действия:

1. Находит элемент, соответствующий селектору. Если такого элемента нет, ожидает его появления в DOM.
2. Проверяет, что найденный элемент является флажком или переключателем. В противном случае метод вызывает ошибку. Если флажок уже снят, метод сразу возвращает результат.
3. Ожидает успешного прохождения проверок возможности выполнения действия для найденного элемента, если не задан параметр force. Если во время проверок элемент отсоединяется от DOM, действие выполняется повторно.
4. При необходимости прокручивает страницу, чтобы элемент оказался в области просмотра.
5. С помощью page.mouse нажимает на центр элемента.
6. Проверяет, что флажок снят. В противном случае метод вызывает ошибку.

Если все действия не будут выполнены за указанный период тайм-аута, метод вызовет ошибку TimeoutError. Передача нулевого тайм-аута отключает его.

Использование

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

Аргументы

• selector string

  Селектор для поиска элемента. Если селектору соответствуют несколько элементов, будет использован первый.

• options Object (необязательно)

  • force boolean (необязательно)

    Определяет, нужно ли пропустить проверки возможности выполнения действия. По умолчанию — false.

  • noWaitAfter boolean (необязательно)

    Устарело

    Этот параметр не влияет на результат.

    Этот параметр не влияет на результат.

  • position Object (необязательно)

    • x number

    • y number

    Точка относительно верхнего левого угла внутренней области элемента. Если не указана, используется видимая точка элемента.

  • scroll "auto" | "none" (необязательно)

    Определяет, прокручивает ли Playwright страницу так, чтобы элемент оказался в области видимости, перед выполнением действия. По умолчанию — "auto": элемент прокручивается в область видимости при необходимости, в том числе во вложенных прокручиваемых контейнерах. Если задано значение "none", Playwright не прокручивает страницу, и действие завершается ошибкой, если элемент уже не находится в области просмотра. Это полезно, чтобы проверить, доступен ли элемент пользователю без дополнительной прокрутки.

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет отменена и возникнет ошибка. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

  • trial boolean (необязательно)

    Если задано, этот метод выполняет только проверки возможности выполнения действия и пропускает само действие. По умолчанию — false. Полезно, чтобы дождаться готовности элемента к действию, не выполняя его.

Возвращает

• Promise<void>

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;

примечание

Изменение URL с помощью History API считается навигацией.

Аргументы

• options Object (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить ожидание с помощью AbortSignal. Если сигнал отменён, ожидание будет прервано, и операция вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • timeout number (необязательно)

    Максимальное время выполнения операции в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра navigationTimeout в конфигурации или методов browserContext.setDefaultNavigationTimeout(), browserContext.setDefaultTimeout(), page.setDefaultNavigationTimeout() или page.setDefaultTimeout().

  • url string | RegExp | URLPattern | function(URL):boolean (необязательно)

    Шаблон glob, регулярное выражение, шаблон URL или предикат, принимающий URL, для сопоставления во время ожидания навигации. Обратите внимание: если параметр — строка без подстановочных символов, метод будет ожидать перехода на URL, в точности совпадающий с этой строкой.

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (необязательно)

    Когда считать операцию успешно завершённой; по умолчанию — load. Возможны следующие события:

    • 'domcontentloaded' — считать операцию завершённой при срабатывании события DOMContentLoaded.
    • 'load' — считать операцию завершённой при срабатывании события load.
    • 'networkidle' — НЕ РЕКОМЕНДУЕТСЯ считать операцию завершённой, если сетевые подключения отсутствуют не менее 500 мс. Не используйте этот метод для тестирования; вместо этого проверяйте готовность с помощью веб-проверок.
    • 'commit' — считать операцию завершённой после получения ответа сети и начала загрузки документа.

Возвращает

• Promise<null | Response>

waitForSelector​

Не рекомендуется

Используйте веб-проверки видимости или метод locator.waitFor() для работы с локатором. Подробнее о локаторах.

Возвращает результат, когда элемент, указанный селектором, соответствует параметру state. При ожидании null или hidden возвращает detached.

примечание

Playwright автоматически ожидает готовности элемента перед выполнением действия. Использование объектов Locator и веб-проверок с приоритетом веба позволяет писать код без ожидания селектора.

Ожидает, пока селектор не будет соответствовать параметру 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 (необязательно)

  • signal AbortSignal (необязательно)

    Позволяет отменить операцию с помощью AbortSignal. Если сигнал отменён, операция будет прервана и вызовет ошибку. Обратите внимание: передача сигнала не отключает тайм-аут по умолчанию. Его можно изменить с помощью browserContext.setDefaultTimeout() или page.setDefaultTimeout(); передайте timeout: 0, чтобы полностью отключить тайм-аут.

  • state "attached" | "detached" | "visible" | "hidden" (необязательно)

    По умолчанию — 'visible'. Возможны следующие значения:

    • 'attached' — ожидать появления элемента в DOM.
    • 'detached' — ожидать удаления элемента из DOM.
    • 'visible' — ожидать, пока у элемента не появится непустая ограничивающая рамка и не будет visibility:hidden. Обратите внимание: у элемента без содержимого или с display:none ограничивающая рамка пуста, поэтому он не считается видимым.
    • 'hidden' — ожидать, пока элемент не будет удалён из DOM, либо пока его ограничивающая рамка не станет пустой, либо не появится visibility:hidden. Это противоположно параметру 'visible'.

  • strict boolean (необязательно)

    Если значение равно true, вызов требует, чтобы селектор соответствовал одному элементу. Если указанный селектор соответствует нескольким элементам, вызов вызывает исключение.

  • timeout number (необязательно)

    Максимальное время в миллисекундах. По умолчанию — 0 (без тайм-аута). Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или методов browserContext.setDefaultTimeout() и page.setDefaultTimeout().

Возвращает

• Promise<null | ElementHandle>

waitForTimeout​

Не рекомендуется

Не используйте ожидание тайм-аута в рабочем коде. Тесты, ожидающие заданное время, по своей сути нестабильны. Используйте действия Locator и веб-проверки, которые выполняют ожидание автоматически.

Ожидает указанное значение timeout в миллисекундах.

Обратите внимание: frame.waitForTimeout() следует использовать только для отладки. Тесты, использующие таймер в рабочем коде, будут нестабильны. Вместо этого используйте такие сигналы, как сетевые события, появление селекторов и другие.

Использование

await frame.waitForTimeout(timeout);

Аргументы

• timeout number

  Время ожидания

Возвращает

• Promise<void>