Content Matching

/**
 * Wait for an element to appear and return it for further interaction
 * @param selector - CSS selector or Selector object to identify the element
 * @param options - Element matching options including text filtering and visibility
 * @returns Promise that resolves to ElementHandle when element is found
 */
toMatchElement(selector: string | Selector, options?: ToMatchElementOptions): Promise<ElementHandle<Element>>;

interface ToMatchElementOptions extends Options {
  /** Text content that must be present within the element */
  text?: string | RegExp;
  /** Whether to wait for element to be visible (not just present in DOM) */
  visible?: boolean;
}

import { expect } from "expect-puppeteer";

// Find element by selector
const button = await expect(page).toMatchElement("button");

// Find element with specific text
const submitBtn = await expect(page).toMatchElement("button", { 
  text: "Submit Form" 
});

// Find element with regex text matching
const errorMsg = await expect(page).toMatchElement(".alert", { 
  text: /error|failed/i 
});

// Wait for visible element (not just in DOM)
const modal = await expect(page).toMatchElement(".modal", { 
  visible: true 
});

// Find element within another element
const table = await expect(page).toMatchElement("table");
const row = await expect(table).toMatchElement("tr", { 
  text: "John Doe" 
});

// Use returned element for further actions
const userRow = await expect(page).toMatchElement("tr", { text: "Alice" });
await expect(userRow).toClick("button", { text: "Edit" });

// XPath selector usage
const link = await expect(page).toMatchElement({
  type: "xpath",
  value: "//a[contains(@href, '/profile')]"
}, { text: "View Profile" });

/**
 * Wait for specific text content to appear in the page or element
 * @param matcher - Text string or RegExp to match against content
 * @param options - Text matching options including shadow DOM traversal
 * @returns Promise that resolves when text is found
 */
toMatchTextContent(matcher: string | RegExp, options?: MatchTextContentOptions): Promise<void>;

interface MatchTextContentOptions extends Options {
  /** Whether to include content from shadow DOM elements */
  traverseShadowRoots?: boolean;
}

import { expect } from "expect-puppeteer";

// Match exact text
await expect(page).toMatchTextContent("Welcome to our website");

// Match with regular expression
await expect(page).toMatchTextContent(/user.*logged.*in/i);

// Match text within specific element context
const notification = await expect(page).toMatchElement(".notification");
await expect(notification).toMatchTextContent("Operation completed successfully");

// Match text including shadow DOM content
await expect(page).toMatchTextContent("Shadow content text", {
  traverseShadowRoots: true
});

// Wait for dynamic content to load
await expect(page).toMatchTextContent(/Loading.*complete|Data.*loaded/);

// Verify error messages
await expect(page).toMatchTextContent("Invalid email address");

// Match multi-line content
await expect(page).toMatchTextContent(/Name:.*John.*Email:.*john@/s);

/**
 * Wait for element to not be present or not match conditions
 * @param selector - CSS selector or Selector object
 * @param options - Element matching options
 */
not.toMatchElement(selector: string | Selector, options?: ToMatchElementOptions): Promise<void>;

/**
 * Wait for text content to not be present
 * @param matcher - Text string or RegExp that should not match
 * @param options - Text matching options
 */
not.toMatchTextContent(matcher: string | RegExp, options?: MatchTextContentOptions): Promise<void>;

import { expect } from "expect-puppeteer";

// Verify element is not present
await expect(page).not.toMatchElement(".error-message");

// Verify specific text is not present
await expect(page).not.toMatchTextContent("Page not found");

// Verify element with text is removed
await expect(page).not.toMatchElement(".notification", { 
  text: "Loading..." 
});

// Verify error state is cleared
await expect(page).not.toMatchTextContent(/error|failed/i);

// Verify dynamic content is hidden
const modal = await expect(page).toMatchElement(".modal");
await expect(modal).not.toMatchTextContent("Processing...");

// Verify removal after action
await expect(page).toClick("button", { text: "Delete Item" });
await expect(page).not.toMatchElement(".item", { text: "Item to delete" });

// Case-insensitive matching
await expect(page).toMatchTextContent(/welcome/i);

// Word boundaries
await expect(page).toMatchTextContent(/\\buser\\b/);

// Optional content
await expect(page).toMatchTextContent(/Profile( Page)?/);

// Multiple alternatives
await expect(page).toMatchTextContent(/success|complete|done/i);

// Multiline matching with dotall flag
await expect(page).toMatchTextContent(/Header.*Footer/s);