Содержание

Кукловодческая документация

Overview

Кукловод-это библиотека Node,предоставляющая высокоуровневый API для управления Chromium или Chrome по протоколу DevTools.

Кукловодный API является иерархическим и отражает структуру браузера.

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

(Источник схемы: ссылка )

кукловод против кукловода-ядро

В каждом выпуске начиная с версии 1.7.0 мы публикуем два пакета:

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

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

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

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

Однако вы должны использовать puppeteer-core если:

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

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

Затем вам нужно будет вызвать puppeteer.connect([options]) или puppeteer.launch([options]) с явной опцией executablePath .

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

Кукловод ищет определенные переменные среды, чтобы помочь в его работе. Если Puppeteer не находит их в среде на этапе установки, будет использоваться вариант этих переменных в нижнем регистре из конфигурации npm .

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

Работа с хромированными удлинителями

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

ПРИМЕЧАНИЕ. Расширения в 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();
  // Тестируем фоновую страницу так же, как и любую другую страницу.
  await browser.close();
})();
ПРИМЕЧАНИЕ. Пока невозможно протестировать всплывающие окна расширений или сценарии содержимого.

Класс:Кукловод

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

const puppeteer = require('puppeteer');
 
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com');
  // другие действия...
  await browser.close();
})();

puppeteer.clearCustomQueryHandlers()

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

puppeteer.connect(options)

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

puppeteer.createBrowserFetcher%%([%%options])

puppeteer.customQueryHandlerNames()

puppeteer.defaultArgs%%([%%options])

Флаги по умолчанию,с которыми будет запущен 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');
   // другие действия...
   await browser.close();
})();

puppeteer.errors

Методы кукловода могут вызывать ошибки, если они не могут выполнить запрос. Например, 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.executablePath() влияют переменные PUPPETEER_EXECUTABLE_PATH и PUPPETEER_CHROMIUM_REVISION . См. Подробности в разделе « Переменные среды» .

puppeteer.launch%%([%%options])

Вы можете использовать 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

* возвращает: < Object >

Возвращает список сетевых условий, которые будут использоваться с 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');
  // другие действия...
  await browser.close();
})();

puppeteer.product

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

puppeteer.registerCustomQueryHandler(name, queryHandler)

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

Example: 

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)

Класс:BrowserFetcher

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

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

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

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

const browserFetcher = puppeteer.createBrowserFetcher();
const revisionInfo = await browserFetcher.download('533271');
const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
ПРИМЕЧАНИЕ BrowserFetcher не предназначен для одновременной работы с другими экземплярами BrowserFetcher, которые используют тот же каталог загрузок.

browserFetcher.canDownload(revision)

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

browserFetcher.download(revision[,progressCallback]).

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

browserFetcher.host()

browserFetcher.localRevisions()

browserFetcher.platform()

browserFetcher.product()

browserFetcher.remove(revision)

browserFetcher.revisionInfo(revision)

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

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

Браузер создается, когда 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();
  // Сохраняем конечную точку, чтобы иметь возможность повторно подключиться к Chromium
  const browserWSEndpoint = browser.wsEndpoint();
  // Отключить кукловода от Chromium
  browser.disconnect();
 
  // Использование конечной точки для восстановления соединения
  const browser2 = await puppeteer.connect({browserWSEndpoint});
  // Закрываем Chromium
  await browser2.close();
})();

Событие:"разъединённый

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

Событие:"изменённая мишень

Испускается,когда урна мишени меняется.

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

Событие:"созданный мишенью

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

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

Событие:"уничтоженный мишенью

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

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

browser.browserContexts()

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

browser.close()

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

browser.createIncognitoBrowserContext()

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

(async () => {
  const browser = await puppeteer.launch();
  // Создаем новый контекст браузера в режиме инкогнито.
  const context = await browser.createIncognitoBrowserContext();
  // Создаем новую страницу в безупречном контексте.
  const page = await context.newPage();
  // Делаем что-нибудь
  await page.goto('https://example.com');
})();

browser.defaultBrowserContext()

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

browser.disconnect()

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

browser.isConnected()

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

browser.newPage()

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

browser.pages()

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

browser.process()

browser.target()

Цель,связанная с браузером.

browser.targets()

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

browser.userAgent()

ПРИМЕЧАНИЕ Pages могут переопределить пользовательский агент браузера с помощью page.setUserAgent.

browser.version()

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

browser.waitForTarget(предикат[,опции]).

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

Пример поиска цели для страницы, открытой через 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()

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

Вы можете найти webSocketDebuggerUrl по ''http://${host}:${port}/json/version'' . Узнайте больше о протоколе devtools и конечной точке браузера .

Класс:БраузерКонтекст

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

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

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

// Создаем новый контекст браузера в режиме инкогнито
const context = await browser.createIncognitoBrowserContext();
// Создаем новую страницу внутри контекста.
const page = await context.newPage();
// ... что-то делать со страницей ...
await page.goto('https://example.com');
// Удаляем контекст, когда он больше не нужен.
await context.close();

Событие:"изменённая мишень

Исполняется,когда изменяется url цели внутри контекста браузера.

Событие:"созданный мишенью

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

Событие:"уничтоженный мишенью

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

browserContext.browser()

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

browserContext.clearPermissionOverrides()

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

const context = browser.defaultBrowserContext();
context.overridePermissions('https://example.com', ['clipboard-read']);
// делаем что-нибудь ..
context.clearPermissionOverrides();

browserContext.close()

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

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

browserContext.isIncognito()

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

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

browserContext.newPage()

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

browserContext.overrideПолномочия (происхождение,разрешения)

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

browserContext.pages()

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

browserContext.targets()

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

browserContext.waitForTarget(предикат[,опции])

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

Пример поиска цели для страницы, открытой через window.open : 

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

Класс:Страница

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

В этом примере создается страница,осуществляется навигация по 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);
// Немного позже...
page.off('request', logRequest);

Событие:"закрытие

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

Событие:"консоль

Генерируется, когда 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'}));

Событие:"диалог

Выдается при появлении диалогового окна JavaScript, например alert , prompt , confirm или beforeunload . Кукольник может ответить на диалог с помощью Диалог «s принять или отклонить методы.

Событие:"загруженный дом

Генерируется при DOMContentLoaded события JavaScript DOMContentLoaded .

Событие:"ошибка

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

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

Событие:"подкреплённый

Испускается,когда рама прикреплена.

Событие:"обрамлённый

Используется,когда рамка отсоединена.

Событие:"фрэмавигационный

Используется,когда рамка перемещается к новому урлу.

событие:"нагрузка

Генерируется при отправке события load JavaScript .

Событие:"метрика

Генерируется, когда код JavaScript вызывает console.timeStamp . Список показателей см. На page.metrics .

событие:'пейджеррор

Выписывается,когда на странице происходит незамеченное исключение.

Событие:"всплытие

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

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')),
]);

Событие:"запрос

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

Событие:"отклонённый запрос

Используется,когда запрос не удается,например,по таймингу.

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

Событие:запрошенный

Выпущено при успешном завершении запроса.

Событие:"реакция

Выдается при получении HTTPResponse .

Событие:"созданный рабочими

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

Событие:"уничтоженный рабочими

Выдается при завершении работы выделенного WebWorker .

page.$(selector)

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

Ярлык для page.mainFrame (). $ (Селектор) .

page.$$(selector)

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

Ярлык для page.mainFrame (). $$ (селектор) .

page.$$eval(селектор,функция pageFunction[,...args]))

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

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

Examples: 

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(селектор,pageFunction[,...args]))

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

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

Examples: 

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)

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

Ярлык для page.mainFrame (). $ X (выражение)

page.accessibility

page.addScriptTag(options)

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

Ярлык для page.mainFrame (). AddScriptTag (параметры) .

page.addStyleTag(options)

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

Ярлык для page.mainFrame (). AddStyleTag (параметры) .

page.authenticate(credentials)

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

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

page.bringToFront()

Привязка страницы к началу (активирует вкладку).

page.browser()

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

page.browserContext()

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

страница.click(селектор[,опции])

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

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

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

Ярлык для page.mainFrame (). Click (селектор [, параметры]) .

page.close%%([%%options])

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

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

page.content()

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

page.cookies%%([%%...urls])

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

page.coverage

page.deleteCookie(...cookies)

page.emulate(options)

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

Чтобы облегчить эмуляцию, кукольник предоставляет список дескрипторов устройства, который можно получить с помощью 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');
  // другие действия...
  await browser.close();
})();

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

page.emulateIdleState(overrides)

page.emulateMediaFeatures(features)

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)

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)

ПРИМЕЧАНИЕ. Это не влияет на 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');
  // другие действия...
  await browser.close();
})();

page.emulateTimezone(timezoneId)

page.emulateVisionDeficiency(type)

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.assess(pageFunction[,...args]))

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

Если функция передается page.evaluate возвращает значение не Serializable значения, то 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); // выводит "56"

Также вместо функции может быть передана строка: 

console.log(await page.evaluate('1 + 2')); // выводит "3"
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // выводит "11"

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

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

Ярлык для page.mainFrame (). Оценить (pageFunction, ... args) .

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

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

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

Также вместо функции может быть передана строка: 

const aHandle = await page.evaluateHandle('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'))
// кнопка - это ElementHandle, поэтому вы можете вызывать такие методы, как click:
await button.click();

Ярлык для page.mainFrame (). ExecuteContext (). AssessmentHandle (pageFunction, ... args) .

page.оценитьOnNewDocument(pageFunction[,...args]))

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

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

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

// preload.js
 
// перезаписываем свойство `languages` для использования специального получателя
Object.defineProperty(navigator, "languages", {
  get: function() {
    return ["en-US", "en", "bn"];
  }
});
 
// В вашем скрипте кукловода предполагается, что файл preload.js находится в той же папке, что и наш скрипт
const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await page.evaluateOnNewDocument(preloadFile);

page.exposeFunction(имя,куклаFunction)

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

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

ПРИМЕЧАНИЕ Функции, установленные через 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 () => {
    // используем window.md5 для вычисления хэшей
    const myString = 'PUPPETEER';
    const myHash = await window.md5(myString);
    console.log(`md5 of ${myString} is ${myHash}`);
  });
  await browser.close();
})();

Пример добавления на window.readfile функции 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 () => {
    // используем window.readfile для чтения содержимого файла
    const content = await window.readfile('/etc/hosts');
    console.log(content);
  });
  await browser.close();
})();

page.focus(selector)

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

Ярлык для page.mainFrame (). Focus (селектор) .

page.frames()

page.goBack%%([%%options])

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

page.goForward%%([%%options])

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

page.goto(url[,опции])

page.goto выдаст ошибку, если:

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

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

Ярлык для page.mainFrame (). Goto (URL, параметры)

page.hover(selector)

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

Ярлык для page.mainFrame (). Hover (селектор) .

page.isClosed()

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

page.isJavaScriptEnabled()

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

page.keyboard

page.mainFrame()

Страница гарантированно имеет основную рамку,которая сохраняется во время навигации.

page.metrics()

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

page.mouse

page.pdf%%([%%options])

ПРИМЕЧАНИЕ. В настоящее время создание 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 принимают значения, помеченные единицами измерения. Значения без меток обрабатываются как пиксели.

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

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

В format опции:

ПРИМЕЧАНИЕ. headerTemplate и footerTemplate имеет следующие ограничения: Теги сценариев внутри шаблонов не оцениваются. Стили страниц не видны внутри шаблонов.

page.queryObjects(prototypeHandle)

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

// Создаем объект Map
await page.evaluate(() => window.map = new Map());
// Получаем дескриптор прототипа объекта Map
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Запрос всех экземпляров карты в массив
const mapInstances = await page.queryObjects(mapPrototype);
// Подсчитываем количество объектов карты в куче
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();

Ярлык для page.mainFrame (). ExecuteContext (). QueryObjects (prototypeHandle) .

page.reload%%([%%options])

page.screenshot%%([%%options])

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

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

Запускает событие change и input после выбора всех предоставленных параметров. Если нет selector соответствия элемента <select> , метод выдает ошибку. 

page.select('select#colors', 'blue'); // одиночный выбор
page.select('select#colors', 'red', 'green', 'blue'); // множественный выбор

Ярлык для page.mainFrame (). Select ()

page.setBypassCSP(enabled)

Переключатели,минуя Контент-Политика Безопасности-Содержание страницы.

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

page.setCacheEnabled%%([%%enabled])

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

page.setContent(html[,options]))

page.setCookie(...cookies)

await page.setCookie(cookieObject1, cookieObject2);

page.setDefaultNavigationTimeout(timeout)

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

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

page.setDefaultTimeout(timeout)

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

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

page.setExtraHTTPHeaders(headers)

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

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

page.setGeolocation(options)

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

await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
ПРИМЕЧАНИЕ. Рассмотрите возможность использования browserContext.overridePermissions, чтобы предоставить странице разрешения на чтение ее геолокации.

page.setJavaScriptEnabled(enabled)

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

page.setOfflineMode(enabled)

page.setRequestInterception(value)

Активация перехвата запросов включает методы 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)

page.setViewport(viewport)

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

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

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

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

page.tap(selector)

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

Ярлык для page.mainFrame (). Tap (селектор) .

page.target()

page.title()

Ярлык для page.mainFrame (). Title () .

page.touchscreen

page.tracing

page.type(селектор,text[,опции]))

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

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

await page.type('#mytextarea', 'Hello'); // Мгновенно набирает
await page.type('#mytextarea', 'World', {delay: 100}); // Набирает медленнее, как пользователь

Ярлык для page.mainFrame (). Type (селектор, текст [, параметры]) .

page.url()

Это ярлык для page.mainFrame (). Url ()

page.viewport()

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

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

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

// ждем селектора
await page.waitFor('.foo');
// ждем 1 секунду
await page.waitFor(1000);
// ждем предиката
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])

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

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

const [fileChooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('#upload-file-button'), // какая-то кнопка, запускающая выбор файла
]);
await fileChooser.accept(['/tmp/myfile.pdf']);
Примечание Это должно быть названо , прежде чем файл Chooser запускается. Он не вернет активный в данный момент выбор файла.

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

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

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();
  // показать аватар
  const img = document.createElement('img');
  img.src = githubUser.avatar_url;
  // ждем 3 секунды
  await new Promise((resolve, reject) => setTimeout(resolve, 3000));
  img.remove();
}, {}, username);

Ярлык для page.mainFrame (). WaitForFunction (pageFunction [, options [, ... args)]] .

page.waitForNavigation%%([%%options])

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

const [response] = await Promise.all([
  page.waitForNavigation(), // Обещание разрешается после завершения навигации
  page.click('a.my-link'), // Нажатие на ссылку косвенно вызовет навигацию
]);

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

Ярлык для page.mainFrame (). WaitForNavigation (параметры) .

page.waitForRequest(urlOrPredicate[,опции]))

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[,опции]))

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 . Если на момент вызова метода 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 (селектор [, параметры]) .

page.waitForTimeout(milliseconds)

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

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[,опции]))

Подождите, пока 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 [, параметры]) .

page.workers()

ПРИМЕЧАНИЕ. Не содержит ServiceWorkers.

GeolocationOptions

WaitTimeoutOptions

class: WebWorker

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

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])

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

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

Ярлык для (await worker.executionContext ()). Assessment (pageFunction, ... args) .

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

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

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

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

Ярлык для (await worker.executionContext ()). AssessmentHandle (pageFunction, ... args) .

webWorker.executionContext()

webWorker.url()

Класс:Доступность

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

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

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

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

accessibility.snapshot%%([%%options])

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

ПРИМЕЧАНИЕ . Дерево доступности Chromium содержит узлы, которые не используются на большинстве платформ и большинством программ чтения с экрана. Кукловод также отбрасывает их, чтобы упростить обработку дерева, если для параметра 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;
}

Класс:Клавиатура

Клавиатура предоставляет API для управления виртуальной клавиатурой. API высокого уровня - это keyboard.type , который принимает необработанные символы и генерирует правильные события нажатия клавиш, нажатия / ввода и нажатия клавиш на вашей странице.

Для более точного управления вы можете использовать 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');
// В результате в тексте результата будет написано «Привет!»

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

await page.keyboard.down('Shift');
await page.keyboard.press('KeyA');
await page.keyboard.up('Shift');
ПРИМЕЧАНИЕ В MacOS такие сочетания клавиш, как ⌘ A → Выбрать все, не работают. См. № 1313

keyboard.down(key[,options]))

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

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

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

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

ПРИМЕЧАНИЕ Клавиши-модификаторы ДЕЙСТВИТЕЛЬНО влияют на раскручивание keyboard.down . Удерживая нажатой Shift вы набираете текст в верхнем регистре.

keyboard.press(key[,options]))

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

ПРИМЕЧАНИЕ Клавиши-модификаторы ДЕЙСТВИТЕЛЬНО влияют на keyboard.press . Удерживая нажатой Shift вы набираете текст в верхнем регистре.

Сочетание клавиш для keyboard.down и keyboard.up .

keyboard.sendCharacter(char)

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

page.keyboard.sendCharacter('嗨');
ПРИМЕЧАНИЕ Клавиши-модификаторы НЕ влияют на keyboard.sendCharacter . Удерживание Shift не приведет к вводу текста в верхнем регистре.

keyboard.type(text[,options]))

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

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

await page.keyboard.type('Hello'); // Мгновенно набирает
await page.keyboard.type('World', {delay: 100}); // Набирает медленнее, как пользователь
ПРИМЕЧАНИЕ Клавиши-модификаторы НЕ влияют на keyboard.type . Удерживание Shift не приведет к вводу текста в верхнем регистре.

keyboard.up(key)

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

Класс:Мышь

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

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

// Использование page.mouse для обведения квадрата 100x100.
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 s. Это означает, что он не полностью воспроизводит функциональность того, что обычный пользователь мог бы делать с помощью своей мыши.

Например, перетаскивание и выделение текста невозможно с помощью 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 буфера обмена не позволяет вам копировать, если вкладка не сфокусирована.
await page.bringToFront();
await page.evaluate(() => {
  // Копируем выделенный контент в буфер обмена
  document.execCommand('copy');
  // Получаем содержимое буфера обмена в виде строки
  return navigator.clipboard.readText();
});

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

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

mouse.click(x,y[,опции]).

Ярлыки для mouse.move , mouse.down и mouse.up .

mouse.down%%([%%options])

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

mouse.move(x,y[,опции))

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

mouse.up%%([%%options])

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

mouse.wheel%%([%%options])

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

Examples: 

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 })

Класс:Сенсорный экран

сенсорный экран.tap(x,y)

Отправляет touchstart и touchend .

Класс:Отслеживание

Вы можете использовать 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])

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

tracing.stop()

Класс:FileChooser

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

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

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

const [fileChooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('#upload-file-button'), // какая-то кнопка, запускающая выбор файла
]);
await fileChooser.accept(['/tmp/myfile.pdf']);
ПРИМЕЧАНИЕ. В браузерах одновременно может быть открыт только один селектор файлов. Все средства выбора файлов должны быть приняты или отменены. Если этого не сделать, то последующие средства выбора файлов не появятся.

fileChooser.accept(filePaths)

fileChooser.cancel()

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

fileChooser.isMultiple()

Класс:Диалог

Объекты диалогов отправляются по страницам с помощью события '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])

dialog.defaultValue()

dialog.dismiss()

dialog.message()

dialog.type()

Класс:Консольное сообщение

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

consoleMessage.args()

consoleMessage.location()

consoleMessage.stackTrace()

consoleMessage.text()

consoleMessage.type()

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

Класс:Фрейм

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

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

Пример сбрасывания каркасного дерева: 

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)

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

frame.$$(selector)

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

frame.$$eval(селектор,функция pageFunction[,...args]))

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

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

Examples: 

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

frame.$eval(селектор,pageFunction[,...args]))

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

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

Examples: 

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)

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

frame.addScriptTag(options)

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

frame.addStyleTag(options)

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

frame.childFrames()

кадр.click (селектор[,опции])

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

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

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

frame.content()

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

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

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

Если функция перешла к frame.evaluate возвращает значение не Serializable значения, то 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.assessHandle(pageFunction[,...args]))

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

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

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

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

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

const aHandle = await frame.evaluateHandle('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()

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

frame.focus(selector)

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

frame.goto(url[,опции])

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

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

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

frame.hover(selector)

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

frame.isDetached()

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

frame.name()

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

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

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

frame.parentFrame()

кадр.выбор (селектор,...значения)

Запускает событие change и input после выбора всех предоставленных параметров. Если нет selector соответствия элемента <select> , метод выдает ошибку. 

frame.select('select#colors', 'blue'); // одиночный выбор
frame.select('select#colors', 'red', 'green', 'blue'); // множественный выбор

frame.setContent(html[,options]))

frame.tap(selector)

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

frame.title()

frame.type(селектор,text[,options]))

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

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

await frame.type('#mytextarea', 'Hello'); // Мгновенно набирает
await frame.type('#mytextarea', 'World', {delay: 100}); // Набирает медленнее, как пользователь

frame.url()

Возвращает урну рамы.

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

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

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

// ждем селектора
await page.waitFor('.foo');
// ждем 1 секунду
await page.waitFor(1000);
// ждем предиката
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]])).

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

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])

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

const [response] = await Promise.all([
  frame.waitForNavigation(), // Обещание навигации разрешается после завершения навигации
  frame.click('a.my-link'), // Нажатие на ссылку косвенно вызовет навигацию
]);

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

frame.waitForSelector(селектор[,опции]).

Подождите, пока на странице появится 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)

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

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[,опции]).

Подождите, пока 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();
})();

Класс:ExecutionContext

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

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

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

Если функция, переданная в 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.assessHandle(pageFunction[,...args]))

Единственное различие между 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; // Дескриптор глобального объекта.

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

const aHandle = await context.evaluateHandle('1 + 2'); // Дескриптор объекта "3".

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

const aHandle = await context.evaluateHandle(() => document.body);
const resultHandle = await context.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue()); // выводит внутренний HTML-код тела
await aHandle.dispose();
await resultHandle.dispose();

executionContext.frame()

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

executionContext.queryObjects(prototypeHandle)

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

// Создаем объект Map
await page.evaluate(() => window.map = new Map());
// Получаем дескриптор прототипа объекта Map
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Запрос всех экземпляров карты в массив
const mapInstances = await page.queryObjects(mapPrototype);
// Подсчитываем количество объектов карты в куче
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()

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

jsHandle.dispose()

Метод jsHandle.dispose перестает ссылаться на дескриптор элемента.

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

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

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

Examples: 

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

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

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

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

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

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

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

jsHandle.executionContext()

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

jsHandle.getProperties()

Метод возвращает карту с именами свойств в качестве ключей и экземплярами 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)

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

jsHandle.jsonValue()

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

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

Класс:ElementHandle

ElementHandle представляет собой элемент DOM на странице. ElementHandles можно создать с помощью метода 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, если дескриптор не удален . ElementHandles автоматически удаляются при переходе по их исходному фрейму.

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

elementHandle.$(selector)

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

elementHandle.$$(selector)

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

elementHandle.$$eval(селектор,функция pageFunction[,...args]))

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

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

Examples: 

<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(селектор,pageFunction[,...args]))

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

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

Examples: 

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)

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

expression должно иметь узел контекста , чтобы оценить должным образом: 

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

elementHandle.asElement()

elementHandle.boundingBox()

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

elementHandle.boxModel()

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

elementHandle.click%%([%%options])

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

elementHandle.contentFrame()

elementHandle.dispose()

Метод elementHandle.dispose перестает ссылаться на дескриптор элемента.

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

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

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

Examples: 

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

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

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

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

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

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

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

elementHandle.executionContext()

elementHandle.focus()

Вызывает фокус на элементе.

elementHandle.getProperties()

Метод возвращает карту с именами свойств в качестве ключей и экземплярами 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; // содержит elementHandles для всех дочерних элементов document.body

elementHandle.getProperty(propertyName)

Получает единственное свойство от objectHandle.

elementHandle.hover()

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

elementHandle.isIntersectingViewport()

elementHandle.jsonValue()

Возвращает JSON-представление объекта. JSON создается путем запуска JSON.stringify для объекта на странице и последующего JSON.parse в puppeteer.

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

elementHandle.press(key[,options]))

Фокусирует элемент, а затем использует keyboard.down и keyboard.up .

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

ПРИМЕЧАНИЕ. Клавиши-модификаторы elementHandle.press влияют на elementHandle.press . Удерживая нажатой Shift вы набираете текст в верхнем регистре.

elementHandle.screenshot%%([%%options])

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

elementHandle.select(...values)

Запускает событие change и input после выбора всех предоставленных параметров. Если нет selector соответствия элемента <select> , метод выдает ошибку. 

handle.select('blue'); // одиночный выбор
handle.select('red', 'green', 'blue'); // множественный выбор

elementHandle.tap()

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

elementHandle.toString()

elementHandle.type(text[,options]))

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

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

await elementHandle.type('Hello'); // Мгновенно набирает
await elementHandle.type('World', {delay: 100}); // Набирает медленнее, как пользователь

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

const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');

elementHandle.uploadFile(...filePaths)

Этот метод ожидает, что elementHandle укажет на элемент ввода .

class: HTTPRequest

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

Если в какой-то момент запрос не выполняется, то вместо события 'requestfinished' (и, возможно, вместо события response) 'requestfailed' событие requestfailed .

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

Если на запрос получен ответ 'redirect',то запрос успешно завершается событием 'requestfinished',и новый запрос выдается на перенаправленный url.

httpRequest.abort%%([%%errorCode])

Отменяет запрос. Чтобы использовать это, перехват запроса должен быть включен с помощью page.setRequestInterception . Если перехват запроса не включен, немедленно генерируется исключение.

httpRequest.continue%%([%%overrides])

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

await page.setRequestInterception(true);
page.on('request', request => {
  // Переопределить заголовки
  const headers = Object.assign({}, request.headers(), {
    foo: 'bar', // устанавливаем заголовок "foo"
    origin: undefined, // удаляем заголовок "origin"
  });
  request.continue({headers});
});

httpRequest.failure()

Метод возвращает значение null , если этот запрос не был неудачным, о чем сообщает событие requestfailed .

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

page.on('requestfailed', request => {
  console.log(request.url() + ' ' + request.failure().errorText);
});

httpRequest.frame()

httpRequest.headers()

httpRequest.isNavigationRequest()

Является ли этот запрос навигацией водительской рамы.

httpRequest.method()

httpRequest.postData()

httpRequest.redirectChain()

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()

Содержит тип ресурса запроса, как он был воспринят механизмом визуализации. ResourceType будет одним из следующих: document , stylesheet , image , media , font , script , texttrack , xhr , fetch , источник eventsource , websocket , manifest , other .

httpRequest.respond(response)

Выполняет запрос с заданным ответом. Чтобы использовать это, перехват запроса должен быть включен с помощью 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()

httpRequest.url()

class: HTTPResponse

Класс HTTPResponse представляет ответы, полученные страницей.

httpResponse.buffer()

httpResponse.frame()

httpResponse.fromCache()

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

httpResponse.fromServiceWorker()

Верно,если ответ был получен от работника сервисной службы.

httpResponse.headers()

httpResponse.json()

Этот метод будет сгенерирован, если тело ответа не может быть JSON.parse через JSON.parse .

httpResponse.ok()

Содержит логическое указание на то,была ли реакция успешной (состояние в диапазоне 200-299)или нет.

httpResponse.remoteAddress()

httpResponse.request()

httpResponse.securityDetails()

httpResponse.status()

Содержит код статуса ответа (например,200 для успеха).

httpResponse.statusText()

Содержит текст статуса ответа (например,обычно «ОК» для успеха).

httpResponse.text()

httpResponse.url()

Содержит URL ответа.

Класс:SecurityDetails

Класс SecurityDetails представляет сведения о безопасности при получении ответа по защищенному соединению.

securityDetails.issuer()

securityDetails.protocol()

securityDetails.subjectAlternativeNames()

securityDetails.subjectName()

securityDetails.validFrom()

securityDetails.validTo()

Класс:Цель

target.browser()

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

target.browserContext()

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

target.createCDPSession()

Создает сеанс протокола Chrome Devtools,прикрепленный к цели.

target.opener()

Получите цель, открывшую эту цель. Целевые объекты верхнего уровня возвращают значение null .

target.page()

Если цель не относится к типу «page» или «background_page» , возвращается значение null .

target.type()

Определяет, что это за цель. Может быть «page» , "background_page" , «service_worker» , «shared_worker» , «browser» или «other» .

target.url()

target.worker()

Если цель не относится к типу «service_worker» или «shared_worker» , возвращается значение null .

Класс:CDPSession

В CDPSession экземпляры привыкли говорить сырец Chrome DevTools протокол:

Полезные ссылки: 

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()

Отсоединяет cdpSession от цели.После отсоединения объект cdpSession не будет испускать никаких событий и не может использоваться для отправки сообщений.

cdpSession.send(method[, ...paramArgs])

Класс:Покрытие

Coverage собирает информацию о тех частях JavaScript и CSS,которые использовались на странице.

Пример использования JavaScript и CSS-покрытия для получения процента первоначально выполненного кода: 

// Включение покрытия как JavaScript, так и CSS
await Promise.all([
  page.coverage.startJSCoverage(),
  page.coverage.startCSSCoverage()
]);
// Переходим на страницу
await page.goto('https://example.com');
// Отключить покрытие JavaScript и CSS
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}%`);

Чтобы вывести покрытие в форме, доступной для Стамбула , см. Puppeteer-to-istanbul .

coverage.startCSSCoverage%%([%%options])

coverage.startJSCoverage%%([%%options])

ПРИМЕЧАНИЕ. Анонимные сценарии - это сценарии, не связанные с URL-адресом. Это скрипты, которые динамически создаются на странице с помощью eval или new Function . Если для параметра reportAnonymousScripts установлено значение true , анонимные скрипты будут иметь __puppeteer_evaluation_script__ в качестве URL-адреса.

coverage.stopCSSCoverage()

ПРИМЕЧАНИЕ. CSS Coverage не включает динамически вводимые теги стиля без sourceURL.

coverage.stopJSCoverage()

ПРИМЕЧАНИЕ. Покрытие JavaScript по умолчанию не включает анонимные сценарии. Однако сообщается о скриптах с исходными URL.

Класс:TimeoutError

TimeoutError генерируется всякий раз, когда определенные операции завершаются из-за тайм-аута, например page.waitForSelector (selector [, options]) или puppeteer.launch ([options]) .

class: EventEmitter

Небольшой класс EventEmitter, поддерживаемый Mitt .

eventEmitter.addListener(event, handler)

Этот метод идентичен on и поддерживается для совместимости с EventEmitter узла. Мы рекомендуем использовать on умолчанию.

eventEmitter.emit(event, [eventData])

eventEmitter.listenerCount(event)

eventEmitter.off(event, handler)

eventEmitter.on(event, handler)

eventEmitter.once(event, handler)

eventEmitter.removeAllListeners%%([%%event])

eventEmitter.removeListener(event, handler)

Этот метод идентичен off и поддерживается для совместимости с EventEmitter узла. Мы рекомендуем по умолчанию off .

interface: CustomQueryHandler

Содержит две функции queryOne и queryAll , которые можно зарегистрировать как альтернативные стратегии запросов. Функции queryOne и queryAll выполняются в контексте страницы. queryOne должен принимать в качестве аргумента Element и строку селектора и возвращать один Element или значение null , если элемент не найден. queryAll принимает те же аргументы, но вместо этого должен возвращать NodeList<Element> или Array<Element> со всеми элементами, соответствующими заданному селектору запроса.