Element Interaction

/**
 * Click on an element after waiting for it to appear
 * @param selector - CSS selector or Selector object to identify the element
 * @param options - Click options including text filtering and mouse button
 * @returns Promise that resolves when click is completed
 */
toClick(selector: string | Selector, options?: ToClickOptions): Promise<void>;

interface ToClickOptions extends ToMatchElementOptions {
  /** Mouse button to use for clicking */
  button?: "left" | "right" | "middle";
  /** Number of clicks to perform */
  clickCount?: number;
  /** Delay between mousedown and mouseup in milliseconds */
  delay?: number;
  /** Click offset from element center */
  offset?: { x: number; y: number };
}

import { expect } from "expect-puppeteer";

// Basic click
await expect(page).toClick("button");

// Click button with specific text
await expect(page).toClick("button", { text: "Submit" });

// Right-click with text matching
await expect(page).toClick(".menu-item", { 
  text: "Edit", 
  button: "right" 
});

// Double-click
await expect(page).toClick(".file-item", { 
  text: "document.pdf",
  clickCount: 2 
});

// Click with XPath selector
await expect(page).toClick({ 
  type: "xpath", 
  value: "//button[contains(text(), 'Save')]" 
});

// Click on element within specific context
const form = await expect(page).toMatchElement("form");
await expect(form).toClick("button[type='submit']");

/**
 * Fill a form control with text after waiting for it to appear
 * @param selector - CSS selector or Selector object to identify the input
 * @param value - Text value to enter into the field
 * @param options - Fill options including typing delay
 * @returns Promise that resolves when filling is completed
 */
toFill(selector: string | Selector, value: string, options?: ToFillOptions): Promise<void>;

interface ToFillOptions extends ToMatchElementOptions {
  /** Delay between keystrokes in milliseconds */
  delay?: number;
}

import { expect } from "expect-puppeteer";

// Fill basic input field
await expect(page).toFill('input[name="firstName"]', "John");

// Fill with typing delay (simulates human typing)
await expect(page).toFill('input[name="email"]', "john@example.com", {
  delay: 100
});

// Fill textarea
await expect(page).toFill("textarea", "This is a longer message that will be typed into the textarea.");

// Fill field within specific context
const modal = await expect(page).toMatchElement(".modal");
await expect(modal).toFill('input[name="username"]', "johndoe");

// Fill password field
await expect(page).toFill('input[type="password"]', "securePassword123");

/**
 * Upload files to a file input element
 * @param selector - CSS selector or Selector object to identify the file input
 * @param filePaths - Single file path or array of file paths to upload
 * @param options - Upload options
 * @returns Promise that resolves when upload is initiated
 */
toUploadFile(selector: string | Selector, filePaths: string | string[], options?: ToMatchElementOptions): Promise<void>;

import { expect } from "expect-puppeteer";
import { join } from "node:path";

// Upload single file
await expect(page).toUploadFile(
  'input[type="file"]',
  join(__dirname, "documents", "test.pdf")
);

// Upload multiple files
await expect(page).toUploadFile('input[type="file"][multiple]', [
  join(__dirname, "images", "photo1.jpg"),
  join(__dirname, "images", "photo2.jpg"),
  join(__dirname, "documents", "report.pdf")
]);

// Upload file within form context
const uploadForm = await expect(page).toMatchElement("#upload-form");
await expect(uploadForm).toUploadFile(
  'input[name="attachment"]',
  join(__dirname, "files", "attachment.doc")
);

// Upload with specific file input selection
await expect(page).toUploadFile(
  'input[type="file"][accept=".jpg,.png"]',
  join(__dirname, "avatar.png")
);