puppeteer-extra-plugin - npm Package Compare versions

Comparing version 2.0.1 to 2.0.2

index.js

 'use strict'
 
 const debug = require('debug')
+const merge = require('merge-deep')
 
@@ -21,5 +22,3 @@ /**
  * class Plugin extends PuppeteerExtraPlugin {
- *   constructor (opts = { }) {
- *     super(opts)
- *   }
+ *   constructor (opts = { }) { super(opts) }
  *
@@ -50,5 +49,11 @@ *   get name () { return 'hello-world' }
 class PuppeteerExtraPlugin {
-  constructor () {
+  constructor (opts = {}) {
     this._debugBase = debug(`puppeteer-extra-plugin:base:${this.name}`)
     this._childClassMembers = []
+
+    this._opts = {}
+    // Deep merge opts with defaults, if available
+    if (Object.keys(this.defaults).length) {
+      this._opts = merge(this.defaults, opts)
+    }
   }
@@ -71,2 +76,26 @@
   /**
+   * 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`.
+   *
+   * @member {Object}
+   * @see opts
+   *
+   * @example
+   * 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 }))
+   */
+  get defaults () { return { } }
+
+  /**
    * Plugin requirements (optional).
@@ -147,2 +176,20 @@ *
   /**
+   * 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.
+   *
+   * @member {Object}
+   * @see defaults
+   *
+   * @example
+   * get defaults () { return { foo: "bar" } }
+   *
+   * async onPageCreated (page) {
+   *   this.debug(this.opts.foo) // => bar
+   * }
+   */
+  get opts () { return this._opts }
+
+  /**
    *  Convenience debug logger based on the [debug] module.
@@ -173,2 +220,9 @@ *  Will automatically namespace the logging output to the plugin package name.
    *
+   * @example
+   * async beforeLaunch (options) {
+   *   if (this.opts.flashPluginPath) {
+   *     options.args.push(`--ppapi-flash-path=${this.opts.flashPluginPath}`)
+   *   }
+   * }
+   *
    * @param  {Object} options - Puppeteer launch options
@@ -182,4 +236,25 @@ * @return {Object=}
    *
+   * 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)
+   * ```
+   *
    * @param  {Puppeteer.Browser} browser - The `puppeteer` browser instance.
    * @param  {Object=} options - The launch options used.
+   *
+   * @example
+   * async afterLaunch (browser, options) {
+   *   this.debug('browser has been launched', options)
+   * }
    */
@@ -191,3 +266,3 @@ async afterLaunch (browser, options = {}) { }
    *
-   * > NOTE This includes target creations in incognito browser contexts.
+   * > Note: This includes target creations in incognito browser contexts.
    *
@@ -201,5 +276,15 @@ * @param  {Puppeteer.Target} target
    *
-   * > NOTE: This includes target creations in incognito browser contexts.
+   * > Note: This includes page creations in incognito browser contexts.
    *
    * @param  {Puppeteer.Target} target
+   *
+   * @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)
+   * }
    */
@@ -211,3 +296,3 @@ async onPageCreated (target) { }
    *
-   * > NOTE: This includes target changes in incognito browser contexts.
+   * > Note: This includes target changes in incognito browser contexts.
    *
@@ -221,3 +306,3 @@ * @param  {Puppeteer.Target} target
    *
-   * > NOTE: This includes target destructions in incognito browser contexts.
+   * > Note: This includes target destructions in incognito browser contexts.
    *
@@ -329,3 +414,4 @@ * @param  {Puppeteer.Target} target
     if (target.type() === 'page') {
-      await this.onPageCreated(await target.page())
+      const page = await target.page()
+      await this.onPageCreated(page)
     }
@@ -332,0 +418,0 @@ }

package.json

 {
   "name": "puppeteer-extra-plugin",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Base class for puppeteer-extra plugins.",
@@ -11,3 +11,3 @@ "main": "index.js",
     "docs": "update-markdown-jsdoc",
-    "test": "standard"
+    "test": "ava -v && standard"
   },
@@ -34,4 +34,5 @@ "engines": {
   "dependencies": {
-    "debug": "^3.1.0"
+    "debug": "^3.1.0",
+    "merge-deep": "^3.0.1"
   }
 }

readme.md

 # puppeteer-extra-plugin
 
-### Install
+## Installation
 
@@ -9,13 +9,15 @@ ```bash
 
-### API
+## API
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-##### Table of Contents
+#### Table of Contents
 
 -   [PuppeteerExtraPlugin](#puppeteerextraplugin)
     -   [name](#name)
+    -   [defaults](#defaults)
     -   [requirements](#requirements)
     -   [dependencies](#dependencies)
     -   [data](#data)
+    -   [opts](#opts)
     -   [debug](#debug)
@@ -33,3 +35,3 @@ -   [beforeLaunch](#beforelaunch)
 
-#### [PuppeteerExtraPlugin](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L48-L351)
+### [PuppeteerExtraPlugin](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L47-L437)
 
@@ -47,4 +49,6 @@ Base class for `puppeteer-extra` plugins.
 
-Type: `function ()`
+Type: `function (opts)`
 
+-   `opts`   (optional, default `{}`)
+
 Example:
@@ -57,5 +61,3 @@
 class Plugin extends PuppeteerExtraPlugin {
-  constructor (opts = { }) {
-    super(opts)
-  }
+  constructor (opts = { }) { super(opts) }
 
@@ -88,3 +90,3 @@ get name () { return 'hello-world' }
 
-##### [name](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L66-L66)
+#### [name](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L71-L71)
 
@@ -108,4 +110,33 @@ Plugin name (required).
 
-##### [requirements](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L91-L91)
+#### [defaults](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/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/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L120-L120)
+
 Plugin requirements (optional).
@@ -139,3 +170,3 @@
 
-##### [dependencies](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L106-L106)
+#### [dependencies](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L135-L135)
 
@@ -159,3 +190,3 @@ Plugin dependencies (optional).
 
-##### [data](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L141-L141)
+#### [data](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L170-L170)
 
@@ -200,4 +231,27 @@ -   **See: getDataFromPlugins**
 
-##### [debug](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L161-L161)
+#### [opts](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L188-L188)
 
+-   **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/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L208-L208)
+
 Convenience debug logger based on the [debug] module.
@@ -226,3 +280,3 @@ Will automatically namespace the logging output to the plugin package name.
 
-##### [beforeLaunch](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L172-L172)
+#### [beforeLaunch](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L226-L226)
 
@@ -238,8 +292,34 @@ Can be used to modify the puppeteer launch options by modifying or returning them.
 
+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/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L180-L180)
+#### [afterLaunch](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L255-L255)
 
 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, options)`
@@ -250,9 +330,17 @@
 
+Example:
+
+```javascript
+async afterLaunch (browser, options) {
+  this.debug('browser has been launched', options)
+}
+```
+
 * * *
 
-##### [onTargetCreated](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L189-L189)
+#### [onTargetCreated](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L264-L264)
 
 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 target creations in incognito browser contexts.
 
@@ -265,7 +353,7 @@ Type: `function (target)`
 
-##### [onPageCreated](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L198-L198)
+#### [onPageCreated](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L283-L283)
 
 Same as `onTargetCreated` but prefiltered to only contain Pages, for convenience.
 
-> NOTE: This includes target creations in incognito browser contexts.
+> Note: This includes page creations in incognito browser contexts.
 
@@ -276,9 +364,22 @@ Type: `function (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/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L207-L207)
+#### [onTargetChanged](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L292-L292)
 
 Called when the url of a target changes.
 
-> NOTE: This includes target changes in incognito browser contexts.
+> Note: This includes target changes in incognito browser contexts.
 
@@ -291,7 +392,7 @@ Type: `function (target)`
 
-##### [onTargetDestroyed](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L216-L216)
+#### [onTargetDestroyed](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L301-L301)
 
 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 target destructions in incognito browser contexts.
 
@@ -304,3 +405,3 @@ Type: `function (target)`
 
-##### [onDisconnected](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L224-L224)
+#### [onDisconnected](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L309-L309)
 
@@ -317,3 +418,3 @@ Called when Puppeteer gets disconnected from the Chromium instance.
 
-##### [onClose](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L233-L233)
+#### [onClose](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L318-L318)
 
@@ -330,3 +431,3 @@ Sometimes `onDisconnected` is not catching all exit scenarios.
 
-##### [onPluginRegistered](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L240-L240)
+#### [onPluginRegistered](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L325-L325)
 
@@ -341,3 +442,3 @@ After the plugin has been registered in `puppeteer-extra`.
 
-##### [getDataFromPlugins](https://github.com/berstend/puppeteer-extra/blob/39bb3948016ab4afc7e6f31459828035c8e8c65c/packages/puppeteer-extra-plugin/index.js#L253-L253)
+#### [getDataFromPlugins](https://github.com/berstend/puppeteer-extra/blob/139d9ecf97a46dc383adede213e1a4c707160dca/packages/puppeteer-extra-plugin/index.js#L338-L338)
 
@@ -344,0 +445,0 @@ -   **See: data**

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

30262

increased by43.43%

Number of package files

4

increased by33.33%

Lines of code

491

increased by49.7%

Number of lines in readme file

439

increased by29.88%

Worsened metrics

Dependency count

2

increased by100%

Dependency changes

• + Addedmerge-deep@^3.0.1

• + Addedarr-union@3.1.0(transitive)

• + Addedclone-deep@0.2.4(transitive)

• + Addedfor-in@0.1.81.0.2(transitive)

• + Addedfor-own@0.1.5(transitive)

• + Addedis-buffer@1.1.6(transitive)

• + Addedis-extendable@0.1.1(transitive)

• + Addedis-plain-object@2.0.4(transitive)

• + Addedisobject@3.0.1(transitive)

• + Addedkind-of@2.0.13.2.2(transitive)

• + Addedlazy-cache@0.2.71.0.4(transitive)

• + Addedmerge-deep@3.0.3(transitive)

• + Addedmixin-object@2.0.1(transitive)

• + Addedshallow-clone@0.1.2(transitive)