tessl/npm-playwright

A high-level API to automate web browsers and comprehensive framework for web testing

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Browser Control

Name: tessl/npm-playwright
Author: tessl

Core browser automation functionality for launching browsers, managing contexts, and controlling browser lifecycle across Chromium, Firefox, and WebKit.

Capabilities

Browser Types

Entry points for launching different browser engines with consistent API across all browsers.

/**
 * Chromium browser automation (Google Chrome, Microsoft Edge)
 */
const chromium: BrowserType;

/**  
 * Firefox browser automation
 */
const firefox: BrowserType;

/**
 * WebKit browser automation (Safari)  
 */
const webkit: BrowserType;

interface BrowserType {
  /** Launch a new browser instance */
  launch(options?: LaunchOptions): Promise<Browser>;
  /** Launch browser with persistent user data directory */
  launchPersistentContext(userDataDir: string, options?: BrowserContextOptions & LaunchOptions): Promise<BrowserContext>;
  /** Connect to existing browser via WebSocket */
  connect(wsEndpoint: string, options?: ConnectOptions): Promise<Browser>;
  /** Get executable path for this browser type */
  executablePath(): string;
  /** Get browser name identifier */
  name(): string;
}

Usage Examples:

import { chromium, firefox, webkit } from 'playwright';

// Launch different browsers
const chromeAuth = await chromium.launch({ headless: false });
const firefoxBrowser = await firefox.launch();
const safariNrowser = await webkit.launch();

// Launch with custom executable
const customChromium = await chromium.launch({
  executablePath: '/path/to/chrome',
  args: ['--disable-web-security']
});

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

Browser Management

Control browser instances, manage contexts for isolation, and handle browser lifecycle.

interface Browser {
  /** Create new isolated browser context */
  newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
  /** Get all browser contexts */
  contexts(): BrowserContext[];
  /** Create new page in default context */
  newPage(options?: BrowserContextOptions): Promise<Page>;
  /** Close browser and all pages */  
  close(): Promise<void>;
  /** Check if browser is connected */
  isConnected(): boolean;
  /** Get browser version */
  version(): string;
  /** Browser type name */
  browserType(): BrowserType;
}

interface BrowserContext {
  /** Create new page in this context */
  newPage(): Promise<Page>;
  /** Get all pages in this context */
  pages(): Page[];
  /** Close context and all its pages */
  close(): Promise<void>;
  /** Add cookies to context */
  addCookies(cookies: Cookie[]): Promise<void>;
  /** Get all cookies */
  cookies(urls?: string | string[]): Promise<Cookie[]>;
  /** Clear cookies */
  clearCookies(): Promise<void>;
  /** Set geolocation */
  setGeolocation(geolocation: Geolocation | null): Promise<void>;
  /** Grant permissions */
  grantPermissions(permissions: string[], options?: BrowserContextGrantPermissionsOptions): Promise<void>;
}

Usage Examples:

// Create isolated contexts
const context1 = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  userAgent: 'Custom Agent',
  locale: 'en-US'
});

const context2 = await browser.newContext({
  geolocation: { latitude: 37.7749, longitude: -122.4194 },
  permissions: ['geolocation']
});

// Manage cookies
await context1.addCookies([
  {
    name: 'session',
    value: 'abc123',
    domain: '.example.com',
    path: '/'
  }
]);

// Create pages
const page1 = await context1.newPage(); 
const page2 = await context2.newPage();

// Cleanup
await context1.close();
await context2.close();
await browser.close();

Browser Server

Remote browser server management for distributed testing and browser reuse.

interface BrowserServer {
  /** Get WebSocket endpoint for connecting */
  wsEndpoint(): string;
  /** Close browser server */
  close(): Promise<void>;
  /** Kill browser server process */
  kill(): Promise<void>;
  /** Get process object */
  process(): ChildProcess;
}

Usage Examples:

// Launch browser server
const browserServer = await chromium.launchServer({
  port: 9222,
  headless: false
});

// Connect from different process
const browser = await chromium.connect(browserServer.wsEndpoint());
const page = await browser.newPage();

// Cleanup
await browser.close();
await browserServer.close();

Chrome DevTools Protocol

Direct access to Chrome DevTools Protocol for advanced browser control.

interface CDPSession {
  /** Send CDP command */
  send(method: string, params?: any): Promise<any>;
  /** Detach from target */
  detach(): Promise<void>;
}

interface BrowserContext {
  /** Create CDP session for new targets */
  newCDPSession(page: Page): Promise<CDPSession>;
}

Types

Launch Configuration

interface LaunchOptions {
  /** Run in headless mode */
  headless?: boolean;
  /** Path to browser executable */
  executablePath?: string;
  /** Additional arguments to pass to browser */
  args?: string[];
  /** Ignore default arguments */  
  ignoreDefaultArgs?: boolean | string[];
  /** Proxy settings */
  proxy?: ProxySettings;
  /** Downloads directory */
  downloadsPath?: string;
  /** Chrome sandbox mode */
  chromiumSandbox?: boolean;
  /** Firefox user preferences */
  firefoxUserPrefs?: { [key: string]: string | number | boolean };
  /** Handle SIGINT, SIGTERM, SIGHUP */
  handleSIGINT?: boolean;
  handleSIGTERM?: boolean;  
  handleSIGHUP?: boolean;
  /** Timeout for browser to launch */
  timeout?: number;
  /** Environment variables */
  env?: { [key: string]: string | number | boolean };
  /** Slow down operations by N milliseconds */
  slowMo?: number;
}

interface ConnectOptions {
  /** WebSocket endpoint URL */
  wsEndpoint?: string;
  /** Connection timeout */
  timeout?: number;
  /** Slow down operations */
  slowMo?: number;
  /** Headers for WebSocket connection */
  headers?: { [key: string]: string };
}

interface ConnectOverCDPOptions {
  /** CDP endpoint URL */  
  endpointURL: string;
  /** Connection timeout */
  timeout?: number;
  /** Slow down operations */
  slowMo?: number;
  /** Headers for connection */
  headers?: { [key: string]: string };
}

interface ProxySettings {
  /** Proxy server URL */
  server: string;
  /** Bypass proxy for these patterns */
  bypass?: string;
  /** Username for proxy auth */
  username?: string;
  /** Password for proxy auth */
  password?: string;
}

Context Configuration

interface BrowserContextOptions {
  /** Viewport size (null for no viewport) */
  viewport?: ViewportSize | null;
  /** User agent string */
  userAgent?: string;
  /** Locale identifier */
  locale?: string;
  /** Timezone identifier */
  timezoneId?: string;
  /** Geolocation */
  geolocation?: Geolocation;
  /** Granted permissions */
  permissions?: string[];
  /** HTTP credentials */  
  httpCredentials?: HTTPCredentials;
  /** Start in offline mode */
  offline?: boolean;
  /** Ignore HTTPS errors */
  ignoreHTTPSErrors?: boolean;
  /** Color scheme preference */
  colorScheme?: 'light' | 'dark' | 'no-preference';
  /** Reduced motion preference */
  reducedMotion?: 'reduce' | 'no-preference';
  /** Accept downloads */
  acceptDownloads?: boolean;
  /** Extra HTTP headers */
  extraHTTPHeaders?: { [key: string]: string };
  /** Client certificates */
  clientCertificates?: ClientCertificate[];
  /** Har recording options */
  recordHar?: { 
    omitContent?: boolean;
    path: string;
  };
  /** Video recording options */
  recordVideo?: {
    dir: string;
    size?: ViewportSize;
  };
}

interface Cookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  expires?: number;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: 'Strict' | 'Lax' | 'None';
}

interface ClientCertificate {
  /** Certificate origin */
  origin: string;
  /** Path to certificate file */
  certPath?: string;
  /** Path to key file */  
  keyPath?: string;
  /** Passphrase for key */
  passphrase?: string;
  /** Certificate in PFX format */
  pfxPath?: string;
}

Install with Tessl CLI