Документация Puppeteer

Обзор

Puppeteer — это библиотека Node, которая предоставляет высокоуровневый API для управления Chromium или Chrome через протокол DevTools.

API Puppeteer иерархичен и отражает структуру браузера.

ПРИМЕЧАНИЕ На следующей диаграмме не отображаемые элементы в настоящее время не представлены в Puppeteer.

<img alt="обзор puppeteer" src="data:image/png;base64,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

Puppeteer взаимодействует с браузером с помощью DevTools Protocol.
Browser экземпляр может содержать несколько контекстов браузера.
BrowserContext экземпляр определяет сеанс просмотра и может содержать несколько страниц.
Page имеет как минимум один фрейм: основной фрейм. Могут быть и другие фреймы, созданные тегами iframe или frame.
Frame имеет как минимум один контекст выполнения — дефолтный контекст выполнения — где выполняется JavaScript фрейма. У фрейма могут быть дополнительные контексты выполнения, связанные с расширениями.
Worker имеет единственный контекст выполнения и облегчает взаимодействие с WebWorkers.

(Источник диаграммы: ссылка)

puppeteer против puppeteer-core

С каждой версией, начиная с v1.7.0, мы публикуем два пакета:

puppeteer — это продукт для автоматизации браузера. При установке он скачивает версию Chromium, а затем управляет ею с помощью puppeteer-core. Как продукт для конечных пользователей, puppeteer поддерживает множество удобных PUPPETEER_* переменных среды для настройки своего поведения.

puppeteer-core — это библиотека, которая помогает управлять любым приложением, поддерживающим протокол DevTools. puppeteer-core не загружает Chromium при установке. Будучи библиотекой, puppeteer-core полностью управляется через свой программируемый интерфейс и игнорирует все PUPPETEER_* переменные среды.

В итоге, единственные различия между puppeteer-core и puppeteer заключаются в:

puppeteer-core не загружает Chromium автоматически при установке.
puppeteer-core игнорирует все PUPPETEER_* переменные среды.

В большинстве случаев вы сможете использовать пакет puppeteer.

Однако, вам следует использовать puppeteer-core если:

вы создаёте другой продукт для конечных пользователей или библиотеку на основе протокола DevTools. Например, можно создать генератор PDF, используя puppeteer-core и написать пользовательский install.js скрипт, который загружает headless_shell вместо Chromium, чтобы сэкономить место на диске.
вы собираете Puppeteer для использования в расширении Chrome/браузере с протоколом DevTools, где загрузка дополнительного бинарника Chromium не требуется.
вы создаёте набор инструментов, где puppeteer-core является одной из составляющих, и вы хотите отложить выполнение install.js скрипта до момента, когда Chromium будет готов к использованию.

При использовании puppeteer-core, не забудьте изменить строку include:

const puppeteer = require('puppeteer-core');

После этого вам нужно вызвать puppeteer.connect([options]) или puppeteer.launch([options]) с явным параметром executablePath.

Переменные среды

Puppeteer использует определённые переменные среды для облегчения своей работы. Если Puppeteer не находит их в среде во время установки, он использует аналогичные переменные в нижнем регистре из npm config.

HTTP_PROXY, HTTPS_PROXY, NO_PROXY — определяют настройки HTTP-прокси, которые используются для загрузки и запуска Chromium.
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD — не загружать входящий Chromium во время установки.
PUPPETEER_DOWNLOAD_HOST — перезаписывает префикс URL, используемый для загрузки Chromium. Примечание: это включает протокол и, возможно, префикс пути. По умолчанию https://storage.googleapis.com.
PUPPETEER_DOWNLOAD_PATH — перезаписывает путь к папке для скачиваний. По умолчанию <root>/.local-chromium, где <root> — корневой каталог пакета puppeteer.
PUPPETEER_CHROMIUM_REVISION — указывает определённую версию Chromium, которую Puppeteer должен использовать. См. puppeteer.launch([options]), чтобы узнать, как определяется путь к исполняемому файлу. ОСТОРОЖНО: Puppeteer гарантированно работает только с встроенным Chromium, используйте на свой страх и риск.
PUPPETEER_EXECUTABLE_PATH — указывает путь к исполняемому файлу, который будет использоваться в puppeteer.launch. См. puppeteer.launch([options]), чтобы узнать, как определяется путь к исполняемому файлу. ОСТОРОЖНО: Puppeteer гарантированно работает только с встроенным Chromium, используйте на свой страх и риск.
PUPPETEER_PRODUCT — указывает, какой браузер должен использовать Puppeteer. Должно быть одно из chrome или firefox. Это также может использоваться во время установки для получения рекомендуемого бинарника браузера. Установка product программно в puppeteer.launch([options]) переопределяет эту переменную среды. Продукт показан в puppeteer.product

ПРИМЕЧАНИЕ Переменные среды PUPPETEER_* не учитываются в пакете puppeteer-core.

Работа с расширениями Chrome

Puppeteer может использоваться для тестирования расширений Chrome.

ПРИМЕЧАНИЕ Расширения в Chrome/Chromium в настоящее время работают только в режиме без графического интерфейса.

Ниже приведен код для получения ссылки на задний план расширения, исходный код которого находится в ./my-extension:

const puppeteer = require('puppeteer');

(async () => {
  const pathToExtension = require('path').join(__dirname, 'my-extension');
  const browser = await puppeteer.launch({
    headless: false,
    args: [
      `--disable-extensions-except=${pathToExtension}`,
      `--load-extension=${pathToExtension}`
    ]
  });
  const targets = await browser.targets();
  const backgroundPageTarget = targets.find(target => target.type() === 'background_page');
  const backgroundPage = await backgroundPageTarget.page();
  // Test the background page as you would any other page.
  await browser.close();
})();

ПРИМЕЧАНИЕ Пока невозможно протестировать всплывающие окна или скрипты содержимого расширения.

Класс: Puppeteer

Модуль Puppeteer предоставляет метод запуска экземпляра Chromium. Ниже приведён типичный пример использования Puppeteer для автоматизации:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();

puppeteer.clearCustomQueryHandlers()

Очищает все зарегистрированные обработчики.

puppeteer.connect(options)

options <Объект>
- browserWSEndpoint <?строка> конечная точка веб-сокета браузера для подключения.
- browserURL <?строка> URL браузера для подключения в формате http://${host}:${port}. Используется взаимозаменяемо с browserWSEndpoint, чтобы Puppeteer мог получить его из конечной точки метаданных.
- ignoreHTTPSErrors <логическое> Игнорировать ошибки HTTPS при навигации. По умолчанию false.
- defaultViewport <Объект> Устанавливает согласованный viewport для каждой страницы. По умолчанию viewport 800x600. null отключает дефолтный viewport.
  - width <число> ширина страницы в пикселях.
  - height <число> высота страницы в пикселях.
  - deviceScaleFactor <число> Указывает коэффициент масштабирования устройства (можно рассматривать как dpr). По умолчанию 1.
  - isMobile <логическое> Учитывать ли тег meta viewport. По умолчанию false.
  - hasTouch<логическое> Указывает, поддерживает ли viewport события касания. По умолчанию false
  - isLandscape <логическое> Указывает, находится ли viewport в ландшафтном режиме. По умолчанию false.
- slowMo <число> Замедляет операции Puppeteer на указанное количество миллисекунд. Полезно, чтобы вы могли видеть, что происходит.
- transport <ConnectionTransport> Экспериментально Указывает объект пользовательского транспорта для использования Puppeteer.
- product <строка> Возможные значения: chrome, firefox. По умолчанию chrome.
возвращает: <Promise<Браузер>>

Этот метод подключает Puppeteer к существующему экземпляру браузера.

puppeteer.createBrowserFetcher([options])

options <Объект>
- host <строка> Хост для загрузки, используемый по умолчанию. По умолчанию https://storage.googleapis.com. Если product равно firefox, по умолчанию https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central.
- path <строка> Путь к папке для загрузок. По умолчанию <root>/.local-chromium, где <root> — корень пакета Puppeteer. Если product равно firefox, по умолчанию <root>/.local-firefox.
- platform <"linux"|"mac"|"win32"|"win64"> строка для текущей платформы. Возможные значения: mac, win32, win64, linux. По умолчанию — текущая платформа.
- product <"chrome"|"firefox"> строка для продукта, который необходимо запустить. Возможные значения: chrome, firefox. По умолчанию chrome.
возвращает: <BrowserFetcher>

puppeteer.customQueryHandlerNames()

возвращает: <Массив> Список имен всех зарегистрированных обработчиков пользовательских запросов.

puppeteer.defaultArgs([options])

options <Объект> Набор настраиваемых параметров для браузера. Может содержать следующие поля:
- headless <логическое значение> Запуск браузера в режиме headless. По умолчанию true, если параметр devtools равен true.
- args <Массив<строк>> Дополнительные аргументы для экземпляра браузера. Список флагов Chromium можно найти здесь.
- userDataDir <строка> Путь к каталогу данных пользователя.
- devtools <логическое значение> Автоматическое открытие панели DevTools для каждого вкладки. Если этот параметр true, параметр headless будет установлен в false.
возвращает: <Массив<строк>>

Флаги, с которыми будет запускаться Chromium по умолчанию.

puppeteer.devices

возвращает: <Объект>

Возвращает список устройств для использования с page.emulate(options). Полный список устройств можно найти в src/common/DeviceDescriptors.ts.

const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulate(iPhone);
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();

puppeteer.errors

возвращает: <Объект>
- TimeoutError <функция> Класс ошибки TimeoutError.

Методы Puppeteer могут генерировать ошибки, если запрос не может быть выполнен. Например, page.waitForSelector(selector[, options]) может завершиться ошибкой, если селектор не соответствует ни одному узлу в течение заданного времени.

Для определённых типов ошибок Puppeteer использует специфические классы ошибок. Эти классы доступны через puppeteer.errors

Пример обработки ошибки таймаута:

try {
  await page.waitForSelector('.foo');
} catch (e) {
  if (e instanceof puppeteer.errors.TimeoutError) {
    // Do something if this is a timeout.
  }
}

ПРИМЕЧАНИЕ В старых версиях Puppeteer (до v1.14.0) ошибки можно было получить с помощью require('puppeteer/Errors').

puppeteer.executablePath()

возвращает: <строка> Путь, где Puppeteer ожидает найти собранный браузер. Бинарник браузера может отсутствовать, если загрузка была пропущена с помощью PUPPETEER_SKIP_DOWNLOAD.

ПРИМЕЧАНИЕ puppeteer.executablePath() зависит от переменных среды PUPPETEER_EXECUTABLE_PATH и PUPPETEER_CHROMIUM_REVISION. Подробнее см. Переменные среды.

puppeteer.launch([options])

options <Объект> Набор настраиваемых параметров для настройки браузера. Может содержать следующие поля:
- product <строка> Браузер, который необходимо запустить. В настоящее время это либо chrome либо firefox. См. также PUPPETEER_PRODUCT.
- ignoreHTTPSErrors <логическое значение> Нужно ли игнорировать ошибки HTTPS при навигации. По умолчанию false.
- headless <логическое значение> Нужно ли запускать браузер в бесголовом режиме. По умолчанию true, если опция devtools равна true.
- executablePath <строка> Путь к исполняемому файлу браузера, который нужно запустить вместо связанного Chromium. Если executablePath — это относительный путь, то он разрешается относительно текущей рабочей директории. ОСТОРОЖНО: Puppeteer гарантированно работает только с связанным Chromium, используйте на свой страх и риск.
- slowMo <число> Замедляет операции Puppeteer на указанное количество миллисекунд. Полезно, чтобы вы могли увидеть, что происходит.
- defaultViewport <?Объект> Устанавливает согласованный viewport для каждой страницы. По умолчанию используется viewport размером 800x600. null отключает значение viewport по умолчанию.
  - width <число> Ширина страницы в пикселях.
  - height <число> Высота страницы в пикселях.
  - deviceScaleFactor <число> Укажите коэффициент масштаба устройства (можно рассматривать как dpr). По умолчанию 1.
  - isMobile <логическое значение> Учитывается ли тег meta viewport. По умолчанию false.
  - hasTouch<логическое значение> Указывает, поддерживает ли viewport сенсорные события. По умолчанию false
  - isLandscape <логическое значение> Указывает, находится ли viewport в ландшафтном режиме. По умолчанию false.
- args <Массив<строка>> Дополнительные аргументы для передачи экземпляру браузера. Список флагов Chromium можно найти здесь, а список флагов Firefox здесь.
- ignoreDefaultArgs <логическое значение|Массив<строка>> Если true, не используйте puppeteer.defaultArgs(). Если задан массив, отфильтруйте заданные аргументы по умолчанию. Опасная опция; используйте с осторожностью. По умолчанию false.
- handleSIGINT <логическое значение> Закрыть процесс браузера при нажатии Ctrl-C. По умолчанию true.
- handleSIGTERM <логическое значение> Закрыть процесс браузера при получении SIGTERM. По умолчанию true.
- handleSIGHUP <логическое значение> Закрыть процесс браузера при получении SIGHUP. По умолчанию true.
- timeout <число> Максимальное время в миллисекундах ожидания запуска экземпляра браузера. По умолчанию 30000 (30 секунд). Передайте 0 для отключения таймаута.
- dumpio <логическое значение> Нужно ли перенаправлять стандартный вывод и стандартный ошибку процесса браузера в process.stdout и process.stderr? По умолчанию false.
- userDataDir <строка> Путь к каталогу данных пользователя.
- env <Объект> Укажите переменные среды, которые будут видны браузеру. По умолчанию process.env.
- devtools <логическое значение> Нужно ли автоматически открывать панель DevTools для каждой вкладки? Если эта опция true, то опция headless будет установлена false.
- pipe <логическое значение> Подключаться ли к браузеру через канал, а не через WebSocket. По умолчанию false.
- extraPrefsFirefox <Объект> Дополнительные параметры, которые можно передать в Firefox (см. PUPPETEER_PRODUCT)
возвращает: <Promise<Браузер>> Promise, который разрешается до экземпляра браузера.

Вы можете использовать ignoreDefaultArgs для фильтрации --mute-audio из аргументов по умолчанию:

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--mute-audio']
});

ПРИМЕЧАНИЕ Puppeteer также может использоваться для управления браузером Chrome, но лучше всего работает с той версией Chromium, с которой он связан. Нет гарантии, что он будет работать с любой другой версией. Используйте опцию executablePath с большой осторожностью.

Если предпочтительнее Google Chrome (а не Chromium), рекомендуется использовать сборку Chrome Canary или Dev Channel.

В puppeteer.launch([options]) выше, любое упоминание Chromium также относится к Chrome.

См. this article для описания различий между Chromium и Chrome. This article описывает некоторые различия для пользователей Linux.

puppeteer.networkConditions

возвращает: <Объект>

Возвращает список сетевых условий, которые будут использоваться с page.emulateNetworkConditions(networkConditions). Фактический список условий можно найти в src/common/NetworkConditions.ts.

const puppeteer = require('puppeteer');
const slow3G = puppeteer.networkConditions['Slow 3G'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulateNetworkConditions(slow3G);
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();

puppeteer.product

возвращает: <строка> возвращает имя браузера, который находится под управлением ("chrome" или "firefox")

Продукт устанавливается переменной среды PUPPETEER_PRODUCT или опцией product в puppeteer.launch([options]) и по умолчанию равен chrome. Поддержка Firefox экспериментальна и требует установки Puppeteer через PUPPETEER_PRODUCT=firefox npm i puppeteer.

puppeteer.registerCustomQueryHandler(name, queryHandler)

name <строка> Имя, под которым будет зарегистрирован обработчик пользовательских запросов.
queryHandler <Обработчик пользовательского запроса> Регистрируемый обработчик пользовательских запросов.

Регистрирует обработчик пользовательских запросов. После регистрации обработчик можно использовать повсюду, где ожидается селектор, добавив к строке выбора префикс <name>/. Имя может содержать только строчные и заглавные латинские буквы.

Пример:

puppeteer.registerCustomQueryHandler('getByClass', {
  queryOne: (element, selector) => {
    return element.querySelector(`.${selector}`);
  },
  queryAll: (element, selector) => {
    return element.querySelectorAll(`.${selector}`);
  },
});
const aHandle = await page.$('getByClass/…');

puppeteer.unregisterCustomQueryHandler(name)

name <строка> Имя обработчика запросов, который нужно отменить.

класс: BrowserFetcher

BrowserFetcher может загружать и управлять различными версиями Chromium и Firefox.

BrowserFetcher работает с строками ревизий, которые указывают точную версию Chromium, например "533271". Строки ревизий можно получить из omahaproxy.appspot.com.

В случае с Firefox, BrowserFetcher загружает Firefox Nightly и работает с номерами версий, такими как "75".

Пример использования BrowserFetcher для загрузки определённой версии Chromium и запуска Puppeteer с ней:

const browserFetcher = puppeteer.createBrowserFetcher();
const revisionInfo = await browserFetcher.download('533271');
const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})

ПРИМЕЧАНИЕ BrowserFetcher не предназначен для одновременной работы с другими экземплярами BrowserFetcher, которые используют один и тот же каталог загрузок.

browserFetcher.canDownload(revision)

revision <строка> ревизия для проверки доступности.
возвращает: <Promise<логическое значение>> возвращает true если ревизия может быть загружена с хоста.

Метод инициирует запрос HEAD для проверки доступности ревизии.

browserFetcher.download(revision[, progressCallback])

revision <строка> ревизия для загрузки.
progressCallback <функция(число, число)> Функция, которая будет вызываться с двумя аргументами:
- downloadedBytes <число> количество загруженных байт
- totalBytes <число> общий объём загрузки.
возвращает: <Promise<объект>> Возвращает информацию о ревизии при её загрузке и извлечении
- revision <строка> ревизия, из которой была создана информация
- folderPath <строка> путь к извлечённой папке ревизии
- executablePath <строка> путь к исполняемому файлу ревизии
- url <строка> URL для загрузки этой ревизии
- local <логическое значение> доступна ли ревизия локально

Метод инициирует запрос GET для загрузки ревизии с хоста.

browserFetcher.host()

возвращает: <строка> Использованный хост для загрузки.

browserFetcher.localRevisions()

возвращает: <Promise<массив<строка>>> Список всех ревизий (для текущего product) доступных локально.

browserFetcher.platform()

возвращает: <строка> Одно из mac, linux, win32 или win64.

browserFetcher.product()

возвращает: <строка> Одно из chrome или firefox.

browserFetcher.remove(revision)

revision <строка> ревизия для удаления для текущего product. Метод выбросит исключение, если ревизия не была загружена.
возвращает: <Promise> Возвращает результат, когда ревизия удалена.

browserFetcher.revisionInfo(revision)

revision <строка> ревизия, для которой нужна информация.
возвращает: <объект>
- revision <строка> ревизия, из которой была создана информация
- folderPath <строка> путь к извлечённой папке ревизии
- executablePath <строка> путь к исполняемому файлу ревизии
- url <строка> URL для загрузки этой ревизии
- local <логическое значение> доступна ли ревизия локально
- product <строка> одно из chrome или firefox

ПРИМЕЧАНИЕ Многие методы BrowserFetcher, такие как remove и revisionInfo зависят от выбора product. См. puppeteer.createBrowserFetcher([options]).

класс: Браузер

расширяет: EventEmitter

Браузер создается, когда Puppeteer подключается к экземпляру Chromium, либо через puppeteer.launch, либо через puppeteer.connect.

Пример использования браузера для создания страницы:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Пример отключения и повторного подключения к браузеру:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  // Store the endpoint to be able to reconnect to Chromium
  const browserWSEndpoint = browser.wsEndpoint();
  // Disconnect puppeteer from Chromium
  browser.disconnect();

  // Use the endpoint to reestablish a connection
  const browser2 = await puppeteer.connect({browserWSEndpoint});
  // Close Chromium
  await browser2.close();
})();

событие: 'disconnected'

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

Chromium закрыт или завис
Был вызван метод browser.disconnect

событие: 'targetchanged'

<Целевой объект>

Срабатывает, когда URL целевого объекта меняется.

ПРИМЕЧАНИЕ Это включает изменения целевых объектов в контекстах браузера в режиме инкогнито.

событие: 'targetcreated'

<Целевой объект>

Срабатывает, когда создаётся целевой объект, например, при открытии новой страницы с помощью window.open или browser.newPage.

ПРИМЕЧАНИЕ Это включает создание целевых объектов в контекстах браузера в режиме инкогнито.

событие: 'targetdestroyed'

<Целевой объект>

Срабатывает, когда целевой объект уничтожается, например, при закрытии страницы.

ПРИМЕЧАНИЕ Это включает уничтожение целевых объектов в контекстах браузера в режиме инкогнито.

browser.browserContexts()

возвращает: <массив<BrowserContext>>

Возвращает массив всех открытых контекстов браузера. В вновь созданном браузере это вернёт единственный экземпляр BrowserContext.

browser.close()

возвращает: <Promise>

Закрывает Chromium и все его страницы (если они были открыты). Объект Browser считается удалённым и больше не может использоваться.

browser.createIncognitoBrowserContext()

returns: <Promise<BrowserContext>>

Создаёт новый контекст браузера в режиме инкогнито. Он не будет совместно использовать куки/кеш с другими контекстами браузера.

(async () => {
  const browser = await puppeteer.launch();
  // Create a new incognito browser context.
  const context = await browser.createIncognitoBrowserContext();
  // Create a new page in a pristine context.
  const page = await context.newPage();
  // Do stuff
  await page.goto('https://example.com');
})();

browser.defaultBrowserContext()

returns: <BrowserContext>

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

browser.disconnect()

Отключает Puppeteer от браузера, но оставляет процесс Chromium запущенным. После вызова disconnect, объект Browser считается удалённым и больше не может использоваться.

browser.isConnected()

returns: <boolean>

Указывает, что браузер подключён.

browser.newPage()

returns: <Promise<Page>>

Обещание, которое разрешается до нового объекта Page. Page создаётся в контексте браузера по умолчанию.

browser.pages()

returns: <Promise<Array<Page>>> Обещание, которое разрешается до массива всех открытых страниц. Невидимые страницы, такие как "background_page", здесь не отображаются. Вы можете найти их, используя target.page().

Массив всех страниц внутри Browser. В случае нескольких контекстов браузера метод вернёт массив со всеми страницами во всех контекстах браузера.

browser.process()

returns: <?ChildProcess> Запущенный процесс браузера. Возвращает null если экземпляр браузера был создан с помощью метода puppeteer.connect.

browser.target()

returns: <Target>

Целевой объект, связанный с браузером.

browser.targets()

returns: <Array<Target>>

Массив всех активных целевых объектов внутри Browser. В случае нескольких контекстов браузера метод вернёт массив со всеми целевыми объектами во всех контекстах браузера.

browser.userAgent()

returns: <Promise<string>> Обещание, которое разрешается до исходного user agent браузера.

ПРИМЕЧАНИЕ Страницы могут переопределять user agent браузера с помощью page.setUserAgent

browser.version()

returns: <Promise<string>> Для бессерверного Chromium это аналогично HeadlessChrome/61.0.3153.0. Для не бессерверного – аналогично Chrome/61.0.3153.0.

ПРИМЕЧАНИЕ Формат browser.version() может измениться в будущих выпусках Chromium.

browser.waitForTarget(predicate[, options])

predicate <function(Target):boolean> Функция, которая будет запускаться для каждого целевого объекта
options <Object>
- timeout <number> Максимальное время ожидания в миллисекундах. Передайте 0 чтобы отключить таймаут. По умолчанию составляет 30 секунд.
returns: <Promise<Target>> Обещание, которое разрешается до первого найденного целевого объекта, соответствующего функции predicate.

Этот поиск целевого объекта выполняется во всех контекстах браузера.

Пример поиска целевого объекта для страницы, открытой с помощью window.open:

await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');

browser.wsEndpoint()

returns: <string> URL websocket браузера.

Конечная точка websocket браузера, которая может быть использована в качестве аргумента для puppeteer.connect. Формат: ws://${host}:${port}/devtools/browser/<id>

Вы можете найти webSocketDebuggerUrl из http://${host}:${port}/json/version. Подробнее о протоколе devtools devtools protocol и конечной точке браузера browser endpoint.

class: BrowserContext

extends: EventEmitter

BrowserContexts предоставляют способ работы с несколькими независимыми сессиями браузера. При запуске браузера используется один контекст BrowserContext по умолчанию. Метод browser.newPage() создаёт страницу в контексте браузера по умолчанию.

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

Puppeteer позволяет создавать контексты браузера "инкогнито" с помощью метода browser.createIncognitoBrowserContext(). Контексты браузера "инкогнито" не записывают данные о просмотре на диск.

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

event: 'targetchanged'

<Target>

Выдаётся, когда URL целевого объекта внутри контекста браузера изменяется.

event: 'targetcreated'

<Target>

Выдаётся, когда создаётся новый целевой объект внутри контекста браузера, например, когда открывается новая страница с помощью window.open или browserContext.newPage.

event: 'targetdestroyed'

<Target>

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

browserContext.browser()

returns: <Browser>

Браузер, которому принадлежит этот контекст браузера.

browserContext.clearPermissionOverrides()

returns: <Promise>

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

const context = browser.defaultBrowserContext();
context.overridePermissions('https://example.com', ['clipboard-read']);
// do stuff ..
context.clearPermissionOverrides();

browserContext.close()

returns: <Promise>

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

ПРИМЕЧАНИЕ Только контексты браузера в режиме инкогнито можно закрыть.

browserContext.isIncognito()

returns: <boolean>

Возвращает значение true, если контекст BrowserContext находится в режиме инкогнито. Контекст браузера по умолчанию — единственный контекст, не являющийся контекстом инкогнито.

ПРИМЕЧАНИЕ Контекст браузера по умолчанию закрыть нельзя.

browserContext.newPage()

returns: <Promise<Page>>

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

browserContext.overridePermissions(origin, permissions)

origin <string> Источник для предоставления разрешений, например, "https://example.com".
permissions <Array<string>> Массив разрешений для предоставления. Все разрешения, не указанные здесь, будут автоматически отклонены. Разрешения могут быть одним из следующих значений:
- 'geolocation'
- 'midi'
- 'midi-sysex' (исключительно системный midi)
- 'notifications'
- 'push'
- 'camera'
- 'microphone'
- 'background-sync'
- 'ambient-light-sensor'
- 'accelerometer'
- 'gyroscope'
- 'magnetometer'
- 'accessibility-events'
- 'clipboard-read'
- 'clipboard-write'
- 'payment-handler'
returns: <Promise>

const context = browser.defaultBrowserContext();
await context.overridePermissions('https://html5demos.com', ['geolocation']);

browserContext.pages()

returns: <Promise<Array<Page>>> Promise, который возвращает массив всех открытых страниц. Невидимые страницы, такие как "background_page", здесь не будут перечислены. Вы можете найти их, используя target.page().

Массив всех страниц внутри контекста браузера.

browserContext.targets()

returns: <Array<Target>>

Массив всех активных целевых объектов внутри контекста браузера.

browserContext.waitForTarget(predicate[, options])

predicate <function(Target):boolean> Функция, которая будет выполняться для каждого целевого объекта
options <Object>
- timeout <number> Максимальное время ожидания в миллисекундах. Передайте 0 для отключения таймаута. По умолчанию 30 секунд.
returns: <Promise<Target>> Promise, который возвращает первый найденный целевой объект, соответствующий функции predicate.

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

Пример поиска целевого объекта для страницы, открытой с помощью window.open:

await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');

class: Page

extends: EventEmitter

Page предоставляет методы для взаимодействия с одним вкладом или фоновой страницей расширения в Chromium. Один экземпляр Browser может иметь несколько экземпляров Page.

В этом примере создается страница, она переходит по URL, а затем сохраняется скриншот:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'screenshot.png'});
  await browser.close();
})();

Класс Page испускает различные события (описанные ниже), которые могут быть обработаны с помощью любого из методов EventEmitter, таких как on, once или off.

В этом примере выводится сообщение для события load одной страницы:

page.once('load', () => console.log('Page loaded!'));

Чтобы отказаться от подписки на события, используйте метод off:

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.off('request', logRequest);

event: 'close'

Издаётся при закрытии страницы.

event: 'console'

<ConsoleMessage>

Издаётся, когда JavaScript внутри страницы вызывает один из методов API консоли, например, console.log или console.dir. Также издаётся, если страница генерирует ошибку или предупреждение.

Переданные аргументы в console.log отображаются как аргументы обработчика событий.

Пример обработки события console:

page.on('console', msg => {
  for (let i = 0; i < msg.args().length; ++i)
    console.log(`${i}: ${msg.args()[i]}`);
});
page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));

event: 'dialog'

<Dialog>

Издаётся, когда появляется диалоговое окно JavaScript, такое как alert, prompt, confirm или beforeunload. Puppeteer может ответить на диалоговое окно через методы Dialog's accept или dismiss.

event: 'domcontentloaded'

Издаётся, когда JavaScript-событие DOMContentLoaded отправляется.

event: 'error'

<Error>

Издаётся, когда страница терпит крах.

ПРИМЕЧАНИЕ Событие error имеет особое значение в Node, см. события ошибок для получения подробностей.

event: 'frameattached'

<Frame>

Издаётся при присоединении кадра.

event: 'framedetached'

<Frame>

Издаётся при отделении кадра.

event: 'framenavigated'

<Frame>

Издаётся, когда кадр переходит по новому URL.

event: 'load'

Издаётся, когда JavaScript-событие load отправляется.

event: 'metrics'

<Object>
- title <string> Заголовок, переданный в console.timeStamp.
- metrics <Object> Объект, содержащий метрики в виде пар ключ/значение. Значения метрик имеют тип <number>.

Издаётся, когда JavaScript-код вызывает console.timeStamp. Список метрик см. в page.metrics.

event: 'pageerror'

<Error> Сообщение об ошибке

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

<Page> Страница, соответствующая окну "popup"

Издаётся, когда страница открывает новую вкладку или окно.

const [popup] = await Promise.all([
  new Promise(resolve => page.once('popup', resolve)),
  page.click('a[target=_blank]'),
]);

const [popup] = await Promise.all([
  new Promise(resolve => page.once('popup', resolve)),
  page.evaluate(() => window.open('https://example.com')),
]);

event: 'request'

<HTTPRequest>

Издаётся, когда страница отправляет запрос. Объект HTTPRequest является только для чтения. Чтобы перехватывать и изменять запросы, см. page.setRequestInterception.

event: 'requestfailed'

<HTTPRequest>

Издаётся, когда запрос завершается неудачно, например, из-за истечения времени ожидания.

ПРИМЕЧАНИЕ Ответы HTTP с ошибками, такие как 404 или 503, всё ещё являются успешными ответами с точки зрения HTTP, поэтому запрос завершится событием 'requestfinished', а не событием 'requestfailed'.

event: 'requestfinished'

<HTTPRequest>

Издаётся, когда запрос завершается успешно.

event: 'response'

<HTTPResponse>

Издаётся, когда получен HTTPResponse.

event: 'workercreated'

<WebWorker>

Издаётся, когда страница создаёт отделённый WebWorker.

event: 'workerdestroyed'

<WebWorker>

Издаётся, когда отделённый WebWorker завершает работу.

page.$(selector)

selector <string> Селектор для запроса к странице
returns: <Promise<?ElementHandle>>

Метод выполняет document.querySelector внутри страницы. Если ни один элемент не соответствует селектору, возвращаемое значение разрешается в null.

Сокращение для page.mainFrame().$(selector).

page.$$(selector)

selector <string> Селектор для запроса к странице
returns: <Promise<Array<ElementHandle>>>

Метод выполняет document.querySelectorAll внутри страницы. Если ни один элемент не соответствует селектору, возвращаемое значение разрешается в [].

Сокращение для page.mainFrame().$$(selector).

page.$$eval(selector, pageFunction[, ...args])

selector <string> Селектор для запроса страницы
pageFunction <function(Array<Element>)> Функция для выполнения в контексте браузера
...args <...Serializable|JSHandle> Аргументы для передачи в pageFunction
returns: <Promise<Serializable>> Обещание, разрешающееся значением, возвращённым pageFunction

Этот метод выполняет Array.from(document.querySelectorAll(selector)) на странице и передаёт его в качестве первого аргумента в pageFunction.

Если pageFunction возвращает Promise, то page.$$eval ожидает разрешения обещания и возвращает его значение.

Примеры:

const divCount = await page.$$eval('div', divs => divs.length);

const options = await page.$$eval('div > span.options', options => options.map(option => option.textContent));

page.$eval(selector, pageFunction[, ...args])

selector <string> Селектор для запроса страницы
pageFunction <function(Element)> Функция для выполнения в контексте браузера
...args <...Serializable|JSHandle> Аргументы для передачи в pageFunction
returns: <Promise<Serializable>> Обещание, разрешающееся значением, возвращённым pageFunction

Этот метод выполняет document.querySelector на странице и передаёт его в качестве первого аргумента в pageFunction. Если элемент, соответствующий selector, не найден, метод выбросит ошибку.

Если pageFunction возвращает Promise, то page.$eval ожидает разрешения обещания и возвращает его значение.

Примеры:

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

Сокращение для page.mainFrame().$eval(selector, pageFunction).

page.$x(expression)

expression <string> Выражение XPath для обработки.
returns: <Promise<Array<ElementHandle>>>

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

Сокращение для page.mainFrame().$x(expression)

page.accessibility

returns: <Accessibility>

page.addScriptTag(options)

options <Object>
- url <string> URL скрипта для добавления.
- path <string> Путь к JavaScript-файлу для вставки в фрейм. Если path является относительным путём, то он разрешается относительно текущей рабочей директории.
- content <string> Необработанный JavaScript-код для вставки в фрейм.
- type <string> Тип скрипта. Используйте 'module', чтобы загрузить модуль Javascript ES6. Смотрите script для получения дополнительной информации.
returns: <Promise<ElementHandle>> который разрешается добавленной меткой, когда срабатывает onload скрипта или когда содержимое скрипта было вставлено во фрейм.

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

Сокращение для page.mainFrame().addScriptTag(options).

page.addStyleTag(options)

options <Object>
- url <string> URL тега <link>.
- path <string> Путь к файлу CSS для вставки во фрейм. Если path является относительным путём, то он разрешается относительно текущей рабочей директории.
- content <string> Необработанное содержимое CSS для вставки во фрейм.
returns: <Promise<ElementHandle>> который разрешается добавленным тегом, когда срабатывает onload стилизованного тега или когда содержимое CSS было вставлено во фрейм.

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

Сокращение для page.mainFrame().addStyleTag(options).

page.authenticate(credentials)

credentials <?Object>
- username <string>
- password <string>
returns: <Promise>

Предоставляет данные для аутентификации HTTP.

Чтобы отключить аутентификацию, передайте null.

page.bringToFront()

returns: <Promise>

Переводит страницу вперёд (активирует вкладку).

page.browser()

returns: <Браузер>

Получить браузер, к которому принадлежит страница.

page.browserContext()

returns: <Контекст браузера>

Получить контекст браузера, к которому принадлежит страница.

page.click(selector[, options])

selector <string> Выбор селектора для поиска элемента, который нужно нажать. Если селектору удовлетворяют несколько элементов, будет нажат первый.
options <Объект>
- button <"left"|"right"|"middle"> По умолчанию left.
- clickCount <число> по умолчанию 1. См. UIEvent.detail.
- delay <число> Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
возвращает: <Promise> Promise, который выполняется, когда элемент, соответствующий selector, успешно нажат. Promise будет отклонен, если соответствующего элемента нет selector.

Этот метод извлекает элемент с selector, прокручивает его в область видимости, если необходимо, и затем использует page.mouse для нажатия в центре элемента. Если нет элемента, соответствующего selector, метод генерирует ошибку.

Обратите внимание, что если click() вызывает событие перехода, и есть отдельное page.waitForNavigation() promise для выполнения, вы можете столкнуться с гонкой, которая даст неожиданные результаты. Правильный шаблон для нажатия и ожидания перехода выглядит следующим образом:

const [response] = await Promise.all([
  page.waitForNavigation(waitOptions),
  page.click(selector, clickOptions),
]);

Сокращение для page.mainFrame().click(selector[, options]).

page.close([options])

options <Объект>
- runBeforeUnload <логическое> По умолчанию false. Выполнять ли обработчики страницы перед закрытием.
возвращает: <Promise>

По умолчанию, page.close() не выполняет обработчики перед закрытием.

ПРИМЕЧАНИЕ если runBeforeUnload передано как true, диалоговое окно beforeunload может быть вызвано и должно быть обработано вручную через событие 'dialog' страницы.

page.content()

возвращает: <Promise<строка>>

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

page.cookies([...urls])

...urls <...строка>
возвращает: <Promise<Массив<объект>>>
- name <строка>
- value <строка>
- domain <строка>
- path <строка>
- expires <число> Время Unix в секундах.
- size <число>
- httpOnly <логическое>
- secure <логическое>
- session <логическое>
- sameSite <"Strict"|"Lax"|"Extended"|"None">

Если URL не указаны, этот метод возвращает куки для текущего URL страницы. Если URL указаны, возвращаются только куки для этих URL.

page.coverage

возвращает: <Обхват>

page.deleteCookie(...cookies)

...cookies <...объект>
- name <строка> обязательно
- url <строка>
- domain <строка>
- path <строка>
возвращает: <Promise>

page.emulate(options)

options <объект>
- viewport <объект>
  - width <число> ширина страницы в пикселях.
  - height <число> высота страницы в пикселях.
  - deviceScaleFactor <число> Укажите коэффициент масштабирования устройства (можно рассматривать как dpr). По умолчанию 1.
  - isMobile <логическое> Учитывать ли тэг meta viewport. По умолчанию false.
  - hasTouch<логическое> Указывает, поддерживает ли viewport события touch. По умолчанию false
  - isLandscape <логическое> Указывает, находится ли viewport в альбомной ориентации. По умолчанию false.
- userAgent <строка>
возвращает: <Promise>

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

page.setUserAgent(userAgent)
page.setViewport(viewport)

Для помощи в эмуляции, puppeteer предоставляет список описаний устройств, которые можно получить через puppeteer.devices.

page.emulate изменит размер страницы. Многие веб-сайты не ожидают, что телефоны будут изменять размер, поэтому вы должны эмулировать до перехода на страницу.

const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulate(iPhone);
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();

Список всех доступных устройств находится в исходном коде: src/common/DeviceDescriptors.ts.

page.emulateIdleState(overrides)

overrides <?объект> Если не задано, очищает эмуляцию
- isUserActive <логическое> обязательно
- isScreenUnlocked <логическое> обязательно
возвращает: <Promise>

page.emulateMediaFeatures(features)

features <?Array<Object>> Указанный массив объектов параметров среды отображения эмулирует параметры среды отображения CSS на странице. Каждый объект параметров среды отображения должен иметь следующие свойства:
- name <строка> Имя параметра среды отображения CSS. Поддерживаемые имена — 'prefers-colors-scheme', 'prefers-reduced-motion', и 'color-gamut'.
- value <строка> Значение для данного параметра среды отображения CSS.
возвращает: <Promise>

await page.emulateMediaFeatures([{ name: 'prefers-color-scheme', value: 'dark' }]);
await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
// → true
await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
// → false

await page.emulateMediaFeatures([{ name: 'prefers-reduced-motion', value: 'reduce' }]);
await page.evaluate(() => matchMedia('(prefers-reduced-motion: reduce)').matches);
// → true
await page.evaluate(() => matchMedia('(prefers-reduced-motion: no-preference)').matches);
// → false

await page.emulateMediaFeatures([
  { name: 'prefers-color-scheme', value: 'dark' },
  { name: 'prefers-reduced-motion', value: 'reduce' },
]);
await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
// → true
await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
// → false
await page.evaluate(() => matchMedia('(prefers-reduced-motion: reduce)').matches);
// → true
await page.evaluate(() => matchMedia('(prefers-reduced-motion: no-preference)').matches);
// → false

await page.emulateMediaFeatures([
  { name: 'color-gamut', value: 'p3' },
]);
await page.evaluate(() => matchMedia('(color-gamut: srgb)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: p3)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: rec2020)').matches);
// → false

page.emulateMediaType(type)

type <?строка> Изменяет тип среды отображения CSS страницы. Допустимые значения — 'screen', 'print' и null. Передача null отключает эмуляцию параметров среды отображения CSS.
возвращает: <Promise>

await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

await page.emulateMediaType('print');
await page.evaluate(() => matchMedia('screen').matches);
// → false
await page.evaluate(() => matchMedia('print').matches);
// → true

await page.emulateMediaType(null);
await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

page.emulateNetworkConditions(networkConditions)

networkConditions <?Объект> Передача null отключает эмуляцию сетевых условий.
- download <число> Скорость загрузки (байт/с), -1 для отключения
- upload <число> Скорость отправки (байт/с), -1 для отключения
- latency <число> Задержка (мс), 0 для отключения
возвращает: <Promise>

ПРИМЕЧАНИЕ Это не влияет на WebSockets и WebRTC PeerConnections (см. https://crbug.com/563644)

const puppeteer = require('puppeteer');
const slow3G = puppeteer.networkConditions['Slow 3G'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulateNetworkConditions(slow3G);
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
})();

page.emulateTimezone(timezoneId)

timezoneId <?строка> Изменяет часовой пояс страницы. См. метаданные ICU для списка поддерживаемых идентификаторов часовых поясов. Передача null отключает эмуляцию часового пояса.
возвращает: <Promise>

page.emulateVisionDeficiency(type)

type <?строка> Эмулирует заданный дефект зрения на странице. Поддерживаемые типы дефектов зрения — 'achromatopsia', 'deuteranopia', 'protanopia', 'tritanopia', 'blurredVision', и 'none'.
возвращает: <Promise>

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://v8.dev/blog/10-years');

  await page.emulateVisionDeficiency('achromatopsia');
  await page.screenshot({ path: 'achromatopsia.png' });

  await page.emulateVisionDeficiency('deuteranopia');
  await page.screenshot({ path: 'deuteranopia.png' });

  await page.emulateVisionDeficiency('blurredVision');
  await page.screenshot({ path: 'blurred-vision.png' });

  await browser.close();
})();

page.evaluate(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая оценке в контексте страницы
...args <...сериализуемое|JSHandle> Аргументы, передаваемые функции pageFunction
возвращает: <Promise<сериализуемое>> Promise, который разрешается значением, возвращаемым функцией pageFunction

Если функция, переданная в page.evaluate, возвращает Promise, тогда page.evaluate ожидает разрешения обещания и возвращает его значение.

Если функция, переданная в page.evaluate, возвращает не-сериализуемое значение, тогда page.evaluate разрешается до undefined. Протокол DevTools также поддерживает передачу некоторых дополнительных значений, которые не сериализуются с помощью JSON: -0, NaN, Infinity, -Infinity, и литералы bigint.

Передача аргументов в pageFunction:

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

Вместо функции также можно передать строку:

console.log(await page.evaluate('1 + 2')); // prints "3"
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"

Экземпляры ElementHandle могут быть переданы в качестве аргументов в page.evaluate:

const bodyHandle = await page.$('body');
const html = await page.evaluate(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();

Сокращение для page.mainFrame().evaluate(pageFunction, ...args).

page.evaluateHandle(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая оценке в контексте страницы
...args <...сериализуемое|JSHandle> Аргументы, передаваемые функции pageFunction
возвращает: <Promise<JSHandle|ElementHandle>> Promise, который разрешается до объекта на странице (JSHandle) — возвращаемого значением функции pageFunction.

Единственное различие между page.evaluate и page.evaluateHandle состоит в том, что page.evaluateHandle возвращает объект на странице (JSHandle).

Если функция, переданная в page.evaluateHandle, возвращает Promise, тогда page.evaluateHandle ожидает разрешения обещания и возвращает его значение.

Вместо функции также можно передать строку:

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

Экземпляры JSHandle могут быть переданы в качестве аргументов в page.evaluateHandle:

const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();

По умолчанию эта функция возвращает JSHandle, однако, если ваша pageFunction возвращает HTML-элемент, вы получите ElementHandle:

const button = await page.evaluateHandle(() => document.querySelector('button'))
// button is an ElementHandle, so you can call methods such as click:
await button.click();

Сокращение для page.mainFrame().executionContext().evaluateHandle(pageFunction, ...args).

page.evaluateOnNewDocument(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая оценке в контексте браузера
...args <...сериализуемое> Аргументы, передаваемые функции pageFunction
возвращает: <Promise>

Добавляет функцию, которая будет вызвана в следующих сценариях:

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

Функция вызывается после создания документа, но до выполнения каких-либо его скриптов. Это полезно для изменения среды JavaScript, например, для инициализации Math.random.

Пример переопределения свойства navigator.languages перед загрузкой страницы:

// preload.js

// overwrite the `languages` property to use a custom getter
Object.defineProperty(navigator, "languages", {
  get: function() {
    return ["en-US", "en", "bn"];
  }
});

// In your puppeteer script, assuming the preload.js file is in same folder of our script
const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await page.evaluateOnNewDocument(preloadFile);

page.exposeFunction(name, puppeteerFunction)

name <строка> Имя функции в объекте window
puppeteerFunction <функция> Обратная функция, которая будет вызвана в контексте Puppeteer.
возвращает: <Promise>

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

Если puppeteerFunction возвращает Promise, он будет ожидать завершения.

ПРИМЕЧАНИЕ Функции, установленные через page.exposeFunction , сохраняются при переходе по страницам.

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

const puppeteer = require('puppeteer');
const crypto = require('crypto');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  page.on('console', msg => console.log(msg.text()));
  await page.exposeFunction('md5', text =>
    crypto.createHash('md5').update(text).digest('hex')
  );
  await page.evaluate(async () => {
    // use window.md5 to compute hashes
    const myString = 'PUPPETEER';
    const myHash = await window.md5(myString);
    console.log(`md5 of ${myString} is ${myHash}`);
  });
  await browser.close();
})();

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

const puppeteer = require('puppeteer');
const fs = require('fs');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  page.on('console', msg => console.log(msg.text()));
  await page.exposeFunction('readfile', async filePath => {
    return new Promise((resolve, reject) => {
      fs.readFile(filePath, 'utf8', (err, text) => {
        if (err)
          reject(err);
        else
          resolve(text);
      });
    });
  });
  await page.evaluate(async () => {
    // use window.readfile to read contents of a file
    const content = await window.readfile('/etc/hosts');
    console.log(content);
  });
  await browser.close();
})();

page.focus(selector)

selector <строка> Селектор элемента, на который нужно направить фокус. Если селектору удовлетворяют несколько элементов, фокус будет настроен на первый.
возвращает: <Promise> Promise, который разрешается, когда элемент, соответствующий selector, успешно получает фокус. Promise отклоняется, если нет элемента, соответствующего selector.

Этот метод получает элемент по selector и устанавливает на нём фокус. Если соответствующего элемента нет, метод генерирует ошибку.

Сокращение для page.mainFrame().focus(selector).

page.frames()

возвращает: <Массив<Фрейм>> Массив всех фреймов, присоединённых к странице.

page.goBack([options])

options <Объект> Параметры навигации, которые могут содержать следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд. Передайте 0 чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Переданный массив строк событий, навигация считается успешной после срабатывания всех событий. События могут быть следующими:
  - load - считать навигацию завершенной, когда срабатывает событие load.
  - domcontentloaded - считать навигацию завершенной, когда срабатывает событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда нет более 0 сетевых соединений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда нет более 2 сетевых соединений в течение как минимум 500 мс.
возвращает: <Promise<?HTTPResponse>> Promise, который разрешается ответом основного ресурса. В случае множественных редиректов, навигация разрешается ответом последнего редиректа. Если невозможно вернуться назад, разрешается null.

Переход на предыдущую страницу в истории.

page.goForward([options])

options <Объект> Параметры навигации, которые могут содержать следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд. Передайте 0 чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Переданный массив строк событий, навигация считается успешной после срабатывания всех событий. События могут быть следующими:
  - load - считать навигацию завершенной, когда срабатывает событие load.
  - domcontentloaded - считать навигацию завершенной, когда срабатывает событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда нет более 0 сетевых соединений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда нет более 2 сетевых соединений в течение как минимум 500 мс.
возвращает: <Promise<?HTTPResponse>> Promise, который разрешается ответом основного ресурса. В случае множественных редиректов, навигация разрешается ответом последнего редиректа. Если невозможно перейти вперёд, разрешается null.

Переход на следующую страницу в истории.

page.goto(url[, options])

url <строка> URL для перехода на страницу. URL должен содержать схему, например, https://.
options <Объект> Параметры навигации, которые могут содержать следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд. Передайте 0 чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Переданный массив строк событий, навигация считается успешной после срабатывания всех событий. События могут быть следующими:
  - load - считать навигацию завершенной, когда срабатывает событие load.
  - domcontentloaded - считать навигацию завершенной, когда срабатывает событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда нет более 0 сетевых соединений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда нет более 2 сетевых соединений в течение как минимум 500 мс.
- referer <строка> Значение заголовка Referer. Если задано, оно будет иметь приоритет над значением заголовка referer, заданным методом page.setExtraHTTPHeaders().
возвращает: <Promise<?HTTPResponse>> Promise, который разрешается ответом основного ресурса. В случае множественных редиректов, навигация разрешается ответом последнего редиректа.

page.goto сгенерирует ошибку в следующих случаях:

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

page.goto не генерирует ошибку при получении любого допустимого HTTP статуса от удаленного сервера, включая 404 «Not Found» и 500 «Internal Server Error». Статус ответа можно получить, вызвав response.status().

ПРИМЕЧАНИЕ page.goto либо генерирует ошибку, либо возвращает ответ основного ресурса. Исключение составляют навигация на about:blank или навигация по тому же URL с другим хэшем, которые пройдут успешно и вернут null.

ПРИМЕЧАНИЕ В режиме без графического интерфейса не поддерживается навигация к документу PDF. См. исходную проблему.

Сокращение для page.mainFrame().goto(url, options)

page.hover(selector)

selector <строка> Селектор для поиска элемента, на который нужно навесить указатель мыши. Если селектору удовлетворяют несколько элементов, будет наведён указатель на первый.
возвращает: <Promise> Promise, который разрешается, когда элемент, соответствующий selector, успешно получает фокус. Promise отклоняется, если нет элемента, соответствующего selector.

Этот метод получает элемент по selector, скролит его в область видимости при необходимости и затем использует page.mouse для наведения указателя на центр элемента. Если соответствующего элемента нет, метод генерирует ошибку.

Сокращение для page.mainFrame().hover(selector).

page.isClosed()

возвращает: <булево>

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

page.isJavaScriptEnabled()

возвращает: <булево>

Возвращает true если на странице включён JavaScript, false в противном случае.

END_OF_DOCUMENT_MARKER

page.keyboard

возвращает: <Клавиатура>

page.mainFrame()

возвращает: <Фрейм> Главный фрейм страницы.

У страницы гарантированно есть главный фрейм, который сохраняется при навигации.

page.metrics()

возвращает: <Promise<Объект>> Объект, содержащий метрики в виде пар ключ/значение.
- Timestamp <число> Отметка времени, когда были взяты метрики.
- Documents <число> Количество документов на странице.
- Frames <число> Количество фреймов на странице.
- JSEventListeners <число> Количество событий на странице.
- Nodes <число> Количество узлов DOM на странице.
- LayoutCount <число> Общее количество полных или частичных макетов страницы.
- RecalcStyleCount <число> Общее количество перерасчетов стилей страницы.
- LayoutDuration <число> Объединённое время всех макетов страницы.
- RecalcStyleDuration <число> Объединённое время всех перерасчётов стилей страницы.
- ScriptDuration <число> Объединённое время выполнения JavaScript.
- TaskDuration <число> Объединённое время выполнения всех задач браузера.
- JSHeapUsedSize <число> Занятый размер кучи JavaScript.
- JSHeapTotalSize <число> Общий размер кучи JavaScript.

ПРИМЕЧАНИЕ Все отметки времени указаны в монотонном времени: монотонно возрастающее время в секундах с произвольной точки прошлого.

page.mouse

возвращает: <Мышь>

page.pdf([options])

options <Объект> Объект параметров, который может содержать следующие свойства:
- path <строка> Путь к файлу, в который будет сохранён PDF. Если path — это относительный путь, то он разрешается относительно текущей рабочей директории. Если путь не указан, PDF не будет сохранён на диск.
- scale <число> Масштаб отображения веб-страницы. По умолчанию 1. Значение масштаба должно быть между 0,1 и 2.
- displayHeaderFooter <логическое значение> Отображать заголовок и подвал. По умолчанию false.
- headerTemplate <строка> HTML-шаблон для печатного заголовка. Должен содержать корректный HTML-разметку с использованием следующих классов для вставки значений печати:
  - date отформатированная дата печати
  - title заголовок документа
  - url местоположение документа
  - pageNumber номер текущей страницы
  - totalPages общее количество страниц в документе
- footerTemplate <строка> HTML-шаблон для печатного подвала. Должен использовать тот же формат, что и headerTemplate.
- printBackground <логическое значение> Печать фоновых графических элементов. По умолчанию false.
- landscape <логическое значение> Ориентация бумаги. По умолчанию false.
- pageRanges <строка> Диапазоны страниц для печати, например, '1-5, 8, 11-13'. По умолчанию пустая строка, что означает печать всех страниц.
- format <строка> Формат бумаги. Если задано, имеет приоритет над width или height опциями. По умолчанию 'Letter'.
- width <строка|число> Ширина бумаги, принимает значения с единицами измерения.
- height <строка|число> Высота бумаги, принимает значения с единицами измерения.
- margin <Объект> Поля бумаги, по умолчанию отсутствуют.
  - top <строка|число> Верхнее поле, принимает значения с единицами измерения.
  - right <строка|число> Правое поле, принимает значения с единицами измерения.
  - bottom <строка|число> Нижнее поле, принимает значения с единицами измерения.
  - left <строка|число> Левое поле, принимает значения с единицами измерения.
- preferCSSPageSize <логическое значение> Приоритет любых размеров CSS @page, объявленных на странице, над заданными в width и height или format опциях. По умолчанию false, что приведет к масштабированию содержимого для подгонки под размер бумаги.
возвращает: <Promise<Буфер>> Promise, который разрешается буфером PDF.

ПРИМЕЧАНИЕ Генерация PDF в настоящее время поддерживается только в Chrome headless.

page.pdf() генерирует PDF страницы с print CSS-средой. Чтобы сгенерировать PDF с screen средой, вызовите page.emulateMediaType('screen') перед вызовом page.pdf():

ПРИМЕЧАНИЕ По умолчанию page.pdf() генерирует PDF с изменёнными цветами для печати. Используйте свойство -webkit-print-color-adjust для принудительного рендеринга точных цветов.

// Generates a PDF with 'screen' media type.
await page.emulateMediaType('screen');
await page.pdf({path: 'page.pdf'});

Опции width, height, и margin принимают значения с единицами измерения. Значения без единиц измерения обрабатываются как пиксели.

Несколько примеров:

page.pdf({width: 100}) - печать с шириной 100 пикселей
page.pdf({width: '100px'}) - печать с шириной 100 пикселей
page.pdf({width: '10cm'}) - печать с шириной 10 сантиметров.

Все возможные единицы измерения:

px - пиксель
in - дюйм
cm - сантиметр
mm - миллиметр

Опции format:

Letter: 8.5in x 11in
Legal: 8.5in x 14in
Tabloid: 11in x 17in
Ledger: 17in x 11in
A0: 33.1in x 46.8in
A1: 23.4in x 33.1in
A2: 16.54in x 23.4in
A3: 11.7in x 16.54in
A4: 8.27in x 11.7in
A5: 5.83in x 8.27in
A6: 4.13in x 5.83in

ПРИМЕЧАНИЕ headerTemplate и footerTemplate разметки имеют следующие ограничения:

Теги script внутри шаблонов не обрабатываются.

Стили страницы не видны внутри шаблонов.

page.queryObjects(prototypeHandle)

prototypeHandle <JSHandle> Дверан к объекту-прототипу.
returns: <Promise<JSHandle>> Обещание, которое разрешается в ссылку на массив объектов с этим прототипом.

Метод итерирует кучу JavaScript и находит все объекты с заданным прототипом.

// Create a Map object
await page.evaluate(() => window.map = new Map());
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();

Сокращение для page.mainFrame().executionContext().queryObjects(prototypeHandle).

page.reload([options])

options <Объект> Параметры навигации, которые могут содержать следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд, передать 0 для отключения таймаута. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Если задан массив строк событий, навигация считается успешной после того, как все события будут вызваны. События могут быть:
  - load - считать навигацию завершенной, когда будет вызвано событие load.
  - domcontentloaded - считать навигацию завершенной, когда будет вызвано событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда не более 0 сетевых подключений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда не более 2 сетевых подключений в течение как минимум 500 мс.
returns: <Promise<HTTPResponse>> Обещание, которое разрешается в ответ на основной ресурс. В случае многократных редиректов навигация разрешится ответом последнего редиректа.

page.screenshot([options])

options <Объект> Объект опций, который может содержать следующие свойства:
- path <строка> Путь к файлу для сохранения изображения. Тип скриншота будет определен по расширению файла. Если path — это относительный путь, то он разрешается относительно текущего рабочего каталога. Если путь не указан, изображение не будет сохранено на диск.
- type <строка> Укажите тип скриншота, может быть либо jpeg или png. По умолчанию 'png'.
- quality <число> Качество изображения, от 0 до 100. Не применимо к изображениям png.
- fullPage <логическое значение> Если true, делает снимок всего прокручиваемой страницы. По умолчанию false.
- clip <Объект> Объект, который определяет область обрезки страницы. Должен иметь следующие поля:
  - x <число> Координата x левого верхнего угла области обрезки
  - y <число> Координата y левого верхнего угла области обрезки
  - width <число> Ширина области обрезки
  - height <число> Высота области обрезки
- omitBackground <логическое значение> Скрывает белый фон по умолчанию и позволяет делать снимки экрана с прозрачностью. По умолчанию false.
- encoding <строка> Кодировка изображения, может быть либо base64 или binary. По умолчанию binary.
returns: <Promise<строка|Буфер>> Обещание, которое разрешается в буфер или строку base64 (в зависимости от значения encoding) со сделанным снимком экрана.

ПРИМЕЧАНИЕ Снимки экрана занимают как минимум 1/6 секунды на OS X. См. https://crbug.com/741689 для обсуждения.

page.select(selector, ...values)

selector <строка> Селектор для запроса страницы
...values <...строка> Значения опций для выбора. Если у <select> есть атрибут multiple, все значения учитываются, в противном случае учитывается только первое.
returns: <Promise<Массив<строка>>> Массив значений опций, которые были успешно выбраны.

Вызывает событие change и input один раз после того, как все предоставленные опции будут выбраны. Если нет элемента <select> , соответствующего selector, метод выбросит ошибку.

page.select('select#colors', 'blue'); // single selection
page.select('select#colors', 'red', 'green', 'blue'); // multiple selections

Сокращение для page.mainFrame().select()

page.setBypassCSP(enabled)

enabled <логическое значение> Устанавливает обход политики Content-Security-Policy страницы.
returns: <Promise>

Включает или отключает обход политики Content-Security-Policy страницы.

ПРИМЕЧАНИЕ Обход CSP происходит в момент инициализации CSP, а не оценки. Обычно это означает, что page.setBypassCSP необходимо вызвать перед переходом на домен.

page.setCacheEnabled([enabled])

enabled <логическое значение> устанавливает состояние кэша.
returns: <Promise>

Включает или отключает игнорирование кэша для каждого запроса в зависимости от состояния enabled. По умолчанию кэширование включено.

page.setContent(html[, options])

html <строка> Разметка HTML, которая должна быть назначена странице.
options <Объект> Параметры, которые могут содержать следующие свойства:
- timeout <число> Максимальное время загрузки ресурсов в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить с помощью методов page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать разметку успешно загруженной, по умолчанию load. Если передан массив строк событий, разметка считается загруженной, после того как будут сгенерированы все события. События могут быть следующими:
  - load - считать разметку загруженной, когда сгенерировано событие load.
  - domcontentloaded - считать разметку загруженной, когда сгенерировано событие DOMContentLoaded.
  - networkidle0 - считать разметку загруженной, когда нет более чем 0 сетевых подключений в течение как минимум 500 мс.
  - networkidle2 - считать разметку загруженной, когда нет более чем 2 сетевых подключений в течение как минимум 500 мс.
Возвращает: <Promise>

page.setCookie(...cookies)

...cookies <...Объект>
- name <строка> обязательно
- value <строка> обязательно
- url <строка>
- domain <строка>
- path <строка>
- expires <число> Время в формате Unix (секунды).
- httpOnly <булево>
- secure <булево>
- sameSite <"Strict"|"Lax">
Возвращает: <Promise>

await page.setCookie(cookieObject1, cookieObject2);

page.setDefaultNavigationTimeout(timeout)

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

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

page.goBack([options])
page.goForward([options])
page.goto(url[, options])
page.reload([options])
page.setContent(html[, options])
page.waitForNavigation([options])

ПРИМЕЧАНИЕ page.setDefaultNavigationTimeout имеет приоритет над page.setDefaultTimeout

page.setDefaultTimeout(timeout)

timeout <число> Максимальное время в миллисекундах

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

page.goBack([options])
page.goForward([options])
page.goto(url[, options])
page.reload([options])
page.setContent(html[, options])
page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
page.waitForFileChooser([options])
page.waitForFunction(pageFunction[, options[, ...args]])
page.waitForNavigation([options])
page.waitForRequest(urlOrPredicate[, options])
page.waitForResponse(urlOrPredicate[, options])
page.waitForSelector(selector[, options])
page.waitForXPath(xpath[, options])

ПРИМЕЧАНИЕ page.setDefaultNavigationTimeout имеет приоритет над page.setDefaultTimeout

page.setExtraHTTPHeaders(headers)

headers <Объект> Объект, содержащий дополнительные HTTP-заголовки, которые будут отправляться с каждым запросом. Все значения заголовков должны быть строками.
Возвращает: <Promise>

Дополнительные HTTP-заголовки будут отправляться с каждым запросом, инициируемым страницей.

ПРИМЕЧАНИЕ page.setExtraHTTPHeaders не гарантирует порядок заголовков в исходящих запросах.

page.setGeolocation(options)

options <GeolocationOptions>
Возвращает: <Promise>

Устанавливает геолокацию страницы.

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

ПРИМЕЧАНИЕ Рассмотрите возможность использования browserContext.overridePermissions для предоставления разрешений странице на чтение ее геолокации.

page.setJavaScriptEnabled(enabled)

enabled <булево> Включить или выключить JavaScript на странице.
Возвращает: <Promise>

ПРИМЕЧАНИЕ изменение этого значения не повлияет на скрипты, которые уже были запущены. Оно будет полностью действовать при следующей навигации.

page.setOfflineMode(enabled)

enabled <булево> Если true, включить режим офлайн для страницы.
Возвращает: <Promise>

page.setRequestInterception(value)

value <булево> Включить перехват запросов.
Возвращает: <Promise>

Включение перехвата запросов позволяет использовать методы request.abort, request.continue и request.respond. Это предоставляет возможность модифицировать сетевые запросы, выполняемые страницей.

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

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setRequestInterception(true);
  page.on('request', interceptedRequest => {
    if (interceptedRequest.url().endsWith('.png') || interceptedRequest.url().endsWith('.jpg'))
      interceptedRequest.abort();
    else
      interceptedRequest.continue();
  });
  await page.goto('https://example.com');
  await browser.close();
})();

ПРИМЕЧАНИЕ Включение перехвата запросов отключает кеширование страницы.

page.setUserAgent(userAgent)

userAgent <строка> Конкретный пользовательский агент, который необходимо использовать на этой странице
Возвращает: <Promise> Promise, который разрешается, когда пользовательский агент установлен.

page.setViewport(viewport)

viewport <Object>
- width <число> Ширина страницы в пикселях. обязательно
- height <число> Высота страницы в пикселях. обязательно
- deviceScaleFactor <число> Укажите коэффициент масштабирования устройства (можно рассматривать как dpr). По умолчанию 1.
- isMobile <логическое> Учитывается ли тег meta viewport. По умолчанию false.
- hasTouch<логическое> Указывает, поддерживает ли viewport события касания. По умолчанию false
- isLandscape <логическое> Указывает, находится ли viewport в альбомной ориентации. По умолчанию false.
возвращает: <Promise>

ПРИМЕЧАНИЕ в некоторых случаях установка viewport приведет к перезагрузке страницы, чтобы установить свойства isMobile или hasTouch.

В случае нескольких страниц в одном браузере каждая страница может иметь свой размер viewport.

page.setViewport будет изменять размер страницы. Многие веб-сайты не ожидают изменения размера телефонов, поэтому вы должны установить viewport перед переходом на страницу.

const page = await browser.newPage();
await page.setViewport({
  width: 640,
  height: 480,
  deviceScaleFactor: 1,
});
await page.goto('https://example.com');

page.tap(selector)

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

Этот метод получает элемент с selector, прокручивает его в область видимости при необходимости и затем использует page.touchscreen для нажатия в центре элемента. Если нет элемента, соответствующего selector, метод генерирует ошибку.

Сокращение для page.mainFrame().tap(selector).

page.target()

возвращает: <Target> целевой объект, из которого была создана эта страница.

page.title()

возвращает: <Promise<строка>> Заголовок страницы.

Сокращение для page.mainFrame().title().

page.touchscreen

возвращает: <Touchscreen>

page.tracing

возвращает: <Tracing>

page.type(selector, text[, options])

selector <строка> Селектор элемента, в который нужно ввести текст. Если существует несколько элементов, удовлетворяющих селектору, используется первый.
text <строка> Текст для ввода в сфокусированный элемент.
options <Объект>
- delay <число> Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Отправляет событие keydown, keypress/input, и keyup для каждого символа в тексте.

Чтобы нажать специальную клавишу, например, Control или ArrowDown, используйте keyboard.press.

await page.type('#mytextarea', 'Hello'); // Types instantly
await page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user

Сокращение для page.mainFrame().type(selector, text[, options]).

page.url()

возвращает: <строка>

Это сокращение для page.mainFrame().url()

page.viewport()

возвращает: <?Объект>
- width <число> ширина страницы в пикселях.
- height <число> высота страницы в пикселях.
- deviceScaleFactor <число> Укажите коэффициент масштабирования устройства (аналогично dpr). По умолчанию 1.
- isMobile <логическое> Учитывается ли тег meta viewport. По умолчанию false.
- hasTouch<логическое> Указывает, поддерживает ли viewport события касания. По умолчанию false
- isLandscape <логическое> Указывает, находится ли viewport в альбомной ориентации. По умолчанию false.

page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])

selectorOrFunctionOrTimeout <строка|число|функция> Селектор, предикат или таймаут ожидания
options <Объект> Дополнительные параметры ожидания
- visible <логическое> ожидать, чтобы элемент был присутствующим в DOM и видимым. По умолчанию false.
- timeout <число> максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0 для отключения таймаута. Значение по умолчанию можно изменить с помощью метода page.setDefaultTimeout(timeout).
- hidden <логическое> ожидать, чтобы элемент не был найден в DOM или был скрыт. По умолчанию false.
- polling <строка|число> Интервал, с которым выполняется pageFunction, по умолчанию raf. Если polling является числом, то оно рассматривается как интервал в миллисекундах, с которым будет выполняться функция. Если polling является строкой, то она может иметь следующие значения:
  - raf - для постоянного выполнения pageFunction в requestAnimationFrame обратном вызове. Это самый строгий режим опроса, подходящий для наблюдения за изменениями стиля.
  - mutation - для выполнения pageFunction при каждой мутации DOM.
...args <...Сериализуемый|JSHandle> Аргументы для передачи в pageFunction
возвращает: <Promise<JSHandle>> Promise, который разрешается JSHandle успешного значения

Этот метод устарел. Вы должны использовать более явные API-методы:

page.waitForSelector
page.waitForXPath
page.waitForFunction
page.waitForTimeout

Этот метод ведет себя по-разному в зависимости от типа первого параметра:

Если selectorOrFunctionOrTimeout является string, то первый аргумент обрабатывается как селектор или xpath, в зависимости от того, начинается ли он с '//', а метод является сокращением для page.waitForSelector или page.waitForXPath
Если selectorOrFunctionOrTimeout является function, то первый аргумент обрабатывается как предикат для ожидания, а метод является сокращением для page.waitForFunction().
Если selectorOrFunctionOrTimeout является number, то первый аргумент обрабатывается как таймаут в миллисекундах, а метод возвращает промис, который разрешается после таймаута
В противном случае выбрасывается исключение

// wait for selector
await page.waitFor('.foo');
// wait for 1 second
await page.waitFor(1000);
// wait for predicate
await page.waitFor(() => !!document.querySelector('.foo'));

Для передачи аргументов из node.js в предикат функции page.waitFor:

const selector = '.foo';
await page.waitFor(selector => !!document.querySelector(selector), {}, selector);

Сокращение для page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]]).

page.waitForFileChooser([options])

options <WaitTimeoutOptions> Дополнительные параметры ожидания
возвращает: <Promise<FileChooser>> Промис, который разрешается после того, как страница запросит диалог выбора файла.

ПРИМЕЧАНИЕ В браузере Chromium без режима без графического интерфейса этот метод приводит к тому, что системный диалог выбора файла не отображается пользователю.

Этот метод обычно используется в паре с действием, которое вызывает выбор файла. В следующем примере нажимается кнопка, которая открывает диалог выбора файла, и затем возвращается /tmp/myfile.pdf так, как если бы пользователь выбрал этот файл.

const [fileChooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('#upload-file-button'), // some button that triggers file selection
]);
await fileChooser.accept(['/tmp/myfile.pdf']);

ПРИМЕЧАНИЕ Этот метод должен быть вызван до открытия диалога выбора файла. Он не вернёт текущий активный диалог выбора файла.

page.waitForFunction(pageFunction[, options[, ...args]])

pageFunction <функция|строка> Функция, которая будет выполняться в контексте браузера
options <Объект> Дополнительные параметры ожидания
- polling <строка|число> Интервал, с которым выполняется pageFunction, по умолчанию raf. Если polling является числом, то оно обрабатывается как интервал в миллисекундах, с которым будет выполняться функция. Если polling является строкой, то она может принимать следующие значения:
  - raf - постоянно выполнять pageFunction в requestAnimationFrame коллбэке. Это самый строгий режим опроса, который подходит для наблюдения за изменениями стилей.
  - mutation - выполнять pageFunction при каждой мутации DOM.
- timeout <число> максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
...args <...Сериализуемые|JSHandle> Аргументы для передачи функции pageFunction
возвращает: <Promise<JSHandle>> Промис, который разрешается, когда pageFunction возвращает истинное значение. Он разрешается до JSHandle истинного значения.

Функция waitForFunction может использоваться для наблюдения за изменениями размера viewport:

const puppeteer = require('puppeteer');

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

Для передачи аргументов из node.js в предикат функции page.waitForFunction:

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

Предикат функции page.waitForFunction также может быть асинхронным:

const username = 'github-username';
await page.waitForFunction(async username => {
  const githubResponse = await fetch(`https://api.github.com/users/${username}`);
  const githubUser = await githubResponse.json();
  // show the avatar
  const img = document.createElement('img');
  img.src = githubUser.avatar_url;
  // wait 3 seconds
  await new Promise((resolve, reject) => setTimeout(resolve, 3000));
  img.remove();
}, {}, username);

Сокращение для page.mainFrame().waitForFunction(pageFunction[, options[, ...args]]).

page.waitForNavigation([options])

options <Объект> Параметры навигации, которые могут иметь следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Если задан массив строк событий, навигация считается успешной после того, как будут вызваны все события. События могут быть:
  - load - считать навигацию завершенной, когда будет вызвано событие load.
  - domcontentloaded - считать навигацию завершенной, когда будет вызвано событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда нет более 0 сетевых подключений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда нет более 2 сетевых подключений в течение как минимум 500 мс.
возвращает: <Promise<?HTTPResponse>> Промис, который разрешается до ответа основного ресурса. В случае множественных переадресаций навигация будет разрешаться с ответом последней переадресации. В случае навигации к другому якорю или навигации из-за использования API истории навигация разрешится с null.

Разрешается при переходе страницы на новый URL или перезагрузке. Полезно, когда вы выполняете код, который косвенно приведет к переходу на другую страницу. Рассмотрим этот пример:

const [response] = await Promise.all([
  page.waitForNavigation(), // The promise resolves after navigation has finished
  page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
]);

ПРИМЕЧАНИЕ Использование API истории для изменения URL считается навигацией.

Сокращение для page.mainFrame().waitForNavigation(options).

page.waitForRequest(urlOrPredicate[, options])

urlOrPredicate <строка|Функция> URL или предикат для ожидания.
options <Объект> Дополнительные параметры ожидания
- timeout <число> Максимальное время ожидания в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
возвращает: <Promise<HTTPRequest>> Промис, который разрешается до соответствующего запроса.

const firstRequest = await page.waitForRequest('http://example.com/resource');
const finalRequest = await page.waitForRequest(request => request.url() === 'http://example.com' && request.method() === 'GET');
return firstRequest.url();

page.waitForResponse(urlOrPredicate[, options])

urlOrPredicate <строка|Функция> URL или предикат для ожидания.
options <Объект> Дополнительные параметры ожидания
- timeout <число> Максимальное время ожидания в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
возвращает: <Promise<HTTPResponse>> Промис, который разрешается до соответствующего ответа.

const firstResponse = await page.waitForResponse('https://example.com/resource');
const finalResponse = await page.waitForResponse(response => response.url() === 'https://example.com' && response.status() === 200);
const finalResponse = await page.waitForResponse(async response => { return (await response.text()).includes('<html>') })
return finalResponse.ok();

page.waitForSelector(selector[, options])

selector <string> Выбираемый селектор элемента, ожидание которого требуется
options <Объект> Необязательные параметры ожидания
- visible <boolean> Ожидать, чтобы элемент был присутствующим в DOM и видимым, т.е. не имел свойств CSS display: none или visibility: hidden. По умолчанию false.
- hidden <boolean> Ожидать, чтобы элемент не был найден в DOM или был скрытым, т.е. имел свойства CSS display: none или visibility: hidden. По умолчанию false.
- timeout <число> Максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
возвращает: <Promise<?ElementHandle>> Promise, который разрешается, когда элемент, указанный строкой селектора, добавлен в DOM. Разрешается в null в случае ожидания hidden: true и селектор не найден в DOM.

Ожидание появления selector на странице. Если в момент вызова метода selector уже существует, метод вернётся сразу. Если селектор не появится после timeout миллисекунд ожидания, функция выбросит исключение.

Этот метод работает через переходы:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page
    .waitForSelector('img')
    .then(() => console.log('First URL with image: ' + currentURL));
  for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
  }
  await browser.close();
})();

Сокращение для page.mainFrame().waitForSelector(selector[, options]).

page.waitForTimeout(milliseconds)

milliseconds <число> Количество миллисекунд ожидания.
возвращает: <Promise> Promise, который разрешается после завершения таймаута.

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

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  page.waitForTimeout(1000)
    .then(() => console.log('Waited a second!'));

  await browser.close();
})();

page.waitForXPath(xpath[, options])

xpath <строка> XPath элемента, ожидание которого требуется
options <Объект> Необязательные параметры ожидания
- visible <boolean> Ожидать, чтобы элемент был присутствующим в DOM и видимым, т.е. не имел свойств CSS display: none или visibility: hidden. По умолчанию false.
- hidden <boolean> Ожидать, чтобы элемент не был найден в DOM или был скрытым, т.е. имел свойства CSS display: none или visibility: hidden. По умолчанию false.
- timeout <число> Максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
возвращает: <Promise<?ElementHandle>> Promise, который разрешается, когда элемент, указанный строкой XPath, добавлен в DOM. Разрешается в null в случае ожидания hidden: true и XPath не найден в DOM.

Ожидание появления xpath на странице. Если в момент вызова метода xpath уже существует, метод вернётся сразу. Если XPath не появится после timeout миллисекунд ожидания, функция выбросит исключение.

Этот метод работает через переходы:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page
    .waitForXPath('//img')
    .then(() => console.log('First URL with image: ' + currentURL));
  for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
  }
  await browser.close();
})();

Сокращение для page.mainFrame().waitForXPath(xpath[, options]).

page.workers()

возвращает: <Массив<WebWorker>> Этот метод возвращает все выделенные WebWorker, связанные со страницей.

ПРИМЕЧАНИЕ Это не включает ServiceWorkers

GeolocationOptions

latitude <число> Широта от -90 до 90.
longitude <число> Долгота от -180 до 180.
accuracy <число> Необязательное неотрицательное значение точности.

WaitTimeoutOptions

timeout <число> Максимальное время ожидания в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).

класс: WebWorker

Класс WebWorker представляет WebWorker. События workercreated и workerdestroyed генерируются на объекте страницы, чтобы сигнализировать о жизненном цикле работника.

page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));

console.log('Current workers:');
for (const worker of page.workers())
  console.log('  ' + worker.url());

webWorker.evaluate(pageFunction[, ...args])

pageFunction <функция|строка> Функция, которая должна быть вычислена в контексте работника
...args <...сериализуемый|JSHandle> Аргументы, передаваемые в pageFunction
возвращает: <Promise<сериализуемый>> Promise, который разрешается с возвращаемым значением pageFunction

Если функция, переданная в worker.evaluate возвращает Promise, то worker.evaluate будет ожидать разрешения обещания и вернет его значение.

Если функция, переданная в worker.evaluate возвращает не сериализуемое значение, то worker.evaluate разрешается в undefined. Протокол DevTools также поддерживает передачу некоторых дополнительных значений, которые не сериализуются с помощью JSON: -0, NaN, Infinity, -Infinity, и литералы bigint.

Сокращение для (await worker.executionContext()).evaluate(pageFunction, ...args).

webWorker.evaluateHandle(pageFunction[, ...args])

pageFunction <функция|строка> Функция, которая должна быть вычислена в контексте страницы
...args <...сериализуемый|JSHandle> Аргументы, передаваемые в pageFunction
возвращает: <Promise<JSHandle|ElementHandle>> Promise, который разрешается с возвращаемым значением pageFunction как объектом на странице.

Единственное отличие между worker.evaluate и worker.evaluateHandle заключается в том, что worker.evaluateHandle возвращает объект на странице (JSHandle).

Если функция, переданная в worker.evaluateHandle возвращает Promise, то worker.evaluateHandle будет ожидать разрешения обещания и вернёт его значение.

Если функция возвращает элемент, возвращаемый обработчик является ElementHandle.

Сокращение для (await worker.executionContext()).evaluateHandle(pageFunction, ...args).

webWorker.executionContext()

returns: <Promise<ExecutionContext>>

webWorker.url()

returns: <строка>

class: Accessibility

Класс Accessibility предоставляет методы для проверки дерева доступности Chromium. Дерево доступности используется технологиями вспомогательного доступа, такими как скринридеры или переключатели.

Доступность — это очень платформа-специфичная вещь. На разных платформах могут использоваться различные скринридеры, которые могут иметь совершенно разные выводы.

Blink — движок рендеринга Chrome — имеет концепцию «дерева доступности», которая затем переводится в различные платформенно-специфичные API. Пространство имён Accessibility предоставляет пользователям доступ к дереву доступности Blink.

Большая часть дерева доступности отфильтровывается при преобразовании из Blink AX Tree в платформенно-специфическое AX-Tree или самими технологиями вспомогательного доступа. По умолчанию Puppeteer пытается приблизительно воспроизвести эту фильтрацию, отображая только «интересные» узлы дерева.

accessibility.snapshot([options])

options <Объект>
- interestingOnly <логическое значение> Удалять неинтересные узлы из дерева. По умолчанию true.
- root <ElementHandle> Корневой элемент DOM для снимка. По умолчанию вся страница.
returns: <Promise<Объект>> Объект AXNode со следующими свойствами:
- role <строка> Роль.
- name <строка> Читаемое человеком имя узла.
- value <строка|число> Текущее значение узла.
- description <строка> Дополнительное описание узла, читаемое человеком.
- keyshortcuts <строка> Кнопки быстрого доступа, связанные с этим узлом.
- roledescription <строка> Читаемое человеком альтернативное значение роли.
- valuetext <строка> Описание текущего значения.
- disabled <логическое значение> Является ли узел отключенным.
- expanded <логическое значение> Является ли узел развернутым или свёрнутым.
- focused <логическое значение> Является ли узел сфокусированным.
- modal <логическое значение> Является ли узел модальным.
- multiline <логическое значение> Поддерживает ли поле ввода текста несколько строк.
- multiselectable <логическое значение> Может ли быть выбрано более одного дочернего элемента.
- readonly <логическое значение> Является ли узел только для чтения.
- required <логическое значение> Является ли узел обязательным.
- selected <логическое значение> Выбран ли узел в его родительском узле.
- checked <логическое значение|"смешанное"> Является ли флажок отмеченным или "смешанное".
- pressed <логическое значение|"смешанное"> Является ли переключатель отмеченным или "смешанное".
- level <число> Уровень заголовка.
- valuemin <число> Минимальное значение в узле.
- valuemax <число> Максимальное значение в узле.
- autocomplete <строка> Какой тип автозаполнения поддерживает элемент управления.
- haspopup <строка> Какой тип всплывающего окна в данный момент отображается для узла.
- orientation <строка> Горизонтальное или вертикальное направление узла.
- children <Массив<Объектов>> Дочерние узлы AXNode этого узла, если таковые имеются.

Захватывает текущее состояние дерева доступности. Возвращаемый объект представляет корневой доступный узел страницы.

ПРИМЕЧАНИЕ Дерево доступности Chromium содержит узлы, которые не используются на большинстве платформ и большинством скринридеров. Puppeteer также будет их отбрасывать для более простого дерева, если interestingOnly не установлено в значение false.

Пример вывода всего дерева доступности:

const snapshot = await page.accessibility.snapshot();
console.log(snapshot);

Пример вывода имени сфокусированного узла:

const snapshot = await page.accessibility.snapshot();
const node = findFocusedNode(snapshot);
console.log(node && node.name);

function findFocusedNode(node) {
  if (node.focused)
    return node;
  for (const child of node.children || []) {
    const foundNode = findFocusedNode(child);
    return foundNode;
  }
  return null;
}

class: Keyboard

Keyboard предоставляет API для управления виртуальной клавиатурой. Основной API — keyboard.type, который принимает необработанные символы и генерирует правильные события keydown, keypress/input и keyup на вашей странице.

Для более точного управления вы можете использовать keyboard.down, keyboard.up и keyboard.sendCharacter для ручного создания событий, как если бы они были сгенерированы реальной клавиатурой.

Пример удержания Shift для выбора и удаления текста:

await page.keyboard.type('Hello World!');
await page.keyboard.press('ArrowLeft');

await page.keyboard.down('Shift');
for (let i = 0; i < ' World'.length; i++)
  await page.keyboard.press('ArrowLeft');
await page.keyboard.up('Shift');

await page.keyboard.press('Backspace');
// Result text will end up saying 'Hello!'

Пример нажатия A

await page.keyboard.down('Shift');
await page.keyboard.press('KeyA');
await page.keyboard.up('Shift');

ПРИМЕЧАНИЕ В MacOS сочетания клавиш, такие как ⌘ A —> Выделить всё, не работают. См. #1313

keyboard.down(key[, options])

key <строка> Название клавиши для нажатия, например ArrowLeft. Список всех названий клавиш см. в USKeyboardLayout.
options <Объект>
- text <строка> Если указано, генерирует событие input с этим текстом.
returns: <Promise>

Отправляет событие keydown.

Если key — это одиночный символ, и никакие модификаторы, кроме Shift, не удерживаются, то также генерируется событие keypress/input. Опция text может быть указана для принудительной генерации события input.

Если key — это модификаторная клавиша, Shift, Meta, Control, или Alt, последующие нажатия клавиш будут отправляться с активным этим модификатором. Чтобы снять модификаторную клавишу, используйте keyboard.up.

После одного нажатия клавиши последующие вызовы keyboard.down будут иметь repeat установленным в значение true. Чтобы снять клавишу, используйте keyboard.up.

ПРИМЕЧАНИЕ Модификаторные клавиши ВЛИЯЮТ на keyboard.down. Удерживание Shift будет вводить текст заглавными буквами.

keyboard.press(key[, options])

key <строка> Название клавиши для нажатия, например ArrowLeft. Список всех названий клавиш см. в USKeyboardLayout.
options <объект>
- text <строка> При указании, генерирует событие ввода с этим текстом.
- delay <число> Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Если key — это одиночный символ и не удерживаются модификаторные клавиши помимо Shift, будет также сгенерировано событие keypress/input. Опция text может быть указана для принудительного создания события ввода.

ПРИМЕЧАНИЕ Модификаторные клавиши ВЛИЯЮТ на keyboard.press. Удерживание Shift будет вводить текст заглавными буквами.

Сокращение для keyboard.down и keyboard.up.

keyboard.sendCharacter(char)

char <строка> Символ, который нужно отправить на страницу.
возвращает: <Promise>

Отправляет событие keypress и input. Это не отправляет события keydown или %%%CODE_BLOCK_1027%%.

page.keyboard.sendCharacter('嗨');

ПРИМЕЧАНИЕ Модификаторные клавиши НЕ ВЛИЯЮТ на keyboard.sendCharacter. Удерживание Shift не будет вводить текст заглавными буквами.

keyboard.type(text[, options])

text <строка> Текст для ввода в фокусированный элемент.
options <объект>
- delay <число> Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Отправляет события keydown, keypress/input, и keyup для каждого символа в тексте.

Чтобы нажать специальную клавишу, например Control или ArrowDown, используйте keyboard.press.

await page.keyboard.type('Hello'); // Types instantly
await page.keyboard.type('World', {delay: 100}); // Types slower, like a user

ПРИМЕЧАНИЕ Модификаторные клавиши НЕ ВЛИЯЮТ на keyboard.type. Удерживание Shift не будет вводить текст заглавными буквами.

keyboard.up(key)

key <строка> Название клавиши для отпускания, например ArrowLeft. Список всех названий клавиш см. в USKeyboardLayout.
возвращает: <Promise>

Отправляет событие keyup.

class: Мышь

Класс Мышь работает в пикселях CSS основного фрейма относительно верхнего левого угла области просмотра.

Каждый объект page имеет свою собственную Мышь, доступную с помощью page.mouse.

// Using ‘page.mouse’ to trace a 100x100 square.
await page.mouse.move(0, 0);
await page.mouse.down();
await page.mouse.move(0, 100);
await page.mouse.move(100, 100);
await page.mouse.move(100, 0);
await page.mouse.move(0, 0);
await page.mouse.up();

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

Например, перетаскивание и выделение текста с помощью page.mouse невозможно. Вместо этого можно использовать функциональность DocumentOrShadowRoot.getSelection(), реализованную в платформе.

Например, если вы хотите выделить все содержимое между узлами:

await page.evaluate((from, to) => {
  const selection = from.getRootNode().getSelection();
  const range = document.createRange();
  range.setStartBefore(from);
  range.setEndAfter(to);
  selection.removeAllRanges();
  selection.addRange(range);
}, fromJSHandle, toJSHandle);

Если затем вы захотите скопировать и вставить свой выделенный текст, вы можете использовать API буфера обмена:

// The clipboard api does not allow you to copy, unless the tab is focused.
await page.bringToFront();
await page.evaluate(() => {
  // Copy the selected content to the clipboard
  document.execCommand('copy');
  // Obtain the content of the clipboard as a string
  return navigator.clipboard.readText();
});

Обратите внимание, что для доступа к API буфера обмена необходимо предоставить разрешение:

await browser.defaultBrowserContext().overridePermissions('<your origin>', ['clipboard-read', 'clipboard-write']);

mouse.click(x, y[, options])

x <число>
y <число>
options <объект>
- button <"слева"|"справа"|"посередине"> По умолчанию left.
- clickCount <число> По умолчанию 1. См. UIEvent.detail.
- delay <число> Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Сокращение для mouse.move, mouse.down и mouse.up.

mouse.down([options])

options <объект>
- button <"слева"|"справа"|"посередине"> По умолчанию left.
- clickCount <число> По умолчанию 1. См. UIEvent.detail.
возвращает: <Promise>

Отправляет событие mousedown.

mouse.move(x, y[, options])

x <число>
y <число>
options <объект>
- steps <число> По умолчанию 1. Отправляет промежуточные события mousemove.
возвращает: <Promise>

Отправляет событие mousemove.

mouse.up([options])

options <объект>
- button <"слева"|"справа"|"посередине"> По умолчанию left.
- clickCount <число> По умолчанию 1. См. UIEvent.detail.
возвращает: <Promise>

Отправляет событие mouseup.

mouse.wheel([options])

options <объект>
- deltaX Значение дельты X в пикселях CSS для события прокрутки мыши (по умолчанию: 0). Положительные значения имитируют прокрутку вправо, а отрицательные — прокрутку влево.
- deltaY Значение дельты Y в пикселях CSS для события прокрутки мыши (по умолчанию: 0). Положительные значения имитируют прокрутку вниз, а отрицательные — прокрутку вверх.
возвращает: <Promise>

Отправляет событие mousewheel.

Примеры:

await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');

const elem = await page.$('div');
const boundingBox = await elem.boundingBox();
await page.mouse.move(
  boundingBox.x + boundingBox.width / 2,
  boundingBox.y + boundingBox.height / 2
);

await page.mouse.wheel({ deltaY: -100 })

class: Touchscreen

touchscreen.tap(x, y)

x <число>
y <число>
возвращает: <Promise>

Отправляет события touchstart и touchend.

class: Tracing

Можно использовать tracing.start и tracing.stop для создания файла трассировки, который можно открыть в Chrome DevTools или просмотрщике временных линий.

await page.tracing.start({path: 'trace.json'});
await page.goto('https://www.google.com');
await page.tracing.stop();

tracing.start([options])

options <объект>
- path <строка> Путь для записи файла трассировки.
- screenshots <логическое значение> включает захват скриншотов в трассировке.
- categories <массив<строк>> укажите настраиваемые категории вместо стандартных.
возвращает: <Promise>

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

tracing.stop()

возвращает: <Promise<Буфер>> Promise, который разрешается в буфер с данными трассировки.

class: FileChooser

FileChooser объекты возвращаются методом 'page.waitForFileChooser'.

Выбор файлов позволяет реагировать на запросы страницы о файле.

Пример использования FileChooser:

const [fileChooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('#upload-file-button'), // some button that triggers file selection
]);
await fileChooser.accept(['/tmp/myfile.pdf']);

ПРИМЕЧАНИЕ В браузерах одновременно может быть открыт только один выбор файла. Все выборы файлов должны быть приняты или отменены. Иначе последующие выборы файлов не появятся.

fileChooser.accept(filePaths)

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

fileChooser.cancel()

возвращает: <Promise>

Закрывает выбор файла без выбора каких-либо файлов.

fileChooser.isMultiple()

возвращает: <логическое значение> Указывает, разрешен ли множественный выбор файла.

class: Dialog

Dialog объекты отправляются страницей через событие 'dialog'.

Пример использования класса Dialog.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  page.on('dialog', async dialog => {
    console.log(dialog.message());
    await dialog.dismiss();
    await browser.close();
  });
  page.evaluate(() => alert('1'));
})();

dialog.accept([promptText])

promptText <строка> Текст для ввода в подсказке. Не оказывает никакого влияния, если тип диалогового окна не подсказка.
возвращает: <Promise> Promise, который разрешается при принятии диалогового окна.

dialog.defaultValue()

возвращает: <строка> Если диалог является подсказкой, возвращает значение по умолчанию подсказки. В противном случае возвращает пустую строку.

dialog.dismiss()

возвращает: <Promise> Promise, который разрешается при закрытии диалогового окна.

dialog.message()

возвращает: <строка> Сообщение, отображаемое в диалоговом окне.

dialog.type()

возвращает: <строка> Тип диалогового окна, может быть одним из alert, beforeunload, confirm или prompt.

class: ConsoleMessage

ConsoleMessage объекты отправляются страницей через событие 'console'.

consoleMessage.args()

возвращает: <массив<JSHandle>>

consoleMessage.location()

возвращает: <объект>
- url <строка> URL ресурса, если известен, или undefined в противном случае.
- lineNumber <число> Номер строки (с нуля) в ресурсе, если известен, или undefined в противном случае.
- columnNumber <число> Номер столбца (с нуля) в ресурсе, если известен, или undefined в противном случае.

consoleMessage.stackTrace()

возвращает: <массив<объектов>>
- url <строка> URL ресурса, если известен, или undefined в противном случае.
- lineNumber <число> Номер строки (с нуля) в ресурсе, если известен, или undefined в противном случае.
- columnNumber <число> Номер столбца (с нуля) в ресурсе, если известен, или undefined в противном случае.

consoleMessage.text()

возвращает: <строка>

consoleMessage.type()

возвращает: <строка>

Одно из следующих значений: 'log', 'debug', 'info', 'error', 'warning', 'dir', 'dirxml', 'table', 'trace', 'clear', 'startGroup', 'startGroupCollapsed', 'endGroup', 'assert', 'profile', 'profileEnd', 'count', 'timeEnd'.

class: Frame

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

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

'frameattached' - срабатывает, когда фрейм присоединяется к странице. Фрейм может быть присоединен к странице только один раз.
'framenavigated' - срабатывает, когда фрейм выполняет навигацию на другой URL.
'framedetached' - срабатывает, когда фрейм отделяется от страницы. Фрейм может быть отделен от страницы только один раз.

Пример вывода структуры фреймов:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.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 + '  ');
    }
  }
})();

Пример извлечения текста из элемента iframe:

const frame = page.frames().find(frame => frame.name() === 'myframe');
const text = await frame.$eval('.selector', element => element.textContent);
console.log(text);

frame.$(selector)

selector <string> Селектор для поиска кадра
возвращает: <Promise<?ElementHandle>> Promise, который разрешается в ElementHandle, указывающий на элемент кадра.

Метод ищет элемент в кадре по селектору. Если такого элемента нет, метод разрешается в null.

frame.$$(selector)

selector <string> Селектор для поиска элементов в кадре
возвращает: <Promise<Массив<ElementHandle>>> Promise, который разрешается в ElementHandles, указывающие на элементы в кадре.

Метод выполняет document.querySelectorAll в рамках кадра. Если ни один элемент не соответствует селектору, возвращаемое значение разрешается в [].

frame.$$eval(selector, pageFunction[, ...args])

selector <string> Селектор для поиска кадра
pageFunction <функция(Массив<Элемент>)> Функция, которая будет вычислена в контексте браузера
...args <...Сериализуемый|JSHandle> Аргументы, которые нужно передать в pageFunction
возвращает: <Promise<Сериализуемый>> Promise, который разрешается в возвращаемое значение pageFunction

Этот метод выполняет Array.from(document.querySelectorAll(selector)) в рамках кадра и передает его в качестве первого аргумента pageFunction.

Если pageFunction возвращает Promise, то frame.$$eval будет ждать, пока Promise не разрешится, и вернет его значение.

Примеры:

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

frame.$eval(selector, pageFunction[, ...args])

selector <string> Селектор для поиска кадра
pageFunction <функция(Элемент)> Функция, которая будет вычислена в контексте браузера
...args <...Сериализуемый|JSHandle> Аргументы, которые нужно передать pageFunction
возвращает: <Promise<Сериализуемый>> Promise, который разрешается в возвращаемое значение pageFunction

Этот метод выполняет document.querySelector в рамках кадра и передает его в качестве первого аргумента pageFunction. Если элемент, соответствующий selector, не найден, метод выбросит ошибку.

Если pageFunction возвращает Promise, то frame.$eval будет ждать, пока Promise не разрешится, и вернет его значение.

Примеры:

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

frame.$x(expression)

expression <строка> Выражение для оценки.
возвращает: <Promise<Массив<ElementHandle>>>

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

frame.addScriptTag(options)

options <Объект>
- url <строка> URL скрипта, который нужно добавить.
- path <строка> Путь к файлу JavaScript, который нужно вставить в кадр. Если path является относительным путем, он разрешается относительно текущей рабочей директории.
- content <строка> Исходный код JavaScript, который нужно вставить в кадр.
- type <строка> Тип скрипта. Используйте 'module', чтобы загрузить модуль Javascript ES6. См. script для получения дополнительной информации.
возвращает: <Promise<ElementHandle>>, который разрешается в добавленный тег, когда срабатывает onload скрипта или когда содержимое скрипта было вставлено в кадр.

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

frame.addStyleTag(options)

options <Объект>
- url <строка> URL тега <link>.
- path <строка> Путь к файлу CSS, который нужно вставить в кадр. Если path является относительным путем, он разрешается относительно текущей рабочей директории.
- content <строка> Исходный код CSS, который нужно вставить в кадр.
возвращает: <Promise<ElementHandle>>, который разрешается в добавленный тег, когда срабатывает onload стилизованного тега или когда содержимое CSS было вставлено в кадр.

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

frame.childFrames()

возвращает: <Массив<Frame>>

frame.click(selector[, options])

selector <строка> Селектор для поиска элемента, который нужно щелкнуть. Если селектору соответствуют несколько элементов, будет щелкнут первый.
options <Объект>
- button <"слева"|"справа"|"посередине"> По умолчанию left.
- clickCount <число> По умолчанию 1. См. UIEvent.detail.
- delay <число> Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
возвращает: <Promise> Promise, который разрешается, когда элемент, соответствующий selector, успешно щелкнут. Promise будет отклонен, если нет элемента, соответствующего selector.

Этот метод извлекает элемент с selector, прокручивает его в область видимости при необходимости и затем использует page.mouse для щелчка по центру элемента. Если нет элемента, соответствующего selector, метод генерирует ошибку.

Обратите внимание, что если click() вызывает событие навигации и существует отдельный promise page.waitForNavigation() для разрешения, у вас может возникнуть состояние гонки, которое приведет к неожиданным результатам. Правильный шаблон для нажатия и ожидания навигации следующий:

const [response] = await Promise.all([
  page.waitForNavigation(waitOptions),
  frame.click(selector, clickOptions),
]);

frame.content()

возвращает: <Promise<строка>>

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

frame.evaluate(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая выполнению в контексте браузера
...args <...сериализуемое|JSHandle> Аргументы для передачи функции pageFunction
возвращает: <Promise<сериализуемое>> Promise, который разрешается со значением, возвращаемым функцией pageFunction

Если функция, переданная в frame.evaluate, возвращает Promise, то frame.evaluate будет ждать разрешения promise и возвращать его значение.

Если функция, переданная в frame.evaluate, возвращает несериализуемое значение, то frame.evaluate разрешается со значением undefined. Протокол DevTools также поддерживает передачу некоторых дополнительных значений, которые не могут быть сериализованы с помощью JSON: -0, NaN, Infinity, -Infinity, и литералы bigint.

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

Вместо функции также может быть передана строка.

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

Экземпляры ElementHandle могут быть переданы в качестве аргументов в frame.evaluate:

const bodyHandle = await frame.$('body');
const html = await frame.evaluate(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();

frame.evaluateHandle(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая выполнению в контексте страницы
...args <...сериализуемое|JSHandle> Аргументы для передачи функции pageFunction
возвращает: <Promise<JSHandle|ElementHandle>> Promise, который разрешается до значения, возвращаемого функцией pageFunction в виде объекта страницы.

Единственное различие между frame.evaluate и frame.evaluateHandle заключается в том, что frame.evaluateHandle возвращает объект страницы (JSHandle).

Если функция, переданная в frame.evaluateHandle, возвращает Promise, то frame.evaluateHandle будет ждать разрешения promise и возвращать его значение.

Если функция возвращает элемент, возвращаемый handle является ElementHandle.

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

Вместо функции также может быть передана строка.

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 => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();

frame.executionContext()

возвращает: <Promise<ExecutionContext>>

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

frame.focus(selector)

selector <строка> Селектор элемента для фокусировки. Если селектору соответствуют несколько элементов, фокусируется первый.
возвращает: <Promise> Promise, который разрешается, когда элемент, соответствующий selector , успешно сфокусирован. Promise будет отклонен, если нет элемента, соответствующего selector.

Этот метод извлекает элемент с selector и фокусирует его. Если нет элемента, соответствующего selector, метод генерирует ошибку.

frame.goto(url[, options])

url <строка> URL для перехода в фрейм. URL должен включать схему, например https://.
options <Объект> Параметры навигации, которые могут иметь следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Если задан массив строк событий, навигация считается успешной после срабатывания всех событий. События могут быть:
  - load - считать навигацию завершённой, когда будет сгенерировано событие load.
  - domcontentloaded - считать навигацию завершённой, когда будет сгенерировано событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершённой, когда активных сетевых подключений не более 0 в течение по крайней мере 500 мс.
  - networkidle2 - считать навигацию завершённой, когда активных сетевых подключений не более 2 в течение по крайней мере 500 мс.
- referer <строка> Значение заголовка Referer. Если задано, оно будет иметь приоритет над значением заголовка referer, установленным с помощью page.setExtraHTTPHeaders().
возвращает: <Promise<?HTTPResponse>> Promise, который разрешается ответом на основной ресурс. В случае нескольких перенаправлений навигация разрешится ответом на последнее перенаправление.

frame.goto вызовет ошибку, если:

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

frame.goto не вызовет ошибку, когда удалённый сервер вернёт любой допустимый HTTP-код состояния, включая 404 "Not Found" и 500 "Internal Server Error". Код состояния таких ответов можно получить, вызвав response.status().

ПРИМЕЧАНИЕ frame.goto либо возвращает ошибку, либо ответ основного ресурса. Исключение составляют переходы на about:blank или переходы по тому же URL с другим хэшем, которые будут успешны и вернут null.

ПРИМЕЧАНИЕ Режим без графического интерфейса не поддерживает переходы к документу PDF. См. соответствующий вопрос.

frame.hover(selector)

selector <строка> Селектор для поиска элемента, на который нужно навести курсор. Если существует несколько элементов, удовлетворяющих селектору, будет наведён курсор на первый.
возвращает: <Promise> Promise, который разрешается, когда элемент, соответствующий selector, успешно наведён курсором. Promise отклоняется, если нет элемента, соответствующего selector.

Этот метод извлекает элемент с selector, прокручивает его в видимую область при необходимости и затем использует page.mouse для наведения курсора на центр элемента. Если нет элемента, соответствующего selector, метод возвращает ошибку.

frame.isDetached()

возвращает: <булево значение>

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

frame.name()

возвращает: <строка>

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

Если имя пустое, возвращает атрибут id вместо него.

ПРИМЕЧАНИЕ Это значение вычисляется один раз при создании фрейма и не будет обновляться, если атрибут изменится позже.

frame.parentFrame()

возвращает: <?Frame> Родительский фрейм, если таковой имеется. Отключенные фреймы и главные фреймы возвращают null.

frame.select(selector, ...values)

selector <строка> Селектор для запроса фрейма
...values <...строка> Значения опций для выбора. Если элемент <select> имеет атрибут multiple, учитываются все значения, в противном случае учитывается только первое.
возвращает: <Promise<массив<строка>>> Массив значений опций, которые были успешно выбраны.

Вызывает событие change и input один раз после выбора всех предоставленных опций. Если нет элемента <select> , соответствующего selector, метод возвращает ошибку.

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

frame.setContent(html[, options])

html <строка> HTML разметка для назначения странице.
options <объект> Параметры, которые могут содержать следующие свойства:
- timeout <число> Максимальное время в миллисекундах для загрузки ресурсов, по умолчанию 30 секунд, передайте 0 для отключения таймаута. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|массив> Когда считать, что разметка задана успешно, по умолчанию load. При передаче массива строк событий, установка содержимого считается успешной после того, как все события сработают. События могут быть:
  - load - считать, что установка содержимого завершена, когда срабатывает событие load.
  - domcontentloaded - считать, что установка содержимого завершена, когда срабатывает событие DOMContentLoaded.
  - networkidle0 - считать установку содержимого завершенной, когда нет более 0 сетевых подключений в течение как минимум 500 мс.
  - networkidle2 - считать установку содержимого завершенной, когда нет более 2 сетевых подключений в течение как минимум 500 мс.
возвращает: <Promise>

frame.tap(selector)

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

Этот метод извлекает элемент с selector, прокручивает его в видимую область при необходимости и затем использует page.touchscreen для нажатия в центре элемента. Если нет элемента, соответствующего selector, метод возвращает ошибку.

frame.title()

возвращает: <Promise<строка>> Заголовок страницы.

frame.type(selector, text[, options])

selector <строка> Селектор элемента, в который нужно ввести текст. Если существует несколько элементов, удовлетворяющих селектору, будет использован первый.
text <строка> Текст для ввода в фокусированный элемент.
options <объект>
- delay <число> Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Отправляет события keydown, keypress/input, и keyup для каждого символа в тексте.

Для нажатия специальной клавиши, например, Control или ArrowDown, используйте keyboard.press.

await frame.type('#mytextarea', 'Hello'); // Types instantly
await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user

frame.url()

возвращает: <строка>

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

frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])

selectorOrFunctionOrTimeout <строка|число|функция> Селектор, предикат или таймаут ожидания
options <объект> Необязательные параметры ожидания
...args <...сериализуемое|JSHandle> Аргументы для передачи в pageFunction
возвращает: <Promise<JSHandle>> Promise, который разрешается с JSHandle успешного значения

Этот метод устарел. Вы должны использовать более явные API-методы:

frame.waitForSelector
frame.waitForXPath
frame.waitForFunction
frame.waitForTimeout

Этот метод ведет себя по-разному в зависимости от типа первого параметра:

Если selectorOrFunctionOrTimeout является string, то первый аргумент обрабатывается как селектор или xpath, в зависимости от того, начинается ли он с '//', а метод является сокращением для frame.waitForSelector или frame.waitForXPath
Если selectorOrFunctionOrTimeout является function, то первый аргумент обрабатывается как предикат ожидания, а метод является сокращением для frame.waitForFunction().
Если selectorOrFunctionOrTimeout является number, то первый аргумент обрабатывается как таймаут в миллисекундах, и метод возвращает промис, который разрешается после таймаута
В противном случае генерируется исключение

// wait for selector
await page.waitFor('.foo');
// wait for 1 second
await page.waitFor(1000);
// wait for predicate
await page.waitFor(() => !!document.querySelector('.foo'));

Для передачи аргументов из node.js в предикат функции page.waitFor:

const selector = '.foo';
await page.waitFor(selector => !!document.querySelector(selector), {}, selector);

frame.waitForFunction(pageFunction[, options[, ...args]])

pageFunction <функция|строка> Функция, которая должна быть вычислена в контексте браузера
options <объект> Необязательные параметры ожидания
- polling <строка|число> Интервал, с которым выполняется pageFunction, по умолчанию raf. Если polling — число, то оно обрабатывается как интервал в миллисекундах, с которым будет выполняться функция. Если polling — строка, то она может иметь следующие значения:
  - raf - для постоянного выполнения pageFunction в requestAnimationFrame обратном вызове. Это наиболее строгий режим опроса, подходящий для наблюдения за изменениями стилей.
  - mutation - для выполнения pageFunction при каждой мутации DOM.
- timeout <число> максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
...args <...сериализуемое|JSHandle> Аргументы, передаваемые в pageFunction
возвращает: <Promise<JSHandle>> Promise, который разрешается, когда pageFunction возвращает истинное значение. Он разрешается до JSHandle истинного значения.

waitForFunction может использоваться для наблюдения за изменением размера viewport:

const puppeteer = require('puppeteer');

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

Для передачи аргументов из node.js в предикат функции page.waitForFunction:

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

frame.waitForNavigation([options])

options <объект> Параметры навигации, которые могут иметь следующие свойства:
- timeout <число> Максимальное время навигации в миллисекундах, по умолчанию 30 секунд, передайте 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы page.setDefaultNavigationTimeout(timeout) или page.setDefaultTimeout(timeout).
- waitUntil <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Массив> Когда считать навигацию успешной, по умолчанию load. Если задан массив строк событий, навигация считается успешной после срабатывания всех событий. События могут быть следующих типов:
  - load - считать навигацию завершенной, когда сработает событие load.
  - domcontentloaded - считать навигацию завершенной, когда сработает событие DOMContentLoaded.
  - networkidle0 - считать навигацию завершенной, когда не более 0 сетевых соединений в течение как минимум 500 мс.
  - networkidle2 - считать навигацию завершенной, когда не более 2 сетевых соединений в течение как минимум 500 мс.
возвращает: <Promise<?HTTPResponse>> Promise, который разрешается до ответа основного ресурса. В случае нескольких редиректов навигация разрешится ответом последнего редиректа. В случае навигации к другому якорю или навигации из-за использования History API навигация разрешится null.

Разрешается, когда фрейм переходит на новый URL. Это полезно, когда вы выполняете код, который косвенно приведет к переходу фрейма.

const [response] = await Promise.all([
  frame.waitForNavigation(), // The navigation promise resolves after navigation has finished
  frame.click('a.my-link'), // Clicking the link will indirectly cause a navigation
]);

ПРИМЕЧАНИЕ Использование History API для изменения URL считается навигацией.

frame.waitForSelector(selector[, options])

selector <строка> Селектор элемента, ожидание которого требуется
options <объект> Необязательные параметры ожидания
- visible <логическое> ожидание того, что элемент присутствует в DOM и виден, т.е. у него отсутствуют свойства CSS display: none или visibility: hidden. По умолчанию false.
- hidden <логическое> ожидание того, что элемент не найден в DOM или скрыт, т.е. у него есть свойства CSS display: none или visibility: hidden. По умолчанию false.
- timeout <число> максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя метод page.setDefaultTimeout(timeout).
возвращает: <Promise<?ElementHandle>> Promise, который разрешается, когда элемент, указанный строкой селектора, добавлен в DOM. Разрешается до null, если ожидается hidden: true, и селектор не найден в DOM.

Дождитесь появления selector на странице. Если в момент вызова метода selector уже существует, метод вернет результат немедленно. Если селектор не появится после timeout миллисекунд ожидания, функция выбросит исключение.

Этот метод работает через навигации:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page.mainFrame()
    .waitForSelector('img')
    .then(() => console.log('First URL with image: ' + currentURL));
  for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
  }
  await browser.close();
})();

frame.waitForTimeout(milliseconds)

milliseconds <число> Количество миллисекунд, которые нужно подождать.
возвращает: <Promise> Promise, который разрешается после завершения таймаута.

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

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  page.mainFrame()
    .waitForTimeout(1000)
    .then(() => console.log('Waited a second!'));

  await browser.close();
})();

frame.waitForXPath(xpath[, options])

xpath <string> Путь XPath элемента, ожидание которого необходимо
options <Объект> Необязательные параметры ожидания
- visible <boolean> Ожидание, чтобы элемент был присутствующим в DOM и видимым, т.е. не имел свойств CSS display: none или visibility: hidden. По умолчанию false.
- hidden <boolean> Ожидание, чтобы элемент не был найден в DOM или был скрыт, т.е. имел свойства CSS display: none или visibility: hidden. По умолчанию false.
- timeout <число> Максимальное время ожидания в миллисекундах. По умолчанию 30000 (30 секунд). Передача 0 для отключения таймаута. Значение по умолчанию может быть изменено с помощью метода page.setDefaultTimeout(timeout).
возвращает: <Promise<?ElementHandle>> Promise, который разрешается, когда элемент, указанный строкой XPath, добавлен в DOM. Разрешается в значение null , если ожидается hidden: true и XPath не найден в DOM.

Ожидание появления xpath на странице. Если в момент вызова метода xpath уже существует, метод вернёт результат немедленно. Если XPath не появится после timeout миллисекунд ожидания, функция выбросит исключение.

Этот метод работает через переходы:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  let currentURL;
  page.mainFrame()
    .waitForXPath('//img')
    .then(() => console.log('First URL with image: ' + currentURL));
  for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
  }
  await browser.close();
})();

класс: Контекст выполнения

Класс представляет контекст для выполнения JavaScript. У страницы может быть много контекстов выполнения:

каждый фрейм имеет «по умолчанию» контекст выполнения, который всегда создаётся после добавления фрейма в DOM. Этот контекст возвращается методом frame.executionContext().
контент скрипты расширений создают дополнительные контексты выполнения.

Помимо страниц, контексты выполнения можно найти в воркерах.

executionContext.evaluate(pageFunction[, ...args])

pageFunction <функция|строка> Функция, которая должна быть выполнена в контексте executionContext
...args <...Сериализуемый|JSHandle> Аргументы, которые нужно передать в pageFunction
возвращает: <Promise<Сериализуемый>> Promise, который разрешается до возвращаемого значения pageFunction

Если функция, переданная в executionContext.evaluate возвращает Promise, тогда executionContext.evaluate будет ждать разрешения обещания и возвращать его значение.

Если функция, переданная в executionContext.evaluate возвращает не-сериализуемое значение, то executionContext.evaluate разрешается до значения undefined. Протокол DevTools также поддерживает передачу некоторых дополнительных значений, которые не сериализуются с помощью JSON: -0, NaN, Infinity, -Infinity, и литералы bigint.

const executionContext = await page.mainFrame().executionContext();
const result = await executionContext.evaluate(() => Promise.resolve(8 * 7));
console.log(result); // prints "56"

Вместо функции также можно передать строку.

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

Экземпляры JSHandle могут быть переданы в качестве аргументов в метод executionContext.evaluate:

const oneHandle = await executionContext.evaluateHandle(() => 1);
const twoHandle = await executionContext.evaluateHandle(() => 2);
const result = await executionContext.evaluate((a, b) => a + b, oneHandle, twoHandle);
await oneHandle.dispose();
await twoHandle.dispose();
console.log(result); // prints '3'.

executionContext.evaluateHandle(pageFunction[, ...args])

pageFunction <функция|строка> Функция, которая должна быть выполнена в данном контексте executionContext
...args <...Сериализуемый|JSHandle> Аргументы, которые нужно передать в pageFunction
возвращает: <Promise<JSHandle|ElementHandle>> Promise, который разрешается до возвращаемого значения pageFunction в виде объекта на странице.

Единственное различие между executionContext.evaluate и executionContext.evaluateHandle заключается в том, что executionContext.evaluateHandle возвращает объект на странице (JSHandle).

Если функция возвращает элемент, возвращаемая обработка является ElementHandle.

Если функция, переданная в executionContext.evaluateHandle возвращает Promise, тогда executionContext.evaluateHandle будет ждать разрешения обещания и возвращать его значение.

const context = await page.mainFrame().executionContext();
const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
aHandle; // Handle for the global object.

Вместо функции также можно передать строку.

const aHandle = await context.evaluateHandle('1 + 2'); // Handle for the '3' object.

Экземпляры JSHandle могут быть переданы в качестве аргументов в метод executionContext.evaluateHandle:

const aHandle = await context.evaluateHandle(() => document.body);
const resultHandle = await context.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue()); // prints body's innerHTML
await aHandle.dispose();
await resultHandle.dispose();

executionContext.frame()

возвращает: <?Фрейм> Фрейм, связанный с этим контекстом выполнения.

ПРИМЕЧАНИЕ Не каждый контекст выполнения связан с фреймом. Например, воркеры и расширения имеют контексты выполнения, которые не связаны с фреймами.

executionContext.queryObjects(prototypeHandle)

prototypeHandle <JSHandle> Обработка прототипа объекта.
возвращает: <Promise<JSHandle>> Обработка массива объектов с этим прототипом

Метод итерирует кучу JavaScript и находит все объекты с заданным прототипом.

// Create a Map object
await page.evaluate(() => window.map = new Map());
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();

класс: JSHandle

JSHandle представляет собой объект JavaScript на странице. JSHandles можно создать с помощью метода page.evaluateHandle.

const windowHandle = await page.evaluateHandle(() => window);
// ...

JSHandle предотвращает сборку мусора ссылочного объекта JavaScript, пока обработка не будет удалена. JSHandles автоматически удаляются, когда фрейм происхождения переходит на новую страницу или родительский контекст уничтожается.

JSHandle можно использовать в качестве аргументов в методах page.$eval(), page.evaluate() и page.evaluateHandle.

jsHandle.asElement()

возвращает: <?ElementHandle>

Возвращает либо null , либо сам объект обработки, если объект обработки является экземпляром ElementHandle.

jsHandle.dispose()

возвращает: <Promise> Promise, который разрешается, когда объект обработки успешно удалён.

Метод jsHandle.dispose прекращает ссылку на обработку элемента.

jsHandle.evaluate(pageFunction[, ...args])

pageFunction <функция(Объект)> Функция, которая должна быть выполнена в контексте браузера
...args <...Сериализуемый|JSHandle> Аргументы, которые нужно передать в pageFunction
возвращает: <Promise<Сериализуемый>> Promise, который разрешается до возвращаемого значения pageFunction

Этот метод передаёт эту обработку как первый аргумент в pageFunction.

Если pageFunction возвращает Promise, тогда handle.evaluate будет ждать разрешения обещания и возвращать его значение.

Примеры:

const tweetHandle = await page.$('.tweet .retweets');
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');

jsHandle.evaluateHandle(pageFunction[, ...args])

pageFunction <function|string> Функция, подлежащая оценке
...args <...Сериализуемый|JSHandle> Аргументы, передаваемые в pageFunction
returns: <Promise<JSHandle|ElementHandle>> Promise, которое разрешается в значение возврата pageFunction в виде объекта на странице.

Этот метод передаёт этот обработчик в качестве первого аргумента в pageFunction.

Единственное различие между jsHandle.evaluate и jsHandle.evaluateHandle заключается в том, что executionContext.evaluateHandle возвращает объект на странице (JSHandle).

Если функция возвращает элемент, возвращаемый обработчик является ElementHandle.

Если функция, переданная в jsHandle.evaluateHandle , возвращает Promise, то jsHandle.evaluateHandle будет ожидать разрешения промиса и возвращать его значение.

См. Page.evaluateHandle для получения более подробной информации.

jsHandle.executionContext()

returns: <ExecutionContext>

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

jsHandle.getProperties()

returns: <Promise<Map<string, JSHandle>>>

Метод возвращает карту со именами свойств в качестве ключей и экземплярами JSHandle для значений свойств.

const handle = await page.evaluateHandle(() => ({window, document}));
const properties = await handle.getProperties();
const windowHandle = properties.get('window');
const documentHandle = properties.get('document');
await handle.dispose();

jsHandle.getProperty(propertyName)

propertyName <string> Свойство для получения
returns: <Promise<JSHandle>>

Извлекает одно свойство из объекта-ссылочного объекта.

jsHandle.jsonValue()

returns: <Promise<Объект>>

Возвращает JSON-представление объекта. Если объект имеет функцию toJSON, она не будет вызвана.

ПРИМЕЧАНИЕ Метод вернёт пустой JSON-объект, если ссылаемый объект не может быть сериализован в JSON. Он выдаст ошибку, если объект содержит циклические ссылки.

class: ElementHandle

extends: JSHandle

ElementHandle представляет элемент DOM на странице. ElementHandle можно создать с помощью метода page.$.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const hrefElement = await page.$('a');
  await hrefElement.click();
  // ...
})();

ElementHandle предотвращает сборку мусора DOM-элемента, пока обработчик не будет удален. ElementHandle автоматически удаляются, когда их исходная фрейм навигация завершается.

Экземпляры ElementHandle могут быть использованы в качестве аргументов в методах page.$eval() и page.evaluate().

elementHandle.$(selector)

selector <string> Селектор для поиска элемента
returns: <Promise<?ElementHandle>>

Метод выполняет element.querySelector на странице. Если ни один элемент не соответствует селектору, возвращаемое значение разрешается в null.

elementHandle.$$(selector)

selector <string> Селектор для поиска элемента
returns: <Promise<Массив<ElementHandle>>>

Метод выполняет element.querySelectorAll на странице. Если ни один элемент не соответствует селектору, возвращаемое значение разрешается в [].

elementHandle.$$eval(selector, pageFunction[, ...args])

selector <string> Селектор для поиска элемента на странице
pageFunction <function(Массив<Элемент>)> Функция, подлежащая оценке в контексте браузера
...args <...Сериализуемый|JSHandle> Аргументы, передаваемые в pageFunction
returns: <Promise<Сериализуемый>> Promise, который разрешается в возвращаемое значение pageFunction

Этот метод выполняет document.querySelectorAll внутри элемента и передаёт его в качестве первого аргумента в pageFunction. Если ни один элемент не соответствует selector, метод генерирует ошибку.

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

Примеры:

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>

const feedHandle = await page.$('.feed');
expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!']);

elementHandle.$eval(selector, pageFunction[, ...args])

selector <string> Селектор для поиска элемента на странице
pageFunction <function(Элемент)> Функция, подлежащая оценке в контексте браузера
...args <...Сериализуемый|JSHandle> Аргументы, передаваемые в pageFunction
returns: <Promise<Сериализуемый>> Promise, который разрешается в возвращаемое значение pageFunction

Этот метод выполняет document.querySelector внутри элемента и передаёт его в качестве первого аргумента в pageFunction. Если ни один элемент не соответствует selector, метод генерирует ошибку.

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

Примеры:

const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');

elementHandle.$x(expression)

expression <string> Выражение для оценки.
returns: <Promise<Массив<ElementHandle>>>

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

Узел контекста expression должен быть указан для правильной оценки:

const [childHandle] = await parentHandle.$x('./div');

elementHandle.asElement()

возвращает: <ElementHandle>

elementHandle.boundingBox()

возвращает: <Promise<?Объект>>
- x <число> координата x элемента в пикселях.
- y <число> координата y элемента в пикселях.
- width <число> ширина элемента в пикселях.
- height <число> высота элемента в пикселях.

Этот метод возвращает прямоугольник, описывающий область элемента (относительно основного фрейма), или null если элемент не виден.

elementHandle.boxModel()

возвращает: <Promise<?Объект>>
- content <Массив<Объектов>> Блок контента.
  - x <число>
  - y <число>
- padding <Массив<Объектов>> Блок отступа.
- border <Массив<Объектов>> Блок границы.
- margin <Массив<Объектов>> Блок отступа.
- width <число> Ширина элемента.
- height <число> Высота элемента.

Этот метод возвращает блоки элемента, или null если элемент не виден. Блоки представлены как массив точек; каждая точка — объект {x, y}. Точки блоков отсортированы по часовой стрелке.

elementHandle.click([options])

options <Объект>
- button <"слева"|"справа"|"посередине"> По умолчанию left.
- clickCount <число> по умолчанию 1. Смотрите UIEvent.detail.
- delay <число> Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
возвращает: <Promise> Promise, который выполняется, когда элемент успешно нажат. Promise отклоняется, если элемент отключен от DOM.

Этот метод прокручивает элемент в видимую область, если необходимо, а затем использует page.mouse для нажатия в центре элемента. Если элемент отключен от DOM, метод генерирует ошибку.

elementHandle.contentFrame()

возвращает: <Promise<?Фрейм>> Возвращает фрейм контента для элементов, ссылающихся на узлы iframe, или null в противном случае.

elementHandle.dispose()

возвращает: <Promise> Promise, который выполняется, когда обработчик элемента успешно удален.

Метод elementHandle.dispose прекращает ссылку на обработчик элемента.

elementHandle.evaluate(pageFunction[, ...args])

pageFunction <функция(Объект)> Функция, подлежащая выполнению в контексте браузера.
...args <...Сериализуемый|JSHandle> Аргументы для передачи pageFunction.
возвращает: <Promise<Сериализуемый>> Promise, который возвращает значение, возвращаемое pageFunction.

Этот метод передает этот обработчик в качестве первого аргумента pageFunction.

Если pageFunction возвращает Promise, то handle.evaluate будет ожидать завершения Promise и возвращать его значение.

Примеры:

const tweetHandle = await page.$('.tweet .retweets');
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');

elementHandle.evaluateHandle(pageFunction[, ...args])

pageFunction <функция|строка> Функция, подлежащая выполнению
...args <...Сериализуемый|JSHandle> Аргументы для передачи pageFunction
возвращает: <Promise<JSHandle|ElementHandle>> Promise, который возвращает значение, возвращаемое pageFunction как объект на странице.

Этот метод передает этот обработчик в качестве первого аргумента pageFunction.

Единственное различие между elementHandle.evaluate и elementHandle.evaluateHandle заключается в том, что executionContext.evaluateHandle возвращает объект на странице (JSHandle).

Если функция возвращает элемент, возвращаемый обработчик является ElementHandle.

Если функция, переданная в elementHandle.evaluateHandle возвращает Promise, то elementHandle.evaluateHandle будет ожидать завершения Promise и возвращать его значение.

См. Page.evaluateHandle для получения дополнительной информации.

elementHandle.executionContext()

возвращает: <ExecutionContext>

elementHandle.focus()

возвращает: <Promise>

Вызывает focus для элемента.

elementHandle.getProperties()

возвращает: <Promise<Map<строка, JSHandle>>>

Метод возвращает карту с именами свойств в качестве ключей и экземплярами JSHandle для значений свойств.

const listHandle = await page.evaluateHandle(() => document.body.children);
const properties = await listHandle.getProperties();
const children = [];
for (const property of properties.values()) {
  const element = property.asElement();
  if (element)
    children.push(element);
}
children; // holds elementHandles to all children of document.body

elementHandle.getProperty(propertyName)

propertyName <строка> свойство для получения
возвращает: <Promise<JSHandle>>

Извлекает одно свойство из объекта objectHandle.

elementHandle.hover()

возвращает: <Promise> Promise, который разрешается, когда элемент успешно наведён курсором.

Этот метод прокручивает элемент в область видимости при необходимости и затем использует page.mouse для наведения курсора на центр элемента. Если элемент отсоединён от DOM, метод выбросит ошибку.

elementHandle.isIntersectingViewport()

возвращает: <Promise<boolean>> Разрешается до значения true, если элемент виден в текущей области просмотра.

elementHandle.jsonValue()

возвращает: <Promise<Объект>>

Возвращает JSON-представление объекта. JSON генерируется путём выполнения JSON.stringify над объектом на странице и последующего JSON.parse в puppeteer.

ПРИМЕЧАНИЕ Метод выбросит ошибку, если сославшийся объект не может быть сериализован в строку.

elementHandle.press(key[, options])

key <строка> Имя нажимаемой клавиши, например ArrowLeft. Список всех имён клавиш см. в USKeyboardLayout.
options <Объект>
- text <строка> Если указано, генерирует событие ввода с этим текстом.
- delay <число> Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Фокусирует элемент и затем использует keyboard.down и keyboard.up.

Если key — одиночный символ и не удерживаются никакие модификаторы кроме Shift, будет также сгенерировано событие keypress/input. Опция text может быть указана для принудительной генерации события ввода.

ПРИМЕЧАНИЕ Модификаторы клавиш ВЛИЯЮТ на elementHandle.press. Удержание Shift приведет к вводу текста в верхнем регистре.

elementHandle.screenshot([options])

options <Объект> Те же параметры, что и в page.screenshot.
возвращает: <Promise<строка|Буфер>> Promise, который разрешается до буфера или строкового представления в формате base64 (в зависимости от значения options.encoding) с захваченным снимком экрана.

Этот метод прокручивает элемент в область видимости при необходимости и затем использует page.screenshot для получения снимка экрана элемента. Если элемент отсоединён от DOM, метод выбросит ошибку.

elementHandle.select(...values)

...values <...строка> Значения опций для выбора. Если элемент <select> имеет атрибут multiple, учитываются все значения, иначе учитывается только первое.
возвращает: <Promise<Массив<строка>>> Массив значений опций, которые были успешно выбраны.

Вызывает события change и input после выбора всех предоставленных опций. Если нет элемента <select> соответствующего selector, метод выбросит ошибку.

handle.select('blue'); // single selection
handle.select('red', 'green', 'blue'); // multiple selections

elementHandle.tap()

возвращает: <Promise> Promise, который разрешается, когда элемент успешно нажат. Promise отклоняется, если элемент отсоединён от DOM.

Этот метод прокручивает элемент в область видимости при необходимости и затем использует touchscreen.tap для нажатия в центре элемента. Если элемент отсоединён от DOM, метод выбросит ошибку.

elementHandle.toString()

возвращает: <строка>

elementHandle.type(text[, options])

text <строка> Текст для ввода в сфокусированный элемент.
options <Объект>
- delay <число> Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
возвращает: <Promise>

Фокусирует элемент и затем отправляет события keydown, keypress/input и keyup для каждого символа в тексте.

Для нажатия специальной клавиши, например Control или ArrowDown, используйте elementHandle.press.

await elementHandle.type('Hello'); // Types instantly
await elementHandle.type('World', {delay: 100}); // Types slower, like a user

Пример ввода текста в поле ввода и отправки формы:

const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');

elementHandle.uploadFile(...filePaths)

...filePaths <...строка> Устанавливает значение поля ввода файла для этих путей. Если некоторые из filePaths являются относительными путями, они разрешаются относительно текущего каталога.
возвращает: <Promise>

Этот метод ожидает, что elementHandle указывает на элемент input.

class: HTTPRequest

Всякий раз, когда страница отправляет запрос, например, к сетевому ресурсу, следующие события генерируются страницей puppeteer:

'request' генерируется при отправке запроса страницей.
'response' генерируется при получении ответа на запрос.
'requestfinished' генерируется, когда тело ответа загружено, и запрос завершён.

Если запрос терпит неудачу в какой-то момент, вместо события 'requestfinished' (и возможно вместо события 'response'), генерируется событие 'requestfailed'.

ПРИМЕЧАНИЕ HTTP-ответы с ошибками, такие как 404 или 503, всё ещё являются успешными ответами с точки зрения HTTP, поэтому запрос завершается событием 'requestfinished'.

Если запрос получает ответ с перенаправлением, запрос успешно завершается событием 'requestfinished', и отправляется новый запрос по перенаправленному URL.

httpRequest.abort([errorCode])

errorCode <string> Дополнительный код ошибки. По умолчанию failed, может быть одним из следующих:
- aborted - Операция была прервана (из-за действия пользователя)
- accessdenied - Разрешение на доступ к ресурсу, помимо сети, было отказано
- addressunreachable - IP-адрес недоступен. Обычно это означает, что нет маршрута к указанному хосту или сети.
- blockedbyclient - Клиент выбрал заблокировать запрос.
- blockedbyresponse - Запрос не удался, так как в ответе были указаны требования, которые не выполняются ('X-Frame-Options' и 'Content-Security-Policy' проверки предков, например).
- connectionaborted - Сбой таймаута соединения в результате отсутствия получения подтверждения (ACK) для отправленных данных.
- connectionclosed - Соединение было закрыто (соответствует TCP FIN).
- connectionfailed - Попытка подключения не удалась.
- connectionrefused - Попытка подключения была отклонена.
- connectionreset - Соединение было перезапущено (соответствует TCP RST).
- internetdisconnected - Интернет-соединение потеряно.
- namenotresolved - Имя хоста не удалось разрешить.
- timedout - Операция превысила время ожидания.
- failed - Произошла общая ошибка.
returns: <Promise>

Прерывает запрос. Для использования необходимо включить перехват запросов с помощью page.setRequestInterception. Исключение выбрасывается немедленно, если перехват запросов не включён.

httpRequest.continue([overrides])

overrides <Object> Необязательные перезаписи запроса, которые могут быть следующими:
- url <string> Если задано, URL запроса будет изменён. Это не переадресация. Запрос будет тихо перенаправлен на новый URL. Например, адресная строка будет отображать исходный URL.
- method <string> Если задано, изменяет метод запроса (например, GET или POST).
- postData <string> Если задано, изменяет данные POST запроса.
- headers <Object> Если задано, изменяет HTTP-заголовки запроса. Значения заголовков будут преобразованы в строку.
returns: <Promise>

Продолжает запрос с необязательными перезаписями запроса. Для использования необходимо включить перехват запросов с помощью page.setRequestInterception. Исключение выбрасывается немедленно, если перехват запросов не включён.

await page.setRequestInterception(true);
page.on('request', request => {
  // Override headers
  const headers = Object.assign({}, request.headers(), {
    foo: 'bar', // set "foo" header
    origin: undefined, // remove "origin" header
  });
  request.continue({headers});
});

httpRequest.failure()

returns: <?Object> Объект, описывающий ошибку запроса, если таковая есть
- errorText <string> Читаемое сообщение об ошибке, например, 'net::ERR_FAILED'.

Метод возвращает null, если запрос не завершился ошибкой, как указано событием requestfailed.

Пример логирования всех неисправных запросов:

page.on('requestfailed', request => {
  console.log(request.url() + ' ' + request.failure().errorText);
});

httpRequest.frame()

returns: <?Frame> Фрейм, который инициировал этот запрос, или null при переходе на страницы ошибок.

httpRequest.headers()

returns: <Object> Объект с HTTP-заголовками, связанными с запросом. Все имена заголовков в нижнем регистре.

httpRequest.isNavigationRequest()

returns: <boolean>

Является ли этот запрос навигацией фрейма.

httpRequest.method()

returns: <string> Метод запроса (GET, POST и т.д.)

httpRequest.postData()

returns: <string> Тело запроса POST, если оно есть.

httpRequest.redirectChain()

returns: <Array<HTTPRequest>>

Цепочка redirectChain — это цепочка запросов, инициированных для получения ресурса.

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

redirectChain общий для всех запросов одной цепочки.

Например, если веб-сайт http://example.com имеет единственную переадресацию на https://example.com, тогда цепочка будет содержать один запрос:

const response = await page.goto('http://example.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 1
console.log(chain[0].url()); // 'http://example.com'

Если веб-сайт https://google.com не имеет переадресаций, тогда цепочка будет пустой:

const response = await page.goto('https://google.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 0

httpRequest.resourceType()

returns: <string>

Содержит тип ресурса запроса, как он был воспринят движком рендеринга. ResourceType будет одним из следующих: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other.

httpRequest.respond(response)

response <Object> Ответ, который выполнит этот запрос
- status <number> Код состояния ответа, по умолчанию 200.
- headers <Object> Необязательные заголовки ответа. Значения заголовков будут преобразованы в строку.
- contentType <string> Если задано, эквивалентно установке заголовка ответа Content-Type.
- body <string|Buffer> Необязательное тело ответа.
returns: <Promise>

Выполняет запрос с заданным ответом. Для использования необходимо включить перехват запросов с помощью page.setRequestInterception. Исключение выбрасывается, если перехват запросов не включён.

Пример выполнения всех запросов с ответами 404:

await page.setRequestInterception(true);
page.on('request', request => {
  request.respond({
    status: 404,
    contentType: 'text/plain',
    body: 'Not Found!'
  });
});

ПРИМЕЧАНИЕ Моделирование ответов для запросов dataURL не поддерживается. Вызов request.respond для запроса dataURL — это ничто операция.

httpRequest.response()

returns: <?HTTPResponse> Соответствующий объект HTTPResponse, или null если ответ ещё не получен.

httpRequest.url()

returns: <string> URL запроса.

class: HTTPResponse

HTTPResponse — класс, представляющий ответы, которые получает страница.

httpResponse.buffer()

returns: <Promise<Buffer>> Promise, который разрешается в буфер с телом ответа.

httpResponse.frame()

returns: <?Frame> Фрейм, который инициировал этот ответ, или null при переходе на страницы ошибок.

httpResponse.fromCache()

returns: <boolean>

True, если ответ был получен из кэша браузера на диске или в памяти.

httpResponse.fromServiceWorker()

returns: <boolean>

True, если ответ был получен от service worker.

httpResponse.headers()

returns: <Object> Объект с HTTP-заголовками, связанными с ответом. Все имена заголовков в нижнем регистре.

httpResponse.json()

returns: <Promise<Object>> Promise, который возвращает JSON-представление тела ответа.

Этот метод выбросит исключение, если тело ответа нельзя обработать с помощью JSON.parse.

httpResponse.ok()

returns: <boolean>

Содержит логическое значение, указывающее, был ли ответ успешным (статус в диапазоне 200-299) или нет.

httpResponse.remoteAddress()

returns: <Object>
- ip <string> IP-адрес удаленного сервера
- port <number> порт, используемый для подключения к удаленному серверу

httpResponse.request()

returns: <HTTPRequest> Соответствующий объект HTTPRequest.

httpResponse.securityDetails()

returns: <?SecurityDetails> Сведения о безопасности, если ответ был получен по защищенному соединению, или null в противном случае.

httpResponse.status()

returns: <number>

Содержит код состояния ответа (например, 200 для успеха).

httpResponse.statusText()

returns: <string>

Содержит текст состояния ответа (например, обычно "OK" для успеха).

httpResponse.text()

returns: <Promise<string>> Promise, который возвращает текстовое представление тела ответа.

httpResponse.url()

returns: <string>

Содержит URL ответа.

class: SecurityDetails

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

securityDetails.issuer()

returns: <string> Строка с именем издателя сертификата.

securityDetails.protocol()

returns: <string> Строка со значением протокола безопасности, например, "TLS 1.2".

securityDetails.subjectAlternativeNames()

returns: <Array<string>> Возвращает список SAN (имена альтернативных субъектов) сертификата.

securityDetails.subjectName()

returns: <string> Имя субъекта, которому был выдан сертификат.

securityDetails.validFrom()

returns: <number> Значение UnixTime, указывающее начало срока действия сертификата.

securityDetails.validTo()

returns: <number> Значение UnixTime, указывающее конец срока действия сертификата.

class: Target

target.browser()

returns: <Browser>

Получить браузер, к которому принадлежит целевой объект.

target.browserContext()

returns: <BrowserContext>

Контекст браузера, к которому принадлежит целевой объект.

target.createCDPSession()

returns: <Promise<CDPSession>>

Создает сеанс протокола Chrome Devtools, подключенный к целевому объекту.

target.opener()

returns: <?Target>

Получить целевой объект, открывший текущий целевой объект. Для корневых целевых объектов возвращается null.

target.page()

returns: <Promise<?Page>>

Если целевой объект не является типом "page" или "background_page", возвращается null.

target.type()

returns: <"page"|"background_page"|"service_worker"|"shared_worker"|"other"|"browser">

Определяет тип целевого объекта. Может быть "page", "background_page", "service_worker", "shared_worker", "browser" или "other".

target.url()

returns: <string>

target.worker()

returns: <Promise<?WebWorker>>

Если целевой объект не является типом "service_worker" или "shared_worker", возвращается null.

class: CDPSession

extends: EventEmitter

Экземпляры CDPSession используются для взаимодействия с Chrome Devtools Protocol:

методы протокола можно вызвать с помощью метода session.send.
подписаться на события протокола можно с помощью метода session.on.

Полезные ссылки:

Документация по протоколу DevTools доступна здесь: DevTools Protocol Viewer.
Начало работы с протоколом DevTools: https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md

const client = await page.target().createCDPSession();
await client.send('Animation.enable');
client.on('Animation.animationCreated', () => console.log('Animation created!'));
const response = await client.send('Animation.getPlaybackRate');
console.log('playback rate is ' + response.playbackRate);
await client.send('Animation.setPlaybackRate', {
  playbackRate: response.playbackRate / 2
});

cdpSession.detach()

returns: <Promise>

Отсоединяет cdpSession от целевого объекта. После отсоединения объект cdpSession не будет генерировать события и не сможет использоваться для отправки сообщений.

cdpSession.send(method[, ...paramArgs])

method <string> Имя метода протокола
...paramArgs <Object> Необязательные параметры метода
returns: <Promise<Object>>

class: Coverage

Coverage собирает информацию об используемых частями JavaScript и CSS на странице.

Пример использования покрытия JavaScript и CSS для получения процентного соотношения первоначально выполненного кода:

// Enable both JavaScript and CSS coverage
await Promise.all([
  page.coverage.startJSCoverage(),
  page.coverage.startCSSCoverage()
]);
// Navigate to page
await page.goto('https://example.com');
// Disable both JavaScript and CSS coverage
const [jsCoverage, cssCoverage] = await Promise.all([
  page.coverage.stopJSCoverage(),
  page.coverage.stopCSSCoverage(),
]);
let totalBytes = 0;
let usedBytes = 0;
const coverage = [...jsCoverage, ...cssCoverage];
for (const entry of coverage) {
  totalBytes += entry.text.length;
  for (const range of entry.ranges)
    usedBytes += range.end - range.start - 1;
}
console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);

Чтобы вывести покрытие в формате, приемлемом для Istanbul, см. puppeteer-to-istanbul.

coverage.startCSSCoverage([options])

options <Object> Набор настраиваемых параметров покрытия
- resetOnNavigation <boolean> Сбросить ли покрытие при каждой навигации. По умолчанию true.
returns: <Promise> Promise, который разрешается после запуска покрытия

coverage.startJSCoverage([options])

options <Object> Набор настраиваемых параметров для покрытия
- resetOnNavigation <boolean> Нужно ли сбрасывать покрытие при каждом переходе. По умолчанию true.
- reportAnonymousScripts <boolean> Следует ли сообщать об анонимных скриптах, сгенерированных страницей. По умолчанию false.
возвращает: <Promise> Promise, который разрешается при запуске покрытия

ПРИМЕЧАНИЕ Анонимные скрипты — это скрипты без связанного URL. Это скрипты, которые динамически создаются на странице с использованием eval или new Function. Если reportAnonymousScripts установлено в true, анонимным скриптам будет назначен URL __puppeteer_evaluation_script__.

coverage.stopCSSCoverage()

возвращает: <Promise<Array<Object>>> Promise, который разрешается массивом отчетов о покрытии для всех таблиц стилей
- url <строка> URL таблицы стилей
- text <строка> Содержимое таблицы стилей
- ranges <Массив<Объект>> Диапазоны таблицы стилей, которые использовались. Диапазоны отсортированы и не перекрываются.
  - start <число> Начальный смещение в тексте (включительно)
  - end <число> Конечное смещение в тексте (исключая)

ПРИМЕЧАНИЕ Покрытие CSS не включает динамически инжектированные теги стиля без sourceURLs.

coverage.stopJSCoverage()

возвращает: <Promise<Массив<Объект>>> Promise, который разрешается массивом отчетов о покрытии для всех скриптов
- url <строка> URL скрипта
- text <строка> Содержимое скрипта
- ranges <Массив<Объект>> Диапазоны скриптов, которые были выполнены. Диапазоны отсортированы и не перекрываются.
  - start <число> Начальное смещение в тексте (включительно)
  - end <число> Конечное смещение в тексте (исключая)

ПРИМЕЧАНИЕ Покрытие JavaScript по умолчанию не включает анонимные скрипты. Однако скрипты с sourceURLs будут отчитаны.

класс: TimeoutError

расширяет: Error

TimeoutError генерируется всякий раз, когда определенные операции завершаются из-за таймаута, например, page.waitForSelector(selector[, options]) или puppeteer.launch([options]).

класс: EventEmitter

Небольшой класс EventEmitter, основанный на Mitt.

eventEmitter.addListener(event, handler)

event <строка|символ> событие, из которого нужно удалить обработчик.
handler <Функция> обработчик события, который будет добавлен.
возвращает: this для возможности цепочки вызовов методов

Этот метод идентичен on и поддерживается для совместимости с EventEmitter из Node.js. Рекомендуется использовать on по умолчанию.

eventEmitter.emit(event, [eventData])

event <строка|символ> событие, которое нужно вызвать.
eventData <Объект> дополнительные данные для передачи вместе с событием.
возвращает: boolean; true если существуют обработчики для события, false если нет.

eventEmitter.listenerCount(event)

event <строка|символ> событие, для которого нужно проверить обработчики.
возвращает: <число> количество обработчиков для данного события.

eventEmitter.off(event, handler)

event <строка|символ> событие, из которого нужно удалить обработчик.
handler <Функция> обработчик события, который будет удален.
возвращает: this для возможности цепочки вызовов методов

eventEmitter.on(event, handler)

event <строка|символ> событие, которому нужно добавить обработчик.
handler <Функция> обработчик события, который будет добавлен.
возвращает: this для возможности цепочки вызовов методов

eventEmitter.once(event, handler)

event <строка|символ> событие, которому нужно добавить обработчик.
handler <Функция> обработчик события, который будет добавлен.
возвращает: this для возможности цепочки вызовов методов

eventEmitter.removeAllListeners([event])

event <строка|символ> необязательный аргумент для удаления всех обработчиков для заданного события. Если он не задан, этот метод удалит все обработчики для всех событий.
возвращает: this для возможности цепочки вызовов методов

eventEmitter.removeListener(event, handler)

event <строка|символ> событие, из которого нужно удалить обработчик.
handler <Функция> обработчик события, который будет удален.
возвращает: this для возможности цепочки вызовов методов

Этот метод идентичен off и поддерживается для совместимости с EventEmitter из Node.js. Рекомендуется использовать off по умолчанию.

интерфейс: CustomQueryHandler

Содержит две функции queryOne и queryAll , которые могут быть зарегистрированы в качестве альтернативных стратегий запроса. Функции queryOne и queryAll выполняются в контексте страницы. queryOne должна принимать Element и строку селектора в качестве аргументов и возвращать один Element или null , если элемент не найден. queryAll принимает те же аргументы, но должна вместо этого возвращать NodeList<Element> или Array<Element> со всеми элементами, соответствующими заданному селектору.

Документация Puppeteer

Обзор

puppeteer против puppeteer-core

Переменные среды

Работа с расширениями Chrome

Класс: Puppeteer

puppeteer.clearCustomQueryHandlers()

puppeteer.connect(options)

puppeteer.createBrowserFetcher([options])

puppeteer.customQueryHandlerNames()

puppeteer.defaultArgs([options])

puppeteer.devices

puppeteer.errors

puppeteer.executablePath()

puppeteer.launch([options])

puppeteer.networkConditions

puppeteer.product

puppeteer.registerCustomQueryHandler(name, queryHandler)

puppeteer.unregisterCustomQueryHandler(name)

класс: BrowserFetcher

browserFetcher.canDownload(revision)

browserFetcher.download(revision[, progressCallback])

browserFetcher.host()

browserFetcher.localRevisions()

browserFetcher.platform()

browserFetcher.product()

browserFetcher.remove(revision)

browserFetcher.revisionInfo(revision)

класс: Браузер

событие: 'disconnected'

событие: 'targetchanged'

событие: 'targetcreated'

событие: 'targetdestroyed'

browser.browserContexts()

browser.close()

browser.createIncognitoBrowserContext()

browser.defaultBrowserContext()

browser.disconnect()

browser.isConnected()

browser.newPage()

browser.pages()

browser.process()

browser.target()

browser.targets()

browser.userAgent()

browser.version()

browser.waitForTarget(predicate[, options])

browser.wsEndpoint()

class: BrowserContext

event: 'targetchanged'

event: 'targetcreated'

event: 'targetdestroyed'

browserContext.browser()

browserContext.clearPermissionOverrides()

browserContext.close()

browserContext.isIncognito()

browserContext.newPage()

browserContext.overridePermissions(origin, permissions)

browserContext.pages()

browserContext.targets()

browserContext.waitForTarget(predicate[, options])

class: Page

event: 'close'

event: 'console'

event: 'dialog'

event: 'domcontentloaded'

event: 'error'

event: 'frameattached'

event: 'framedetached'

event: 'framenavigated'

event: 'load'

event: 'metrics'

event: 'pageerror'

event: 'popup'

event: 'request'

event: 'requestfailed'

event: 'requestfinished'

event: 'response'

event: 'workercreated'

event: 'workerdestroyed'