tessl/npm-jest-puppeteer

Jest preset that enables end-to-end testing with Puppeteer, providing browser automation and testing utilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration

Name: tessl/npm-jest-puppeteer
Author: tessl

Configuration options for jest-puppeteer, including browser setup, server management, and expect-puppeteer matcher behavior. jest-puppeteer provides comprehensive configuration through jest-puppeteer.config.js files and environment variables.

Capabilities

Jest-Puppeteer Configuration File

Main configuration system using jest-puppeteer.config.js for browser launch options, server management, and environment settings.

/**
 * Configuration object for jest-puppeteer preset
 */
interface JestPuppeteerConfig {
  /** Puppeteer connect options for connecting to existing browser */
  connect?: ConnectOptions;
  /** Puppeteer launch options for launching new browser */
  launch?: PuppeteerLaunchOptions;
  /** Development server configuration */
  server?: JestDevServerConfig | JestDevServerConfig[];
  /** Run one browser per worker process */
  browserPerWorker?: boolean;
  /** Browser context type */
  browserContext?: "default" | "incognito";
  /** Exit on page errors */
  exitOnPageError?: boolean;
  /** Use runBeforeUnload when closing pages */
  runBeforeUnloadOnClose?: boolean;
}

interface ConnectOptions {
  browserWSEndpoint?: string;
  ignoreHTTPSErrors?: boolean;
  defaultViewport?: Viewport | null;
  slowMo?: number;
}

interface PuppeteerLaunchOptions {
  headless?: boolean | "new";
  args?: string[];
  ignoreDefaultArgs?: boolean | string[];
  handleSIGINT?: boolean;
  handleSIGTERM?: boolean;
  handleSIGHUP?: boolean;
  timeout?: number;
  dumpio?: boolean;
  userDataDir?: string;
  env?: Record<string, string | undefined>;
  devtools?: boolean;
  pipe?: boolean;
  product?: "chrome" | "firefox";
  extraPrefsFirefox?: Record<string, unknown>;
  slowMo?: number;
}

interface JestDevServerConfig {
  command: string;
  port: number;
  launchTimeout?: number;
  debug?: boolean;
}

Usage Examples:

// jest-puppeteer.config.js

/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */
module.exports = {
  launch: {
    dumpio: true,
    headless: process.env.HEADLESS !== "false",
  },
  server: {
    command: "node server.js",
    port: 4444,
    launchTimeout: 10000,
    debug: true,
  },
};

Browser Launch Configuration

Options for launching and connecting to Puppeteer browser instances.

interface LaunchConfig {
  /** Launch new browser instance */
  launch?: PuppeteerLaunchOptions;
  /** Connect to existing browser instance */
  connect?: ConnectOptions;
}

Usage Examples:

// Launch configuration
module.exports = {
  launch: {
    headless: false,
    devtools: true,
    slowMo: 250,
    args: ["--no-sandbox", "--disable-setuid-sandbox"],
  },
};

// Connect configuration  
module.exports = {
  connect: {
    browserWSEndpoint: "ws://localhost:9222/devtools/browser",
  },
};

Server Management Configuration

Automatic server startup and teardown for testing applications.

interface ServerConfig {
  /** Command to start the server */
  command: string;
  /** Port number server will listen on */
  port: number;
  /** Timeout for server startup */
  launchTimeout?: number;
  /** Enable debug output */
  debug?: boolean;
}

Usage Examples:

// Single server
module.exports = {
  server: {
    command: "npm start",
    port: 3000,
    launchTimeout: 10000,
    debug: true,
  },
};

// Multiple servers
module.exports = {
  server: [
    {
      command: "npm run start:api",
      port: 8080,
    },
    {
      command: "npm run start:web",
      port: 3000,
    },
  ],
};

expect-puppeteer Matcher Options

Configuration for expect-puppeteer assertion matchers, including timeouts and polling behavior.

/**
 * Set global default options for all matchers
 * @param options - Configuration options to set as defaults
 */
function setDefaultOptions(options: Options): void;

/**
 * Get current default options with slowMo adjustments applied
 * @returns Current default options object
 */
function getDefaultOptions(): Options;

interface Options {
  /** Maximum time to wait for conditions in milliseconds */
  timeout?: number;
  /** Polling interval for condition checking */
  polling?: string | number;
}

Usage Examples:

import { setDefaultOptions } from "expect-puppeteer";

// Set longer timeout for slow applications
setDefaultOptions({ timeout: 10000 });

// Set custom polling interval
setDefaultOptions({ 
  timeout: 5000,
  polling: 100 // Check every 100ms
});

// Use requestAnimationFrame polling for styling changes
setDefaultOptions({ 
  timeout: 3000,
  polling: "raf" 
});

// Use mutation observer polling for DOM changes
setDefaultOptions({ 
  timeout: 5000,
  polling: "mutation" 
});

Configuration File Location

jest-puppeteer uses cosmiconfig for configuration file discovery. Configuration files are searched in this order:

package.json - "jest-puppeteer" key
.jest-puppeteerrc - JSON or YAML format
.jest-puppeteerrc.json, .jest-puppeteerrc.yml, .jest-puppeteerrc.yaml, .jest-puppeteerrc.json5
.jest-puppeteerrc.js, .jest-puppeteerrc.cjs, jest-puppeteer.config.js, jest-puppeteer.config.cjs
.jest-puppeteerrc.toml

Use JEST_PUPPETEER_CONFIG environment variable to specify custom configuration file path.

Environment-Specific Configuration

Development vs Production

// jest-puppeteer.config.js
const isDevelopment = process.env.NODE_ENV === "development";

/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */
module.exports = {
  launch: {
    headless: !isDevelopment,
    devtools: isDevelopment,
    slowMo: isDevelopment ? 100 : 0,
  },
  browserContext: isDevelopment ? "default" : "incognito",
};

CI/CD Configuration

// jest-puppeteer.config.js
const isCI = process.env.CI === "true";

/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */
module.exports = {
  launch: {
    headless: isCI,
    args: isCI 
      ? ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"]
      : [],
  },
  server: {
    command: "npm start",
    port: 3000,
    launchTimeout: isCI ? 60000 : 10000,
  },
};

Async Configuration

// jest-puppeteer.config.js
const dockerHost = "http://localhost:9222";

async function getConfig() {
  const data = await fetch(`${dockerHost}/json/version`).then(r => r.json());
  const browserWSEndpoint = data.webSocketDebuggerUrl;
  
  return {
    connect: {
      browserWSEndpoint,
    },
    server: {
      command: "node server.js",
      port: 3000,
    },
  };
}

module.exports = getConfig();

Best Practices

Performance Optimization

Use browserPerWorker: false for faster test execution (shared browser)
Use browserContext: "incognito" for test isolation with shared browser
Set appropriate timeouts based on your application's performance characteristics
Use headless: true in CI environments for better performance