puppeteer-extra-plugin-devtools

> A plugin for puppeteer-extra.

Installation

``bash
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

!screenshot

Quickstart

`es6
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

$3

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:

`javascript
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:

`javascript
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:

`javascript
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:

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

---

$3

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:

`javascript
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:

`javascript
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:

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

---