puppeteer-extra-plugin-devtools

A plugin for puppeteer-extra.

Installation

yarn add puppeteer-extra-plugin-devtools

Purpose

Make puppeteer browser debugging possible from anywhere.

• Creates a secure tunnel to make the devtools frontend (incl. screencasting) accessible from the public internet
• Works for both headless and headful puppeteer instances, as well as within docker containers
• Uses the already existing DevTools Protocol websocket connection from puppeteer
• Features some convenience functions for using the devtools frontend locally

Magic

Quickstart

const puppeteer = require('puppeteer-extra')
const devtools = require('puppeteer-extra-plugin-devtools')()
puppeteer.use(devtools)

puppeteer
  .launch({ headless: true, defaultViewport: null })
  .then(async browser => {
    console.log('Start')
    const tunnel = await devtools.createTunnel(browser)
    console.log(tunnel.url)

    const page = await browser.newPage()
    await page.goto('https://example.com')
    console.log('All setup.')
  })

API

Table of Contents

• Plugin
  • createTunnel
  • setAuthCredentials
  • getLocalDevToolsUrl
• Tunnel
  • url
  • getUrlForPage
  • close

Plugin

Extends: PuppeteerExtraPlugin

As the tunnel page is public the plugin will require basic auth.

You can set your own credentials using opts or setAuthCredentials().

If you don't specify basic auth credentials the plugin will generate a password and print it to STDOUT.

opts

Type: function (opts)

• opts Object Options (optional, default {})
  • opts.auth Object? Basic auth credentials for the public page
    • opts.auth.user string? Username (default: 'user')
    • opts.auth.pass string? Password (will be generated if not provided)
  • opts.prefix Object? The prefix to use for the localtunnel.me subdomain (default: 'devtools-tunnel')
  • opts.localtunnel Object? Advanced options to pass to localtunnel

Example:

const puppeteer = require('puppeteer-extra')
const devtools = require('puppeteer-extra-plugin-devtools')({
  auth: { user: 'francis', pass: 'president' }
})
puppeteer.use(devtools)

puppeteer.launch().then(async browser => {
  console.log('tunnel url:', (await devtools.createTunnel(browser)).url)
  // => tunnel url: https://devtools-tunnel-n9aogqwx3d.localtunnel.me
})

createTunnel

Create a new public tunnel.

Supports multiple browser instances (will create a new tunnel for each).

Type: function (browser): Tunnel

• browser Puppeteer.Browser The browser to create the tunnel for (there can be multiple)

Example:

const puppeteer = require('puppeteer-extra')
const devtools = require('puppeteer-extra-plugin-devtools')()
devtools.setAuthCredentials('bob', 'swordfish')
puppeteer.use(devtools)
;(async () => {
  const browserFleet = await Promise.all(
    [...Array(3)].map(slot => puppeteer.launch())
  )
  for (const [index, browser] of browserFleet.entries()) {
    const { url } = await devtools.createTunnel(browser)
    console.info(`Browser ${index}'s devtools frontend can be found at: ${url}`)
  }
})()
// =>
// Browser 0's devtools frontend can be found at: https://devtools-tunnel-fzenb4zuav.localtunnel.me
// Browser 1's devtools frontend can be found at: https://devtools-tunnel-qe2t5rghme.localtunnel.me
// Browser 2's devtools frontend can be found at: https://devtools-tunnel-pp83sdi4jo.localtunnel.me

setAuthCredentials

Set the basic auth credentials for the public tunnel page.

Alternatively the credentials can be defined when instantiating the plugin.

Type: function (user, pass)

• user string Username
• pass string Password

Example:

const puppeteer = require('puppeteer-extra')
const devtools = require('puppeteer-extra-plugin-devtools')()
puppeteer.use(devtools)

puppeteer.launch().then(async browser => {
  devtools.setAuthCredentials('bob', 'swordfish')
  const tunnel = await devtools.createTunnel(browser)
})

getLocalDevToolsUrl

Convenience function to get the local devtools frontend URL.

Type: function (browser): string

• browser Puppeteer.Browser

Example:

const puppeteer = require('puppeteer-extra')
const devtools = require('puppeteer-extra-plugin-devtools')()
puppeteer.use(devtools)

puppeteer.launch().then(async browser => {
  console.log(devtools.getLocalDevToolsUrl(browser))
  // => http://localhost:55952
})

Tunnel

Extends: RemoteDevTools.DevToolsTunnel

The devtools tunnel for a browser instance.

Type: function (wsEndpoint, opts)

• wsEndpoint
• opts (optional, default {})

url

Get the public devtools frontend url.

Type: function (): string

Example:

const tunnel = await devtools.createTunnel(browser)
console.log(tunnel.url)
// => https://devtools-tunnel-sdoqqj95vg.localtunnel.me

getUrlForPage

Get the devtools frontend deep link for a specific page.

Type: function (page): string

• page Puppeteer.Page

Example:

const page = await browser.newPage()
const tunnel = await devtools.createTunnel(browser)
console.log(tunnel.getUrlForPage(page))
// => https://devtools-tunnel-bmkjg26zmr.localtunnel.me/devtools/inspector.html?ws(...)

close

Close the tunnel.

The tunnel will automatically stop when your script exits.

Type: function ()

Example:

const tunnel = await devtools.createTunnel(browser)
tunnel.close()