BrowserContext

BrowserContext предоставляют возможность работать с несколькими независимыми сеансами браузера.

Если страница открывает другую страницу, например с помощью вызова window.open, всплывающее окно будет принадлежать контексту браузера родительской страницы.

Playwright позволяет создавать изолированные непостоянные контексты браузера с помощью метода browser.newContext(). Непостоянные контексты браузера не записывают данные о просмотре на диск.

// Create a new incognito browser context
const context = await browser.newContext();
// Create a new page inside context.
const page = await context.newPage();
await page.goto('https://example.com');
// Dispose context once it's no longer needed.
await context.close();

Методы​

addCookies​

Добавляет файлы cookie в этот контекст браузера. Эти файлы cookie будут установлены на всех страницах в данном контексте. Файлы cookie можно получить с помощью browserContext.cookies().

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

await browserContext.addCookies([cookieObject1, cookieObject2]);

Аргументы

• cookies Array<Object>

  • name string

  • value string

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

    Требуется либо url, либо оба параметра: domain и path. Необязательно.

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

    Чтобы файл cookie распространялся также на все поддомены, добавьте точку перед доменом, например: ".example.com". Требуется либо url, либо оба параметра: domain и path. Необязательно.

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

    Требуется либо url, либо оба параметра: domain и path. Необязательно.

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

    Время Unix в секундах. Необязательно.

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

    Необязательно.

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

    Необязательно.

  • sameSite "Strict" | "Lax" | "None" (необязательно)

    Необязательно.

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

    Ключ секционирования для сторонних файлов cookie с секционированием (также называемых CHIPS). Необязательно.

Возвращает

• Promise<void>

addInitScript​

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

• При создании или переходе на новую страницу в контексте браузера.
• При присоединении или переходе на новый дочерний фрейм на любой странице в контексте браузера. В этом случае скрипт выполняется в контексте только что присоединённого фрейма.

Скрипт выполняется после создания документа, но до запуска любых содержащихся в нём скриптов. Это полезно для изменения среды JavaScript, например для установки начального значения Math.random.

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

Пример переопределения Math.random до загрузки страницы:

// preload.js
Math.random = () => 42;

// In your playwright script, assuming the preload.js file is in same directory.
await browserContext.addInitScript({
  path: 'preload.js'
});

примечание

Порядок выполнения нескольких скриптов, добавленных с помощью browserContext.addInitScript() и page.addInitScript(), не определён.

Аргументы

• script function | string | Object

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

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

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

    Исходный текст скрипта. Необязательно.

  Скрипт, который будет выполняться на всех страницах в контексте браузера.

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

  Необязательный аргумент, передаваемый в script (поддерживается только при передаче функции).

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

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

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

Возвращает

• Promise<Disposable>

browser​

Возвращает экземпляр браузера, которому принадлежит контекст. Возвращает null, если контекст создан вне обычного браузера, например в Android или Electron.

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

browserContext.browser();

Возвращает

• null | Browser

clearCookies​

Удаляет файлы cookie из контекста. Принимает необязательный фильтр.

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

await context.clearCookies();
await context.clearCookies({ name: 'session-id' });
await context.clearCookies({ domain: 'my-origin.com' });
await context.clearCookies({ domain: /.*my-origin\.com/ });
await context.clearCookies({ path: '/api/v1' });
await context.clearCookies({ name: 'session-id', domain: 'my-origin.com' });

Аргументы

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

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

    Удаляет только файлы cookie с указанным доменом.

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

    Удаляет только файлы cookie с указанным именем.

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

    Удаляет только файлы cookie с указанным путём.

Возвращает

• Promise<void>

clearPermissions​

Сбрасывает все переопределения разрешений для контекста браузера.

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

const context = await browser.newContext();
await context.grantPermissions(['clipboard-read']);
// do stuff ..
context.clearPermissions();

Возвращает

• Promise<void>

close​

Закрывает контекст браузера. Все страницы, принадлежащие этому контексту, будут закрыты.

примечание

Контекст браузера по умолчанию закрыть нельзя.

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

await browserContext.close();
await browserContext.close(options);

Аргументы

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

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

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

Возвращает

• Promise<void>

cookies​

Если URL-адреса не указаны, этот метод возвращает все файлы cookie. Если URL-адреса указаны, возвращаются только файлы cookie, влияющие на эти URL-адреса.

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

await browserContext.cookies();
await browserContext.cookies(urls);

Аргументы

• urls string | Array<string> (необязательно)

  Необязательный список URL-адресов.

Возвращает

• Promise<Array<Object>>

  • name string

  • value string

  • domain string

  • path string

  • expires number

    Время Unix в секундах.

  • httpOnly boolean

  • secure boolean

  • sameSite "Strict" | "Lax" | "None"

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

exposeBinding​

Метод добавляет функцию с именем name в объект window каждого фрейма каждой страницы в контексте. При вызове функция выполняет callback и возвращает Promise, который разрешается значением, возвращённым callback. Если callback возвращает Promise, будет выполнено ожидание его разрешения.

Первый аргумент функции callback содержит сведения о вызывающей стороне: { browserContext: BrowserContext, page: Page, frame: Frame }.

См. page.exposeBinding() для версии, работающей только со страницей.

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

Пример предоставления URL-адреса страницы всем фреймам на всех страницах контекста:

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

(async () => {
  const browser = await webkit.launch({ headless: false });
  const context = await browser.newContext();
  await context.exposeBinding('pageURL', ({ page }) => page.url());
  const page = await context.newPage();
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.getByRole('button').click();
})();

Аргументы

• name string

  Имя функции в объекте window.

• callback function

  Функция обратного вызова, которая будет вызвана в контексте Playwright.

Возвращает

• Promise<Disposable>

exposeFunction​

Метод добавляет функцию с именем name в объект window каждого фрейма каждой страницы в контексте. При вызове функция выполняет callback и возвращает Promise, который разрешается значением, возвращённым callback.

Если callback возвращает Promise, будет выполнено ожидание его разрешения.

См. page.exposeFunction() для версии, работающей только со страницей.

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

Пример добавления функции sha256 на все страницы контекста:

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

(async () => {
  const browser = await webkit.launch({ headless: false });
  const context = await browser.newContext();
  await context.exposeFunction('sha256', text =>
    crypto.createHash('sha256').update(text).digest('hex'),
  );
  const page = await context.newPage();
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.getByRole('button').click();
})();

Аргументы

• name string

  Имя функции в объекте window.

• callback function

  Функция обратного вызова, которая будет вызвана в контексте Playwright.

Возвращает

• Promise<Disposable>

grantPermissions​

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

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

await browserContext.grantPermissions(permissions);
await browserContext.grantPermissions(permissions, options);

Аргументы

• permissions Array<string>

  Список разрешений для предоставления.

  опасность

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

  Вот некоторые разрешения, которые могут поддерживаться отдельными браузерами:

  • 'accelerometer'
  • 'ambient-light-sensor'
  • 'background-sync'
  • 'camera'
  • 'clipboard-read'
  • 'clipboard-write'
  • 'geolocation'
  • 'gyroscope'
  • 'local-fonts'
  • 'local-network-access'
  • 'magnetometer'
  • 'microphone'
  • 'midi-sysex' (MIDI, только для системы)
  • 'midi'
  • 'notifications'
  • 'payment-handler'
  • 'storage-access'
  • 'screen-wake-lock'

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

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

    Источник, для которого нужно предоставить разрешения, например "https://example.com".

Возвращает

• Promise<void>

isClosed​

Указывает, что контекст браузера закрывается или уже закрыт.

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

browserContext.isClosed();

Возвращает

• boolean

newCDPSession​

примечание

Сеансы CDP поддерживаются только в браузерах на основе Chromium.

Возвращает только что созданный сеанс.

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

await browserContext.newCDPSession(page);

Аргументы

• page Page | Frame

  Цель, для которой создаётся сеанс. Для обратной совместимости этот параметр называется page, но его тип может быть Page или Frame.

Возвращает

• Promise<CDPSession>

newPage​

Создаёт новую страницу в контексте браузера.

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

await browserContext.newPage();

Возвращает

• Promise<Page>

pages​

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

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

browserContext.pages();

Возвращает

• Array<Page>

removeAllListeners​

Удаляет все обработчики указанного типа (или все зарегистрированные обработчики, если тип не указан). Позволяет дождаться завершения асинхронных обработчиков или игнорировать последующие ошибки от этих обработчиков.

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

await browserContext.removeAllListeners();
await browserContext.removeAllListeners(type, options);

Аргументы

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

  • behavior "wait" | "ignoreErrors" | "default" (необязательно)

    Определяет, нужно ли ждать уже выполняющиеся обработчики и что делать, если они выбрасывают ошибки:

    • 'default' — не ждать завершения текущих вызовов обработчиков (если они есть); если обработчик выбросит ошибку, она может остаться необработанной
    • 'wait' — дождаться завершения текущих вызовов обработчиков (если они есть)
    • 'ignoreErrors' — не ждать завершения текущих вызовов обработчиков (если они есть); все ошибки, выброшенные обработчиками после удаления, будут незаметно перехвачены

Возвращает

• Promise<void>

route​

Маршрутизация позволяет изменять сетевые запросы, отправляемые любой страницей в контексте браузера. После включения маршрутизации каждый запрос, соответствующий шаблону URL, будет приостановлен, пока его не продолжат, не выполнят или не прервут.

примечание

browserContext.route() не перехватывает запросы, перехваченные Service Worker. См. эту проблему. При перехвате запросов рекомендуется отключать Service Worker, задав для serviceWorkers значение 'block'.

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

Пример простого обработчика, прерывающего все запросы изображений:

const context = await browser.newContext();
await context.route('**/*.{png,jpg,jpeg}', route => route.abort());
const page = await context.newPage();
await page.goto('https://example.com');
await browser.close();

или тот же фрагмент с использованием регулярного выражения:

const context = await browser.newContext();
await context.route(/(\.png$)|(\.jpg$)/, route => route.abort());
const page = await context.newPage();
await page.goto('https://example.com');
await browser.close();

Можно изучить запрос, чтобы определить действие для маршрута. Например, перехватывать все запросы, содержащие данные POST, а остальные оставлять без изменений:

await context.route('/api/**', async route => {
  if (route.request().postData().includes('my-string'))
    await route.fulfill({ body: 'mocked-data' });
  else
    await route.continue();
});

Маршруты страниц (настроенные с помощью page.route()) имеют приоритет над маршрутами контекста браузера, если запрос соответствует обоим обработчикам.

Чтобы удалить маршрут вместе с его обработчиком, используйте browserContext.unroute().

примечание

Включение маршрутизации отключает кэш HTTP.

Аргументы

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

  Шаблон glob, регулярное выражение, шаблон URL или предикат, получающий URL для сопоставления при маршрутизации. Если в параметрах контекста задан baseURL, а указанный URL — строка, не начинающаяся с *, он разрешается с помощью конструктора new URL().

• handler function(Route, Request):Promise<Object> | Object

  Функция-обработчик для маршрутизации запроса.

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

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

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

Возвращает

• Promise<Disposable>

routeFromHAR​

Если этот параметр указан, сетевые запросы, выполняемые в контексте, будут обслуживаться из файла HAR. Подробнее см. в разделе Воспроизведение из HAR.

Playwright не будет обслуживать из файла HAR запросы, перехваченные Service Worker. См. эту задачу. При перехвате запросов рекомендуется отключать Service Worker, установив для serviceWorkers значение 'block'.

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

await browserContext.routeFromHAR(har);
await browserContext.routeFromHAR(har, options);

Аргументы

• har string

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

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

  • notFound "abort" | "fallback" (необязательно)

    • Если задано значение 'abort', любой запрос, отсутствующий в файле HAR, будет прерван.
    • Если задано значение 'fallback', запрос будет передан следующему обработчику маршрута в цепочке обработчиков.

    По умолчанию — abort.

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

    Если задано это значение, указанный HAR обновляется фактическими сетевыми данными вместо обслуживания запросов из файла. Файл записывается на диск при вызове browserContext.close().

  • updateContent "embed" | "attach" (необязательно)

    Необязательный параметр для управления хранением содержимого ресурсов. Если задано attach, ресурсы сохраняются как отдельные файлы или записи в ZIP-архиве. Если задано embed, содержимое сохраняется непосредственно в файле HAR.

  • updateMode "full" | "minimal" (необязательно)

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

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

    Шаблон glob, регулярное выражение или предикат для сопоставления URL запроса. Из файла HAR будут обслуживаться только запросы с URL, соответствующим шаблону. Если параметр не задан, из файла HAR обслуживаются все запросы.

Возвращает

• Promise<void>

routeWebSocket​

Этот метод позволяет изменять WebSocket-соединения, создаваемые любой страницей в контексте браузера.

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

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

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

await context.routeWebSocket('/ws', async ws => {
  ws.routeSend(message => {
    if (message === 'to-be-blocked')
      return;
    ws.send(message);
  });
  await ws.connect();
});

Аргументы

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

  Будут маршрутизироваться только WebSocket-соединения, URL которых соответствует этому шаблону. Строковый шаблон может быть относительным к параметру контекста baseURL.

• handler function(WebSocketRoute):Promise<Object> | Object

  Функция-обработчик для маршрутизации WebSocket.

Возвращает

• Promise<void>

serviceWorkers​

примечание

Service Worker поддерживаются только в браузерах на базе Chromium.

Все существующие Service Worker в контексте.

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

browserContext.serviceWorkers();

Возвращает

• Array<Worker>

setDefaultNavigationTimeout​

Этот параметр изменяет максимальное время ожидания навигации по умолчанию для следующих методов и связанных с ними сокращенных вариантов:

• page.goBack()
• page.goForward()
• page.goto()
• page.reload()
• page.setContent()
• page.waitForNavigation()

примечание

page.setDefaultNavigationTimeout() и page.setDefaultTimeout() имеют приоритет над browserContext.setDefaultNavigationTimeout().

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

browserContext.setDefaultNavigationTimeout(timeout);

Аргументы

• timeout number

  Максимальное время навигации в миллисекундах

setDefaultTimeout​

Этот параметр изменяет максимальное время ожидания по умолчанию для всех методов, принимающих параметр timeout.

примечание

page.setDefaultNavigationTimeout(), page.setDefaultTimeout() и browserContext.setDefaultNavigationTimeout() имеют приоритет над browserContext.setDefaultTimeout().

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

browserContext.setDefaultTimeout(timeout);

Аргументы

• timeout number

  Максимальное время в миллисекундах. Передайте 0, чтобы отключить тайм-аут.

setExtraHTTPHeaders​

Дополнительные заголовки HTTP будут отправляться с каждым запросом, инициированным любой страницей в контексте. Эти заголовки объединяются с дополнительными заголовками HTTP для конкретной страницы, заданными с помощью page.setExtraHTTPHeaders(). Если страница переопределяет определенный заголовок, вместо значения заголовка контекста браузера будет использоваться значение заголовка страницы.

примечание

browserContext.setExtraHTTPHeaders() не гарантирует порядок заголовков в исходящих запросах.

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

await browserContext.setExtraHTTPHeaders(headers);

Аргументы

• headers Object<string, string>

  Объект с дополнительными заголовками HTTP, которые будут отправляться с каждым запросом. Все значения заголовков должны быть строками.

Возвращает

• Promise<void>

setGeolocation​

Задает геолокацию контекста. Передача null или undefined имитирует недоступность местоположения.

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

await browserContext.setGeolocation({ latitude: 59.95, longitude: 30.31667 });

примечание

Рассмотрите возможность использования browserContext.grantPermissions(), чтобы предоставить страницам контекста браузера разрешение на чтение геолокации.

Аргументы

• geolocation null | Object

  • latitude number

    Широта от -90 до 90.

  • longitude number

    Долгота от -180 до 180.

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

    Неотрицательное значение точности. По умолчанию — 0.

Возвращает

• Promise<void>

setHTTPCredentials​

Задает учетные данные для HTTP-аутентификации в этом контексте браузера.

примечание

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

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

await browserContext.setHTTPCredentials(httpCredentials);

Аргументы

• httpCredentials null | Object | Array<Object>

  • username string

  • password string

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

    Ограничивает отправку учетных данных HTTP для указанного источника (scheme://host:port).

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

Возвращает

• Promise<void>

setOffline​

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

await browserContext.setOffline(offline);

Аргументы

• offline boolean

  Определяет, следует ли имитировать отсутствие сети для контекста браузера.

Возвращает

• Promise<void>

setStorageState​

Удаляет существующие cookie, данные local storage, записи IndexedDB, записи приватной файловой системы источника и виртуальные учетные данные WebAuthn, а затем задает новое состояние хранилища. Если состояние хранилища содержит учетные данные, устанавливается виртуальный аутентификатор WebAuthn (эквивалентно вызову credentials.install()), что делает невозможной работу всех реальных аутентификаторов в этом контексте.

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

// Load storage state from a file and apply it to the context.
await context.setStorageState('state.json');

Аргументы

• storageState string | Object

  • cookies Array<Object>

    • name string

    • value string

    • domain string

      Домен и путь обязательны. Чтобы cookie применялся также ко всем поддоменам, добавьте перед доменом точку, например: ".example.com"

    • path string

      Домен и путь обязательны

    • expires number

      Время Unix в секундах.

    • httpOnly boolean

    • secure boolean

    • sameSite "Strict" | "Lax" | "None"

      Флаг sameSite

    Cookie, задаваемые для контекста

  • origins Array<Object>

    • origin string

    • localStorage Array<Object>

      • name string

      • value string

      Данные localStorage, задаваемые для контекста

  Подробнее см. в разделе состояние хранилища и аутентификация.

  Заполняет контекст указанным состоянием хранилища. Этот параметр можно использовать для инициализации контекста данными о входе в систему, полученными с помощью browserContext.storageState().

Возвращает

• Promise<void>

storageState​

Возвращает состояние хранилища для этого контекста браузера: текущие cookie, снимок local storage, снимок IndexedDB, снимок приватной файловой системы источника и виртуальные учетные данные WebAuthn.

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

await browserContext.storageState();
await browserContext.storageState(options);

Аргументы

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

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

    Установите значение true, чтобы включить виртуальные учетные данные WebAuthn контекста browserContext.credentials (ключи доступа) в снимок состояния хранилища. Сохраненные учетные данные содержат закрытые ключи, поэтому их можно повторно загрузить в последующий контекст с помощью параметра storageState или метода browserContext.setStorageState(). Обратите внимание: восстановление состояния хранилища с учетными данными автоматически устанавливает виртуальный аутентификатор WebAuthn (см. credentials.install()) и делает невозможной работу всех реальных аутентификаторов в этом контексте.

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

    Установите значение true, чтобы включить IndexedDB в снимок состояния хранилища. Если ваше приложение использует IndexedDB для хранения токенов аутентификации, например Firebase Authentication, включите этот параметр.

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

    Установите значение true, чтобы включить приватную файловую систему источника в снимок состояния хранилища.

    примечание

    OPFS в настоящее время не поддерживается во временных контекстах WebKit.

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

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

Возвращает

• Promise<Object>

  • cookies Array<Object>

    • name string

    • value string

    • domain string

    • path string

    • expires number

      Время Unix в секундах.

    • httpOnly boolean

    • secure boolean

    • sameSite "Strict" | "Lax" | "None"

  • origins Array<Object>

    • origin string

    • localStorage Array<Object>

      • name string

      • value string

unroute​

Удаляет маршрут, созданный с помощью browserContext.route(). Если обработчик не указан, удаляет все маршруты для URL.

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

await browserContext.unroute(url);
await browserContext.unroute(url, handler);

Аргументы

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

  Шаблон glob, регулярное выражение, шаблон URL или предикат, получающий URL, используемый для регистрации маршрута с помощью browserContext.route().

• handler function(Route, Request):Promise<Object> | Object (необязательно)

  Необязательная функция-обработчик, используемая для регистрации маршрута с помощью browserContext.route().

Возвращает

• Promise<void>

unrouteAll​

Удаляет все маршруты, созданные с помощью browserContext.route() и browserContext.routeFromHAR().

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

await browserContext.unrouteAll();
await browserContext.unrouteAll(options);

Аргументы

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

  • behavior "wait" | "ignoreErrors" | "default" (необязательно)

    Указывает, следует ли дожидаться уже выполняющихся обработчиков и что делать, если они вызывают ошибки:

    • 'default' — не ждать завершения текущих вызовов обработчика (если таковые имеются); если отменённый обработчик вызовет ошибку, она может остаться необработанной
    • 'wait' — ждать завершения текущих вызовов обработчика (если таковые имеются)
    • 'ignoreErrors' — не ждать завершения текущих вызовов обработчика (если таковые имеются); все ошибки, вызванные обработчиками после отмены маршрутизации, будут перехвачены без уведомления

Возвращает

• Promise<void>

waitForEvent​

Ожидает возникновения события и передаёт его значение функции-предикату. Возвращает результат, когда предикат возвращает истинное значение. Вызывает ошибку, если контекст закрывается до возникновения события. Возвращает значение данных события.

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

const pagePromise = context.waitForEvent('page');
await page.getByRole('button').click();
const page = await pagePromise;

Аргументы

• event string

  Имя события, такое же, как передаваемое в browserContext.on(event).

• optionsOrPredicate function | Object (необязательно)

  • predicate function

    Получает данные события и возвращает истинное значение, когда ожидание должно завершиться.

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

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

  Либо предикат, получающий событие, либо объект параметров. Необязательно.

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

  • predicate function (необязательно)

    Получает данные события и возвращает истинное значение, когда ожидание должно завершиться.

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

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

Возвращает

• Promise<Object>

Свойства​

clock​

Playwright позволяет имитировать часы и ход времени.

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

browserContext.clock

Тип

• Clock

credentials​

Виртуальный аутентификатор WebAuthn для этого контекста. Позволяет тестам добавлять учётные данные и перехватывать процедуры navigator.credentials.create() / navigator.credentials.get().

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

browserContext.credentials

Тип

• Credentials

debugger​

Отладчик позволяет приостанавливать и возобновлять выполнение.

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

browserContext.debugger

Тип

• Debugger

request​

Вспомогательный инструмент для тестирования API, связанный с этим контекстом. Запросы, выполненные с помощью этого API, используют файлы cookie контекста.

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

browserContext.request

Тип

• APIRequestContext

tracing​

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

browserContext.tracing

Тип

• Tracing

События​

on('close')​

Возникает при закрытии контекста браузера. Это может произойти по одной из следующих причин:

• Контекст браузера закрыт.
• Приложение браузера закрыто или аварийно завершило работу.
• Был вызван метод browser.close().

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

browserContext.on('close', data => {});

Данные события

• BrowserContext

on('console')​

Возникает, когда JavaScript на странице вызывает один из методов API console, например console.log или console.dir.

Аргументы, переданные в console.log, и страница доступны в аргументе обработчика события ConsoleMessage.

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

context.on('console', async msg => {
  const values = [];
  for (const arg of msg.args())
    values.push(await arg.jsonValue());
  console.log(...values);
});
await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));

Данные события

• ConsoleMessage

on('dialog')​

Возникает при появлении диалогового окна JavaScript, например alert, prompt, confirm или beforeunload. Обработчик должен вызвать для диалогового окна либо dialog.accept(), либо dialog.dismiss() — в противном случае страница зависнет в ожидании диалога, а такие действия, как щелчок, не завершатся.

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

context.on('dialog', dialog => {
  dialog.accept();
});

примечание

Если обработчики page.on('dialog') или browserContext.on('dialog') не заданы, все диалоговые окна закрываются автоматически.

Данные события

• Dialog

on('dialogclosed')​

Возникает, когда диалоговое окно JavaScript на любой странице этого контекста закрывается вызовом dialog.accept(), вызовом dialog.dismiss() или вручную пользователем в браузере с графическим интерфейсом.

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

browserContext.on('dialogclosed', data => {});

Данные события

• Dialog

on('download')​

Возникает при начале загрузки вложения на любой странице этого контекста. Пользователь может выполнять основные операции с загруженным файлом через переданный экземпляр Download. См. также page.on('download'), чтобы получать события для конкретной страницы.

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

browserContext.on('download', data => {});

Данные события

• Download

on('frameattached')​

Возникает, когда фрейм добавляется на любой странице этого контекста. См. также page.on('frameattached'), чтобы получать события для конкретной страницы.

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

browserContext.on('frameattached', data => {});

Данные события

• Frame

on('framedetached')​

Возникает, когда фрейм удаляется с любой страницы этого контекста. См. также page.on('framedetached'), чтобы получать события для конкретной страницы.

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

browserContext.on('framedetached', data => {});

Данные события

• Frame

on('framenavigated')​

Возникает, когда фрейм переходит по новому URL на любой странице этого контекста. См. также page.on('framenavigated'), чтобы получать события навигации на конкретной странице.

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

browserContext.on('framenavigated', data => {});

Данные события

• Frame

on('page')​

Событие возникает при создании новой страницы в BrowserContext. Страница может всё ещё загружаться. Событие также возникает для всплывающих страниц. См. также page.on('popup'), чтобы получать события о всплывающих окнах, связанных с конкретной страницей.

Раньше всего страница становится доступной после перехода на исходный URL. Например, при открытии всплывающего окна с помощью window.open('http://example.com') это событие возникнет, когда сетевой запрос к "http://example.com" будет выполнен и начнётся загрузка ответа во всплывающем окне. Чтобы маршрутизировать или прослушивать этот сетевой запрос, используйте соответственно browserContext.route() и browserContext.on('request'), а не аналогичные методы объекта Page.

const newPagePromise = context.waitForEvent('page');
await page.getByText('open new page').click();
const newPage = await newPagePromise;
console.log(await newPage.evaluate('location.href'));

примечание

Используйте page.waitForLoadState(), чтобы дождаться перехода страницы в нужное состояние (в большинстве случаев это не требуется).

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

browserContext.on('page', data => {});

Данные события

• Page

on('pageclose')​

Возникает при закрытии страницы в этом контексте. См. также page.on('close'), чтобы получать события для конкретной страницы.

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

browserContext.on('pageclose', data => {});

Данные события

• Page

on('pageload')​

Возникает при отправке события JavaScript load на любой странице этого контекста. См. также page.on('load'), чтобы получать события для конкретной страницы.

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

browserContext.on('pageload', data => {});

Данные события

• Page

on('request')​

Возникает при отправке запроса с любой страницы, созданной в этом контексте. Объект request доступен только для чтения. Чтобы прослушивать запросы только с определённой страницы, используйте page.on('request').

Чтобы перехватывать запросы и изменять их, см. browserContext.route() или page.route().

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

browserContext.on('request', data => {});

Данные события

• Request

on('requestfailed')​

Возникает при сбое запроса, например из-за истечения времени ожидания. Чтобы прослушивать сбои запросов только с определённой страницы, используйте page.on('requestfailed').

примечание

Ответы HTTP с ошибками, например 404 или 503, с точки зрения HTTP всё равно считаются успешными ответами. Поэтому запрос завершается событием browserContext.on('requestfinished'), а не событием browserContext.on('requestfailed').

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

browserContext.on('requestfailed', data => {});

Данные события

• Request

on('requestfinished')​

Возникает, когда запрос успешно завершается после загрузки тела ответа. Для успешного ответа последовательность событий такова: request, response и requestfinished. Чтобы прослушивать успешные запросы только с определённой страницы, используйте page.on('requestfinished').

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

browserContext.on('requestfinished', data => {});

Данные события

• Request

on('response')​

Возникает, когда получены статус и заголовки ответа на запрос. Для успешного ответа последовательность событий такова: request, response и requestfinished. Чтобы прослушивать события ответа только для определённой страницы, используйте page.on('response').

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

browserContext.on('response', data => {});

Данные события

• Response

on('serviceworker')​

примечание

Сервис-воркеры поддерживаются только в браузерах на основе Chromium.

Возникает при создании нового сервис-воркера в контексте.

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

browserContext.on('serviceworker', data => {});

Данные события

• Worker

on('weberror')​

Возникает, когда исключение не обработано на любой из страниц этого контекста. Чтобы прослушивать ошибки только на определённой странице, используйте page.on('pageerror').

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

browserContext.on('weberror', data => {});

Данные события

• WebError

Устаревшее​

on('backgroundpage')​

Устарело

Фоновые страницы удалены из Chromium вместе с расширениями Manifest V2.

Это событие не возникает.

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

browserContext.on('backgroundpage', data => {});

Данные события

• Page

backgroundPages​

Устарело

Фоновые страницы удалены из Chromium вместе с расширениями Manifest V2.

Возвращает пустой список.

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

browserContext.backgroundPages();

Возвращает

• Array<Page>