puppeteer-extra-plugin
Advanced tools
puppeteer-extra-plugin - npm Package Compare versions
Comparing version 2.1.1 to 3.0.2
| { | ||
| "name": "puppeteer-extra-plugin", | ||
| "version": "2.1.1", | ||
| "version": "3.0.2", | ||
| "description": "Base class for puppeteer-extra plugins.", | ||
| "main": "index.js", | ||
| "main": "dist/index.cjs.js", | ||
| "module": "dist/index.esm.js", | ||
| "typings": "dist/index.d.ts", | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "repository": "berstend/puppeteer-extra", | ||
| "homepage": "https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin", | ||
| "author": "berstend", | ||
| "license": "MIT", | ||
| "scripts": { | ||
| "docs": "update-markdown-jsdoc", | ||
| "test": "ava -v && standard" | ||
| "clean": "rm -rf dist/*", | ||
| "build": "yarn clean && tsc --module commonjs && rollup -c rollup.config.ts", | ||
| "docs": "typedoc --module commonjs --readme none --excludeExternals --excludePrivate --target ES6 --theme markdown --out docs --mode file src", | ||
| "test": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' ava -v src/**.test.ts", | ||
| "prepublishOnly": "npm run test && npm run docs && npm run build" | ||
| }, | ||
| "engines": { | ||
| "node": ">=8" | ||
| "node": ">=9.11.2" | ||
| }, | ||
| "ava": { | ||
| "compileEnhancements": false, | ||
| "extensions": [ | ||
| "ts" | ||
| ], | ||
| "require": [ | ||
| "ts-node/register" | ||
| ] | ||
| }, | ||
| "prettier": { | ||
| "printWidth": 80, | ||
| "semi": false, | ||
| "singleQuote": true | ||
| }, | ||
| "keywords": [ | ||
@@ -27,6 +50,20 @@ "puppeteer", | ||
| "devDependencies": { | ||
| "ava": "^0.25.0", | ||
| "@types/debug": "^4.1.0", | ||
| "@types/node": "^10.12.23", | ||
| "@types/puppeteer": "^1.12.1", | ||
| "ava": "^1.2.1", | ||
| "lodash.camelcase": "^4.3.0", | ||
| "puppeteer": "next", | ||
| "standard": "^11.0.0", | ||
| "update-markdown-jsdoc": "^1.0.6" | ||
| "rollup": "^1.1.2", | ||
| "rollup-plugin-commonjs": "^9.2.0", | ||
| "rollup-plugin-node-resolve": "^4.0.0", | ||
| "rollup-plugin-sourcemaps": "^0.4.2", | ||
| "rollup-plugin-typescript2": "^0.19.2", | ||
| "ts-node": "^8.0.2", | ||
| "tslint": "^5.12.1", | ||
| "tslint-config-prettier": "^1.18.0", | ||
| "tslint-config-standard": "^8.0.1", | ||
| "typedoc": "^0.14.2", | ||
| "typedoc-plugin-markdown": "^1.1.26", | ||
| "typescript": "^3.3.3" | ||
| }, | ||
@@ -40,3 +77,3 @@ "dependencies": { | ||
| }, | ||
| "gitHead": "2783eda8b71df3eb3e360614302c08007d467628" | ||
| "gitHead": "d56b0bff08e963c83e1b17008f29133326aadeaa" | ||
| } |
499
readme.md
@@ -9,500 +9,25 @@ # puppeteer-extra-plugin | ||
| ## API | ||
| <!-- Generated by documentation.js. Update this documentation by updating the source code. --> | ||
| #### Table of Contents | ||
| - [PuppeteerExtraPlugin](#puppeteerextraplugin) | ||
| - [name](#name) | ||
| - [defaults](#defaults) | ||
| - [requirements](#requirements) | ||
| - [dependencies](#dependencies) | ||
| - [data](#data) | ||
| - [opts](#opts) | ||
| - [debug](#debug) | ||
| - [beforeLaunch](#beforelaunch) | ||
| - [afterLaunch](#afterlaunch) | ||
| - [beforeConnect](#beforeconnect) | ||
| - [afterConnect](#afterconnect) | ||
| - [onBrowser](#onbrowser) | ||
| - [onTargetCreated](#ontargetcreated) | ||
| - [onPageCreated](#onpagecreated) | ||
| - [onTargetChanged](#ontargetchanged) | ||
| - [onTargetDestroyed](#ontargetdestroyed) | ||
| - [onDisconnected](#ondisconnected) | ||
| - [onClose](#onclose) | ||
| - [onPluginRegistered](#onpluginregistered) | ||
| - [getDataFromPlugins](#getdatafromplugins) | ||
| ### [PuppeteerExtraPlugin](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L47-L505) | ||
| Base class for `puppeteer-extra` plugins. | ||
| Provides convenience methods to avoid boilerplate. | ||
| Provides convenience lifecycle methods to avoid boilerplate. | ||
| All common `puppeteer` browser events will be bound to | ||
| the plugin instance, if a respectively named class member is found. | ||
| ## API | ||
| Please refer to the [puppeteer API documentation] as well. | ||
| I've refactored the code to TypeScript and the [generated typedoc API documentation can be found here](./docs). | ||
| [puppeteer api documentation]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md | ||
| Unfortunately the generated documentation is currently not as nice as the former documentation.js one but I'm working on it. :-) | ||
| Type: `function (opts)` | ||
| ## Changelog | ||
| - `opts` (optional, default `{}`) | ||
| ### `v3.1.0` | ||
| Example: | ||
| - Now written in TypeScript 🎉 | ||
| - **Breaking change:** Now using a named export: | ||
| ```javascript | ||
| // hello-world-plugin.js | ||
| ```js | ||
| // Before | ||
| 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() | ||
| })() | ||
| // After (>= v3.1.0) | ||
| const { PuppeteerExtraPlugin } = require('puppeteer-extra-plugin') | ||
| ``` | ||
| * * * | ||
| #### [name](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L71-L71) | ||
| Plugin name (required). | ||
| Convention: | ||
| - Package: `puppeteer-extra-plugin-anonymize-ua` | ||
| - Name: `anonymize-ua` | ||
| Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | ||
| Example: | ||
| ```javascript | ||
| get name () { return 'anonymize-ua' } | ||
| ``` | ||
| * * * | ||
| #### [defaults](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L95-L95) | ||
| - **See: opts** | ||
| Plugin defaults (optional). | ||
| If defined will be ([deep-](https://github.com/jonschlinkert/merge-deep))merged with the (optional) user supplied options (supplied during plugin instantiation). | ||
| The result of merging defaults with user supplied options can be accessed through `this.opts`. | ||
| Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | ||
| Example: | ||
| ```javascript | ||
| get defaults () { | ||
| return { | ||
| stripHeadless: true, | ||
| makeWindows: true, | ||
| customFn: null | ||
| } | ||
| } | ||
| // Users can overwrite plugin defaults during instantiation: | ||
| puppeteer.use(require('puppeteer-extra-plugin-foobar')({ makeWindows: false })) | ||
| ``` | ||
| * * * | ||
| #### [requirements](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L123-L123) | ||
| 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. | ||
| Type: [Set](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | ||
| Example: | ||
| ```javascript | ||
| get requirements () { | ||
| return new Set(['runLast', 'dataFromPlugins']) | ||
| } | ||
| ``` | ||
| * * * | ||
| #### [dependencies](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L138-L138) | ||
| Plugin dependencies (optional). | ||
| Missing plugins will be required() by puppeteer-extra. | ||
| Type: [Set](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | ||
| Example: | ||
| ```javascript | ||
| get dependencies () { | ||
| return new Set(['user-preferences']) | ||
| } | ||
| // Will ensure the 'puppeteer-extra-plugin-user-preferences' plugin is loaded. | ||
| ``` | ||
| * * * | ||
| #### [data](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L173-L173) | ||
| - **See: getDataFromPlugins** | ||
| Plugin data (optional). | ||
| Plugins can expose data (an array of objects), which in turn can be consumed by other plugins, | ||
| that list the `dataFromPlugins` requirement (by using `this.getDataFromPlugins()`). | ||
| Convention: `[ {name: 'Any name', value: 'Any value'} ]` | ||
| Type: `function ()` | ||
| Example: | ||
| ```javascript | ||
| // plugin1.js | ||
| get data () { | ||
| return [ | ||
| { | ||
| name: 'userPreferences', | ||
| value: { foo: 'bar' } | ||
| }, | ||
| { | ||
| name: 'userPreferences', | ||
| value: { hello: 'world' } | ||
| } | ||
| ] | ||
| // plugin2.js | ||
| get requirements () { return new Set(['dataFromPlugins']) } | ||
| async beforeLaunch () { | ||
| const prefs = this.getDataFromPlugins('userPreferences').map(d => d.value) | ||
| this.debug(prefs) // => [ { foo: 'bar' }, { hello: 'world' } ] | ||
| } | ||
| ``` | ||
| * * * | ||
| #### [opts](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L191-L191) | ||
| - **See: defaults** | ||
| Access the plugin options (usually the `defaults` merged with user defined options) | ||
| To skip the auto-merging of defaults with user supplied opts don't define a `defaults` | ||
| property and set the `this._opts` Object in your plugin constructor directly. | ||
| Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | ||
| Example: | ||
| ```javascript | ||
| get defaults () { return { foo: "bar" } } | ||
| async onPageCreated (page) { | ||
| this.debug(this.opts.foo) // => bar | ||
| } | ||
| ``` | ||
| * * * | ||
| #### [debug](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L211-L211) | ||
| Convenience debug logger based on the [debug] module. | ||
| Will automatically namespace the logging output to the plugin package name. | ||
| [debug]: https://www.npmjs.com/package/debug | ||
| ```bash | ||
| # 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 | ||
| ``` | ||
| Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function) | ||
| Example: | ||
| ```javascript | ||
| this.debug('hello world') | ||
| // will output e.g. 'puppeteer-extra-plugin:anonymize-ua hello world' | ||
| ``` | ||
| * * * | ||
| #### [beforeLaunch](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L231-L231) | ||
| 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. | ||
| Type: `function (options)` | ||
| - `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Puppeteer launch options | ||
| Example: | ||
| ```javascript | ||
| async beforeLaunch (options) { | ||
| if (this.opts.flashPluginPath) { | ||
| options.args.push(`--ppapi-flash-path=${this.opts.flashPluginPath}`) | ||
| } | ||
| } | ||
| ``` | ||
| * * * | ||
| #### [afterLaunch](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L261-L261) | ||
| 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: | ||
| ```es6 | ||
| const fancyPlugin = require('puppeteer-extra-plugin-fancy')() | ||
| puppeteer.use(fancyPlugin) | ||
| const browser = await puppeteer.launch() | ||
| await fancyPlugin.killBrowser(browser) | ||
| ``` | ||
| Type: `function (browser, opts)` | ||
| - `browser` **Puppeteer.Browser** The `puppeteer` browser instance. | ||
| - `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`) | ||
| - `opts.options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Puppeteer launch options used. | ||
| Example: | ||
| ```javascript | ||
| async afterLaunch (browser, opts) { | ||
| this.debug('browser has been launched', opts.options) | ||
| } | ||
| ``` | ||
| * * * | ||
| #### [beforeConnect](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L274-L274) | ||
| 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. | ||
| Type: `function (options)` | ||
| - `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Puppeteer connect options | ||
| * * * | ||
| #### [afterConnect](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L286-L286) | ||
| 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. | ||
| Type: `function (browser, opts)` | ||
| - `browser` **Puppeteer.Browser** The `puppeteer` browser instance. | ||
| - `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`) | ||
| - `opts.options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Puppeteer connect options used. | ||
| * * * | ||
| #### [onBrowser](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L300-L300) | ||
| 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. | ||
| Type: `function (browser)` | ||
| - `browser` **Puppeteer.Browser** The `puppeteer` browser instance. | ||
| * * * | ||
| #### [onTargetCreated](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L311-L311) | ||
| 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()`. | ||
| Type: `function (target)` | ||
| - `target` **Puppeteer.Target** | ||
| * * * | ||
| #### [onPageCreated](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L332-L332) | ||
| 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()`. | ||
| Type: `function (target)` | ||
| - `target` **Puppeteer.Target** | ||
| Example: | ||
| ```javascript | ||
| 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](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L343-L343) | ||
| 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()`. | ||
| Type: `function (target)` | ||
| - `target` **Puppeteer.Target** | ||
| * * * | ||
| #### [onTargetDestroyed](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L354-L354) | ||
| 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()`. | ||
| Type: `function (target)` | ||
| - `target` **Puppeteer.Target** | ||
| * * * | ||
| #### [onDisconnected](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L363-L363) | ||
| 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 | ||
| Type: `function ()` | ||
| * * * | ||
| #### [onClose](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L377-L377) | ||
| **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. | ||
| > Note: Might be called multiple times on exit. | ||
| > | ||
| > Note: This only includes browser instances created through `.launch()`. | ||
| Type: `function ()` | ||
| * * * | ||
| #### [onPluginRegistered](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L384-L384) | ||
| After the plugin has been registered in `puppeteer-extra`. | ||
| Normally right after `puppeteer.use(plugin)` is called | ||
| Type: `function ()` | ||
| * * * | ||
| #### [getDataFromPlugins](https://github.com/berstend/puppeteer-extra/blob/db57ea66cf10d407cf63af387892492e495a84f2/packages/puppeteer-extra-plugin/index.js#L397-L397) | ||
| - **See: data** | ||
| - **See: requirements** | ||
| Helper method to retrieve `data` objects from other plugins. | ||
| A plugin needs to state the `dataFromPlugins` requirement | ||
| in order to use this method. Will be mapped to `puppeteer.getPluginData`. | ||
| Type: `function (name)` | ||
| - `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Filter data by `name` property (optional, default `null`) | ||
| * * * |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No website
QualityPackage does not have a website.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by190.77%
131017
- Number of package files
- increased by116.67%
13
- Lines of code
- increased by292.27%
2181
- Number of low quality alerts
- decreased by-100%
0
Worsened metrics
- Dev dependency count
- increased by350%
18
- Number of lines in readme file
- decreased by-93.5%
33
- Number of medium supply chain risk alerts
- increased byInfinity%
1
No dependency changes