or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mddialog-handling.mdelement-assertions.mdelement-interactions.mdindex.md
tile.json

index.mddocs/

expect-puppeteer

expect-puppeteer is an assertion toolkit for Puppeteer that extends Jest's expect API with high-level, asynchronous matchers designed specifically for integration testing. It provides Puppeteer-specific assertions that automatically wait for elements to be present before performing actions, solving common timing issues in asynchronous web testing.

Package Information

  • Package Name: expect-puppeteer
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install expect-puppeteer

Core Imports

import { expect, setDefaultOptions, getDefaultOptions } from "expect-puppeteer";

For CommonJS:

const { expect, setDefaultOptions, getDefaultOptions } = require("expect-puppeteer");

Jest Setup Integration

// In setupFilesAfterEnv or Jest configuration
import "expect-puppeteer";
// Or for direct setup file import
import "expect-puppeteer/setup";
// CommonJS setup
require("expect-puppeteer");
// Or for direct setup
require("expect-puppeteer/setup");

Basic Usage

import "expect-puppeteer"; // Sets up global expect enhancement
// Or with Jest setupFilesAfterEnv: ["expect-puppeteer"]

// Basic element assertions
await expect(page).toMatchElement("button", { text: "Submit" });
await expect(page).toClick("button", { text: "Submit" });

// Form interactions
await expect(page).toFill('input[name="email"]', "user@example.com");
await expect(page).toSelect('select[name="country"]', "United States");

// Content validation
await expect(page).toMatchTextContent("Welcome to our site");
await expect(page).not.toMatchTextContent("Error occurred");

Architecture

expect-puppeteer extends Jest's expect functionality with Puppeteer-specific matchers:

  • Enhanced expect function: Detects Puppeteer instances (Page, Frame, ElementHandle) and provides additional matchers
  • Automatic waiting: All matchers wait for elements to exist before performing actions
  • Text-based matching: Support for both string and RegExp text content matching
  • Selector flexibility: Supports both CSS selectors and XPath expressions
  • Type safety: Full TypeScript support with conditional matcher availability based on instance type
  • Configurable timeouts: Global and per-matcher timeout and polling options

Capabilities

Element Interaction

Core matchers for interacting with page elements including clicking, filling forms, and file uploads.

// Click on elements
function toClick(
  instance: PuppeteerInstance,
  selector: Selector | string,
  options?: ToClickOptions
): Promise<void>;

// Fill form fields
function toFill(
  instance: PuppeteerInstance,
  selector: Selector | string,
  value: string,
  options?: ToFillOptions
): Promise<void>;

// Fill entire forms
function toFillForm(
  instance: PuppeteerInstance,
  selector: Selector | string,
  values: Record<string, string>,
  options?: ToFillFormOptions
): Promise<void>;

// Select options
function toSelect(
  instance: PuppeteerInstance,
  selector: Selector | string,
  valueOrText: string,
  options?: ToMatchElementOptions
): Promise<void>;

// Upload files
function toUploadFile(
  instance: PuppeteerInstance,
  selector: Selector | string,
  filePaths: string | string[],
  options?: ToMatchElementOptions
): Promise<void>;

Element Interactions

Element Assertions

Matchers for asserting element presence, text content, and other element states.

// Assert element exists and return it
function toMatchElement(
  instance: PuppeteerInstance,
  selector: Selector | string,
  options?: ToMatchElementOptions
): Promise<ElementHandle<Element>>;

// Assert text content matches
function toMatchTextContent(
  instance: PuppeteerInstance,
  matcher: SearchExpression,
  options?: ToMatchOptions
): Promise<void>;

// Assert elements do not exist
function notToMatchElement(
  instance: PuppeteerInstance,
  selector: Selector | string,
  options?: NotToMatchElementOptions
): Promise<void>;

// Assert text content does not match
function notToMatchTextContent(
  instance: PuppeteerInstance,
  matcher: SearchExpression,
  options?: NotToMatchOptions
): Promise<void>;

Element Assertions

Dialog Handling

Special matcher for handling browser dialogs (alerts, confirms, prompts).

// Capture dialogs triggered by actions (Page instances only)
function toDisplayDialog(
  page: Page,
  block: () => Promise<void>
): Promise<Dialog>;

Dialog Handling

Configuration

Global configuration options for timeout and polling behavior.

// Set global default options
function setDefaultOptions(options: Options): void;

// Get current default options
function getDefaultOptions(): Options;

interface Options extends FrameWaitForFunctionOptions {
  timeout?: number;
  polling?: string | number;
  traverseShadowRoots?: boolean;
}

Configuration

Core Types

import type { Page, Frame, ElementHandle, Dialog, FrameWaitForFunctionOptions } from "puppeteer";

// Puppeteer instances that can be used with matchers
type PuppeteerInstance = Page | Frame | ElementHandle;

// Selector definition supporting CSS and XPath
interface Selector {
  type: "css" | "xpath";
  value: string;
}

// Search expressions for text matching
type SearchExpression = RegExp | string | undefined;

// Base element options
interface GetElementOptions {
  text?: string | RegExp;
  visible?: boolean;
}

// Base text matching options
interface MatchTextContentOptions extends Options {
  traverseShadowRoots?: boolean;
}

// Element matching options
interface ToMatchElementOptions extends GetElementOptions {
  timeout?: number;
  polling?: string | number;
  traverseShadowRoots?: boolean;
}