tessl/npm-playwright-extra

A modular plugin framework for Playwright to enable enhanced browser automation through plugins.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Browser Launchers

Name: tessl/npm-playwright-extra
Author: tessl

Enhanced browser launchers that provide the same API as standard Playwright with additional plugin functionality. Each launcher supports plugin registration and manages plugin lifecycle events throughout the browser's lifecycle.

Capabilities

Chromium Launcher

Chromium browser launcher with plugin functionality. This is the default export that automatically loads the installed playwright or playwright-core module.

const chromium: AugmentedBrowserLauncher;

Usage Examples:

import { chromium } from "playwright-extra";
import StealthPlugin from "puppeteer-extra-plugin-stealth";

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

// Launch browser (same as standard Playwright)
const browser = await chromium.launch({
  headless: true,
  args: ['--no-sandbox']
});

const context = await browser.newContext();
const page = await context.newPage();

Firefox Launcher

Firefox browser launcher with plugin functionality.

const firefox: AugmentedBrowserLauncher;

Usage Examples:

import { firefox } from "playwright-extra";
import RecaptchaPlugin from "puppeteer-extra-plugin-recaptcha";

// Add plugins
firefox.use(RecaptchaPlugin({
  provider: {
    id: '2captcha',
    token: 'YOUR_API_KEY'
  }
}));

// Launch Firefox
const browser = await firefox.launch({ headless: false });

WebKit Launcher

WebKit browser launcher with plugin functionality.

const webkit: AugmentedBrowserLauncher;

Usage Examples:

import { webkit } from "playwright-extra";

// Add plugins
webkit.use(plugin);

// Launch WebKit
const browser = await webkit.launch({ headless: true });

Launch Method

Launch a browser instance with plugin support. All plugins are executed before and after the launch process.

async launch(
  options?: LaunchOptions
): Promise<Browser>;

Usage Examples:

import { chromium } from "playwright-extra";

// Launch with options
const browser = await chromium.launch({
  headless: true,
  slowMo: 50,
  args: ['--disable-web-security']
});

// Plugins can modify launch options via beforeLaunch hook

Launch Persistent Context Method

Launch a browser with a persistent context. This method combines browser launching and context creation into one step.

async launchPersistentContext(
  userDataDir: string,
  options?: BrowserContextOptions & LaunchOptions
): Promise<BrowserContext>;

Usage Examples:

import { chromium } from "playwright-extra";

// Launch with persistent context
const context = await chromium.launchPersistentContext('./user-data', {
  headless: false,
  viewport: { width: 1280, height: 720 }
});

const page = await context.newPage();

Connect Method

Connect to an existing browser instance via WebSocket endpoint with plugin support.

async connect(
  wsEndpointOrOptions: string | (ConnectOptions & { wsEndpoint?: string }),
  wsOptions?: ConnectOptions
): Promise<Browser>;

Usage Examples:

import { chromium } from "playwright-extra";

// Connect using WebSocket endpoint string
const browser = await chromium.connect('ws://localhost:9222/devtools/browser');

// Connect with additional options
const browser = await chromium.connect('ws://localhost:9222/devtools/browser', {
  timeout: 30000
});

// Connect using options object
const browser = await chromium.connect({
  wsEndpoint: 'ws://localhost:9222/devtools/browser',
  timeout: 30000
});

Connect Over CDP Method

Connect to an existing Chromium browser via Chrome DevTools Protocol.

async connectOverCDP(
  wsEndpointOrOptions: string | (ConnectOverCDPOptions & { endpointURL?: string }),
  wsOptions?: ConnectOverCDPOptions
): Promise<Browser>;

Usage Examples:

import { chromium } from "playwright-extra";

// Connect over CDP using endpoint URL string
const browser = await chromium.connectOverCDP('http://localhost:9222');

// Connect with additional options
const browser = await chromium.connectOverCDP('http://localhost:9222', {
  timeout: 10000
});

// Connect using options object
const browser = await chromium.connectOverCDP({
  endpointURL: 'http://localhost:9222',
  timeout: 10000
});

Plugin Registration

use(plugin: CompatiblePlugin): this;

Usage Examples:

import { chromium } from "playwright-extra";
import StealthPlugin from "puppeteer-extra-plugin-stealth";
import RecaptchaPlugin from "puppeteer-extra-plugin-recaptcha";

// Chain multiple plugins
chromium
  .use(StealthPlugin())
  .use(RecaptchaPlugin({ 
    provider: { id: '2captcha', token: 'key' } 
  }));

// Individual plugin registration
chromium.use(StealthPlugin());
chromium.use(RecaptchaPlugin());

Plugin Manager Access

Access the plugin manager for advanced plugin configuration and inspection.

readonly plugins: PluginList;

Usage Examples:

import { chromium } from "playwright-extra";

// Access plugin list
console.log(chromium.plugins.names); // ['stealth', 'recaptcha']

// Set dependency defaults
chromium.plugins.setDependencyDefaults('stealth/evasions/webgl.vendor', {
  vendor: 'Custom Vendor',
  renderer: 'Custom Renderer'
});

// Get plugin instances
const pluginList = chromium.plugins.list;

Core Types

interface AugmentedBrowserLauncher extends PlaywrightBrowserLauncher {
  use(plugin: CompatiblePlugin): this;
  plugins: PluginList;
}

type PlaywrightBrowserLauncher = BrowserType<{}>;

interface LaunchOptions {
  headless?: boolean;
  args?: string[];
  ignoreDefaultArgs?: boolean | string[];
  proxy?: {
    server: string;
    bypass?: string;
    username?: string;
    password?: string;
  };
  downloadsPath?: string;
  chromiumSandbox?: boolean;
  firefoxUserPrefs?: { [key: string]: string | number | boolean };
  slowMo?: number;
  timeout?: number;
}

interface ConnectOptions {
  wsEndpoint?: string;
  timeout?: number;
  slowMo?: number;
}

interface ConnectOverCDPOptions {
  endpointURL?: string;
  timeout?: number;
  slowMo?: number;
}

Install with Tessl CLI