Puppeteer-extra-plugin-notbody NPM

puppeteer-extra-plugin

Installation

yarn add puppeteer-extra-plugin

Changelog

Now written in TypeScript 🎉
Breaking change: Now using a named export:

// Before
const PuppeteerExtraPlugin = require('puppeteer-extra-plugin')

// After (>= v3.0.1)
const { PuppeteerExtraPlugin } = require('puppeteer-extra-plugin')

API

puppeteer-extra-plugin [](https://extra.community) [](https://www.npmjs.com/package/puppeteer-extra-plugin)

class: PuppeteerExtraPlugin

opts PluginOptions?

Base class for puppeteer-extra plugins.

Provides convenience methods to avoid boilerplate.

All common puppeteer browser events will be bound to the plugin instance, if a respectively named class member is found.

Please refer to the puppeteer API documentation as well.

Example:

// hello-world-plugin.js
const { PuppeteerExtraPlugin } = require('puppeteer-extra-plugin')

class Plugin extends PuppeteerExtraPlugin {
  constructor(opts = {}) {
    super(opts)
  }

  get name() {
    return 'hello-world'
  }

  async onPageCreated(page) {
    this.debug('page created', page.url())
    const ua = await page.browser().userAgent()
    this.debug('user agent', ua)
  }
}

module.exports = function (pluginConfig) {
  return new Plugin(pluginConfig)
}

// foo.js
const puppeteer = require('puppeteer-extra')
puppeteer.use(require('./hello-world-plugin')())
;(async () => {
  const browser = await puppeteer.launch({ headless: false })
  const page = await browser.newPage()
  await page.goto('http://example.com', { waitUntil: 'domcontentloaded' })
  await browser.close()
})()

.name

Type: string

Plugin name (required).

Convention:

Package: puppeteer-extra-plugin-anonymize-ua
Name: anonymize-ua

Example:

get name () { return 'anonymize-ua' }

.requirements

Type: PluginRequirements

Plugin requirements (optional).

Signal certain plugin requirements to the base class and the user.

Currently supported:

launch
- If the plugin only supports locally created browser instances (no puppeteer.connect()), will output a warning to the user.
headful
- If the plugin doesn't work in headless: true mode, will output a warning to the user.
dataFromPlugins
- In case the plugin requires data from other plugins. will enable usage of this.getDataFromPlugins().
runLast
- In case the plugin prefers to run after the others. Useful when the plugin needs data from others.

Example:

get requirements () {
  return new Set(['runLast', 'dataFromPlugins'])
}

.dependencies

Type: PluginDependencies

Plugin dependencies (optional).

Missing plugins will be required() by puppeteer-extra.

Example:

get dependencies () {
  return new Set(['user-preferences'])
}
// Will ensure the 'puppeteer-extra-plugin-user-preferences' plugin is loaded.

.debug

Type: Debugger

Convenience debug logger based on the debug module. Will automatically namespace the logging output to the plugin package name.

# toggle output using environment variables
DEBUG=puppeteer-extra-plugin:<plugin_name> node foo.js
# to debug all the things:
DEBUG=puppeteer-extra,puppeteer-extra-plugin:* node foo.js

Example:

this.debug('hello world')
// will output e.g. 'puppeteer-extra-plugin:anonymize-ua hello world'

.beforeLaunch(options)

options any Puppeteer launch options

Before a new browser instance is created/launched.

Can be used to modify the puppeteer launch options by modifying or returning them.

Plugins using this method will be called in sequence to each be able to update the launch options.

Example:

async beforeLaunch (options) {
  if (this.opts.flashPluginPath) {
    options.args.push(`--ppapi-flash-path=${this.opts.flashPluginPath}`)
  }
}

.afterLaunch(browser, opts)

browser Puppeteer.Browser The puppeteer browser instance.
opts (optional, default {options:({}as Puppeteer.LaunchOptions)})

After the browser has launched.

Note: Don't assume that there will only be a single browser instance during the lifecycle of a plugin. It's possible that pupeeteer.launch will be called multiple times and more than one browser created. In order to make the plugins as stateless as possible don't store a reference to the browser instance in the plugin but rather consider alternatives.

E.g. when using onPageCreated you can get a browser reference by using page.browser().

Alternatively you could expose a class method that takes a browser instance as a parameter to work with:

const fancyPlugin = require('puppeteer-extra-plugin-fancy')()
puppeteer.use(fancyPlugin)
const browser = await puppeteer.launch()
await fancyPlugin.killBrowser(browser)

Example:

async afterLaunch (browser, opts) {
  this.debug('browser has been launched', opts.options)
}

.beforeConnect(options)

options Object Puppeteer connect options

Before connecting to an existing browser instance.

Can be used to modify the puppeteer connect options by modifying or returning them.

Plugins using this method will be called in sequence to each be able to update the launch options.

.afterConnect(browser, opts)

browser Puppeteer.Browser The puppeteer browser instance.
opts Object (optional, default {})
- opts.options Object Puppeteer connect options used.

After connecting to an existing browser instance.

Note: Don't assume that there will only be a single browser instance during the lifecycle of a plugin.

.onBrowser(browser, opts)

browser Puppeteer.Browser The puppeteer browser instance.
opts any

Returns: Promise<void>

Called when a browser instance is available.

This applies to both puppeteer.launch() and puppeteer.connect().

Convenience method created for plugins that need access to a browser instance and don't mind if it has been created through launch or connect.

Note: Don't assume that there will only be a single browser instance during the lifecycle of a plugin.

.onTargetCreated(target)

target Puppeteer.Target

Called when a target is created, for example when a new page is opened by window.open or browser.newPage.

Note: This includes target creations in incognito browser contexts.
Note: This includes browser instances created through .launch() as well as .connect().

.onPageCreated(page, target)

page Puppeteer.Page
target Puppeteer.Target

Same as onTargetCreated but prefiltered to only contain Pages, for convenience.

Note: This includes page creations in incognito browser contexts.
Note: This includes browser instances created through .launch() as well as .connect().

Example:

async onPageCreated (page) {
  let ua = await page.browser().userAgent()
  if (this.opts.stripHeadless) {
    ua = ua.replace('HeadlessChrome/', 'Chrome/')
  }
  this.debug('new ua', ua)
  await page.setUserAgent(ua)
}

.onTargetChanged(target)

target Puppeteer.Target

Called when the url of a target changes.

Note: This includes target changes in incognito browser contexts.
Note: This includes browser instances created through .launch() as well as .connect().

.onTargetDestroyed(target)

target Puppeteer.Target

Called when a target is destroyed, for example when a page is closed.

Note: This includes target destructions in incognito browser contexts.
Note: This includes browser instances created through .launch() as well as .connect().

.onDisconnected()

Called when Puppeteer gets disconnected from the Chromium instance.

This might happen because of one of the following:

Chromium is closed or crashed
The browser.disconnect method was called

.onClose()

Deprecated: Since puppeteer v1.6.0 onDisconnected has been improved and should be used instead of onClose.

In puppeteer < v1.6.0 onDisconnected was not catching all exit scenarios. In order for plugins to clean up properly (e.g. deleting temporary files) the onClose method had been introduced.