playwright-extra

playwright-extra

A modular plugin framework for playwright to enable cool plugins through a clean interface.

Installation

yarn add playwright playwright-extra
# - or -
npm install playwright playwright-extra

Changelog

• v4.2
  • Initial public release

Quickstart

// playwright-extra is a drop-in replacement for playwright,
// it augments the installed playwright with plugin functionality
// Note: Instead of chromium you can use firefox and webkit as well.
const { chromium } = require('playwright-extra')

// import and configure the recaptcha plugin
const RecaptchaPlugin = require('@extra/recaptcha')
const recaptcha = RecaptchaPlugin({
  provider: {
    id: '2captcha',
    token: 'XXXXXXX' // Replace this with your own 2captcha api key
  }
})

// add the plugin to playwright
chromium.use(recaptcha)

// playwright usage as normal
chromium.launch({ headless: true }).then(async browser => {
  const page = await browser.newPage()
  await page.goto('https://www.google.com/recaptcha/api2/demo')

  // That's it, a single line of code to solve reCAPTCHAs and hCaptchas 🎉
  await page.solveRecaptchas()

  await Promise.all([
    page.waitForNavigation(),
    page.click(`#recaptcha-demo-submit`)
  ])
  await page.screenshot({ path: 'response.png', fullPage: true })
  await browser.close()
})

The above example uses the recaptcha plugin, which needs to be installed as well:

yarn add @extra/recaptcha
# - or -
npm install @extra/recaptcha

If you'd like to see debug output just run your script like so:

DEBUG=automation-extra,automation-extra-plugin:* node myscript.js

More examples

TypeScript usage

playwright-extra and most plugins are written in TS, so you get perfect type support out of the box. :)

import { chromium } from 'playwright-extra'
// if you need types as well:
import { chromium, Playwright } from 'playwright-extra'

---

Plugins

🏴 @extra/recaptcha

• Solves reCAPTCHAs and hCaptchas automatically, using a single line of code: page.solveRecaptchas()
• First plugin to support Playwright & Puppeteer, Chrome, Firefox and Webkit.

Note

playwright-extra is brand new, we're in the process of porting over existing puppeteer-extra plugins with Firefox & Webkit support. If you depend on having a large list of pre-made plugins available we suggest you use puppeteer-extra for the moment. See also: Playwright vs Puppeteer

Write your own plugin

Making custom plugins which work with Playwright and Puppeteer is easy and fun. It might even make your own code base more maintainable and modular. Head over to the documentation here: automation-extra-plugin

---

API

Table of Contents

• addExtra(launcher)
• chromium()
• firefox()
• webkit()
• errors()
• selectors()
• devices()

addExtra(launcher)

• launcher PlaywrightBrowserLauncher Playwright (or compatible) browser launcher

Returns: PlaywrightExtra

Augment the provided Playwright browser launcher with plugin functionality.

Using addExtra will always create a fresh PlaywrightExtra instance.

Example:

import playwright from 'playwright'
import { addExtra } from 'playwright-extra'

const chromium = addExtra(playwright.chromium)
chromium.use(plugin)

---

chromium()

This object can be used to launch or connect to Chromium, returning instances of ChromiumBrowser.

The default exports will behave exactly the same as the regular playwright (just with extra plugin functionality) and can be used as a drop-in replacement.

Behind the scenes it will try to require either playwright or playwright-core from the installed dependencies.

Please note that due to imports being cached this will result in a single PlaywrightExtra instance, even when used in different files. If you need multiple instances (e.g. different plugins) please use addExtra.

Example:

// javascript import
const { chromium } = require('playwright-extra')

// typescript/es6 module import
import { chromium } from 'playwright-extra'

// Add plugins
chromium.use(...)

---

firefox()

This object can be used to launch or connect to Firefox, returning instances of FirefoxBrowser.

---

webkit()

This object can be used to launch or connect to WebKit, returning instances of WebKitBrowser.

---

errors()

Returns playwright specific errors

---

selectors()

Selectors can be used to install custom selector engines.

---

devices()

Returns a list of devices to be used with browser.newContext([options]) or browser.newPage([options]).

---

License

Copyright © 2018 - 2021, berstend̡̲̫̹̠̖͚͓̔̄̓̐̄͛̀͘. Released under the MIT License.