CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-expect-puppeteer

Assertion toolkit for Puppeteer that extends Jest's expect API with high-level matchers for integration testing.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration

Global configuration options for controlling timeout, polling behavior, and other matcher settings across all expect-puppeteer operations.

Capabilities

Set Default Options

Configures global default options that apply to all matchers unless overridden.

import type { FrameWaitForFunctionOptions } from "puppeteer";

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

interface Options extends FrameWaitForFunctionOptions {
  /** Maximum time to wait in milliseconds (default: 500) */
  timeout?: number;
  /** Polling interval ("raf", "mutation", or milliseconds) */
  polling?: string | number;
  /** Whether to traverse shadow DOM roots (default: false) */
  traverseShadowRoots?: boolean;
}

Usage Examples:

import { setDefaultOptions } from "expect-puppeteer";

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

// Use faster polling for responsive applications
setDefaultOptions({ 
  timeout: 1000,
  polling: 100 
});

// Enable shadow DOM traversal globally
setDefaultOptions({ 
  timeout: 1000,
  traverseShadowRoots: true 
});

Get Current Default Options

Retrieves the current global default options, including any automatic adjustments.

/**
 * Get current default options (includes slowMo calculation)
 * @returns Current default options object
 */
function getDefaultOptions(): Options;

Usage Examples:

import { getDefaultOptions } from "expect-puppeteer";

// Check current settings
const currentOptions = getDefaultOptions();
console.log(`Current timeout: ${currentOptions.timeout}ms`);
console.log(`Current polling: ${currentOptions.polling}`);

// Temporarily modify and restore
const originalOptions = getDefaultOptions();
setDefaultOptions({ timeout: 5000 });

// ... run tests requiring longer timeout ...

setDefaultOptions(originalOptions); // Restore original settings

Configuration Options

Timeout Options

Controls how long matchers wait for conditions to be met.

interface TimeoutOptions {
  /** Maximum time to wait in milliseconds (default: 500) */
  timeout?: number;
}

Default timeout: 500ms Automatic adjustment: Timeout is automatically increased when slowMo is configured in Puppeteer settings

Usage Examples:

// Short timeout for fast operations
setDefaultOptions({ timeout: 200 });

// Longer timeout for slow operations
setDefaultOptions({ timeout: 5000 });

// Zero timeout (immediate check, no waiting)
setDefaultOptions({ timeout: 0 });

Polling Options

Controls how frequently matchers check conditions while waiting.

interface PollingOptions {
  /** Polling interval ("raf", "mutation", or milliseconds) */
  polling?: string | number;
}

Polling modes:

  • "raf" (default): Uses requestAnimationFrame - best for visual changes
  • "mutation": Uses MutationObserver - best for DOM changes
  • number: Polling interval in milliseconds - for custom timing

Usage Examples:

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

// Custom polling interval
setDefaultOptions({ polling: 250 }); // Check every 250ms

// Fast polling for responsive apps
setDefaultOptions({ polling: 50 });

Shadow DOM Options

Controls whether matchers traverse shadow DOM boundaries when searching for elements or text.

interface ShadowDOMOptions {
  /** Whether to traverse shadow DOM roots (default: false) */
  traverseShadowRoots?: boolean;
}

Usage Examples:

// Enable shadow DOM traversal globally
setDefaultOptions({ traverseShadowRoots: true });

// Per-matcher override (still uses global for other options)
await expect(page).toMatchElement("custom-element", { 
  traverseShadowRoots: false // Override global setting
});

Advanced Configuration

SlowMo Integration

expect-puppeteer automatically integrates with Puppeteer's slowMo configuration:

// Puppeteer configuration with slowMo
const browser = await puppeteer.launch({
  slowMo: 100 // 100ms delay between actions
});

// expect-puppeteer automatically adjusts timeout:
// finalTimeout = configuredTimeout + (slowMo * 10)

Global configuration integration:

// In jest-puppeteer.config.js or similar
module.exports = {
  launch: {
    slowMo: 50 // expect-puppeteer will add 500ms to all timeouts
  }
};

Per-Matcher Configuration

Individual matchers can override global defaults:

// Global settings
setDefaultOptions({ timeout: 1000, polling: "raf" });

// Per-matcher overrides
await expect(page).toMatchElement("button", { 
  timeout: 5000,      // Override global timeout
  polling: "mutation" // Override global polling
});

await expect(page).toMatchTextContent("Loading...", {
  timeout: 500 // Use shorter timeout for this check
});

Environment-Based Configuration

Configure different settings for different environments:

import { setDefaultOptions } from "expect-puppeteer";

// Configure based on environment
if (process.env.CI) {
  // Longer timeouts in CI environment
  setDefaultOptions({ 
    timeout: 3000,
    polling: 200 
  });
} else {
  // Faster settings for local development
  setDefaultOptions({ 
    timeout: 1000,
    polling: 100 
  });
}

Setup Integration

Jest Configuration

Configure expect-puppeteer in your Jest setup:

// In setupFilesAfterEnv file
import { setDefaultOptions } from "expect-puppeteer";

// Configure before tests run
setDefaultOptions({
  timeout: 2000,
  polling: "mutation",
  traverseShadowRoots: false
});

Package.json Setup

{
  "jest": {
    "setupFilesAfterEnv": [
      "expect-puppeteer/setup"
    ]
  }
}

Or with custom configuration:

{
  "jest": {
    "setupFilesAfterEnv": [
      "<rootDir>/jest.setup.js"
    ]
  }
}
// jest.setup.js
require("expect-puppeteer");
const { setDefaultOptions } = require("expect-puppeteer");

setDefaultOptions({ timeout: 1500 });

Best Practices

Timeout Strategy

// Base timeout for most operations
setDefaultOptions({ timeout: 1000 });

// Use longer timeouts for specific slow operations
await expect(page).toMatchElement(".slow-loading-chart", { 
  timeout: 10000 
});

// Use shorter timeouts for quick checks
await expect(page).not.toMatchElement(".error", { 
  timeout: 100 
});

Polling Strategy

// Use "mutation" for DOM-heavy applications
setDefaultOptions({ polling: "mutation" });

// Use "raf" for animation-heavy applications  
setDefaultOptions({ polling: "raf" });

// Use numeric polling for specific timing needs
setDefaultOptions({ polling: 200 });

Configuration Testing

// Test configuration changes don't break existing tests
describe("Configuration", () => {
  const originalOptions = getDefaultOptions();
  
  afterEach(() => {
    setDefaultOptions(originalOptions); // Restore after each test
  });
  
  it("works with longer timeout", () => {
    setDefaultOptions({ timeout: 5000 });
    // ... test with longer timeout
  });
});

Troubleshooting

Common Configuration Issues

Timeouts too short:

// Symptoms: Tests fail with "waiting for function failed: timeout"
// Solution: Increase timeout
setDefaultOptions({ timeout: 2000 });

Polling too aggressive:

// Symptoms: High CPU usage, browser performance issues
// Solution: Use less aggressive polling
setDefaultOptions({ polling: 500 }); // Check every 500ms instead of every frame

Shadow DOM elements not found:

// Symptoms: Elements in shadow DOM not detected
// Solution: Enable shadow DOM traversal
setDefaultOptions({ traverseShadowRoots: true });

docs

configuration.md

dialog-handling.md

element-assertions.md

element-interactions.md

index.md

tile.json