Element Assertions

/**
 * Wait for element to exist and return it
 * @param instance - Puppeteer instance (page, frame, or element)
 * @param selector - CSS selector string or Selector object
 * @param options - Element matching options
 * @returns ElementHandle for the found element
 */
function toMatchElement(
  instance: PuppeteerInstance,
  selector: Selector | string,
  options?: ToMatchElementOptions
): Promise<ElementHandle<Element>>;

interface ToMatchElementOptions extends GetElementOptions {
  /** Text content to match within the element */
  text?: string | RegExp;
  /** Whether element must be visible (default: false) */
  visible?: boolean;
  /** 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;
}

// Assert element exists
await expect(page).toMatchElement("button");

// Assert element with specific text
await expect(page).toMatchElement("button", { text: "Submit" });

// Assert visible element only
await expect(page).toMatchElement(".modal", { visible: true });

// Assert with RegExp text matching
await expect(page).toMatchElement("h1", { text: /Welcome.*/ });

// Get element handle for further operations
const row = await expect(page).toMatchElement("tr", { text: "John Doe" });
await expect(row).toClick("td button", { text: "Edit" });

/**
 * Wait for text content to match string or RegExp
 * @param instance - Puppeteer instance (page, frame, or element)
 * @param matcher - String or RegExp to match in text content
 * @param options - Text matching options
 */
function toMatchTextContent(
  instance: PuppeteerInstance,
  matcher: SearchExpression,
  options?: ToMatchOptions
): Promise<void>;

interface ToMatchOptions extends MatchTextContentOptions {
  /** 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;
}

type SearchExpression = RegExp | string | undefined;

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

// Match with RegExp
await expect(page).toMatchTextContent(/Hello, \w+!/);

// Match within specific element
const sidebar = await expect(page).toMatchElement(".sidebar");
await expect(sidebar).toMatchTextContent("Navigation");

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

/**
 * Wait for element to not exist or not match criteria
 * @param instance - Puppeteer instance (page, frame, or element)
 * @param selector - CSS selector string or Selector object
 * @param options - Element matching options
 */
function notToMatchElement(
  instance: PuppeteerInstance,
  selector: Selector | string,
  options?: NotToMatchElementOptions
): Promise<void>;

interface NotToMatchElementOptions extends GetElementOptions {
  /** Text content to match within the element */
  text?: string | RegExp;
  /** Whether element must be visible (default: false) */
  visible?: boolean;
  /** 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;
}

// Assert element does not exist
await expect(page).not.toMatchElement(".error-message");

// Assert element with specific text does not exist
await expect(page).not.toMatchElement("button", { text: "Delete" });

// Assert visible element does not exist
await expect(page).not.toMatchElement(".loading-spinner", { visible: true });

/**
 * Wait for text content to not match string or RegExp
 * @param instance - Puppeteer instance (page, frame, or element)
 * @param matcher - String or RegExp that should not match in text content
 * @param options - Text matching options
 */
function notToMatchTextContent(
  instance: PuppeteerInstance,
  matcher: SearchExpression,
  options?: NotToMatchOptions
): Promise<void>;

interface NotToMatchOptions extends MatchTextContentOptions {
  /** 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;
}

// Assert text does not exist
await expect(page).not.toMatchTextContent("Error occurred");

// Assert RegExp does not match
await expect(page).not.toMatchTextContent(/Server error \d+/);

// Assert within specific element
const form = await expect(page).toMatchElement("form");
await expect(form).not.toMatchTextContent("Required field");

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

// CSS selector (default)
await expect(page).toMatchElement("button.primary");

// XPath selector
await expect(page).toMatchElement({
  type: "xpath",
  value: "//button[contains(@class, 'primary')]"
});

// XPath with text content
await expect(page).toMatchElement({
  type: "xpath", 
  value: "//div[text()='Welcome']"
});

// Exact text matching
await expect(page).toMatchElement("button", { text: "Click Here" });

// Case-insensitive RegExp
await expect(page).toMatchElement("h1", { text: /welcome/i });

// Pattern matching
await expect(page).toMatchElement("span", { text: /\d+ items/ });

// Only match visible elements
await expect(page).toMatchElement(".modal", { visible: true });

// Match any element (visible or hidden) - default behavior
await expect(page).toMatchElement(".modal", { visible: false });