Core matchers for interacting with page elements including clicking, filling forms, selecting options, and uploading files. All interaction matchers automatically wait for elements to exist before performing actions.
Waits for an element to exist, then clicks on it.
/**
* Wait for element to exist then click on it
* @param instance - Puppeteer instance (page, frame, or element)
* @param selector - CSS selector string or Selector object
* @param options - Click and element matching options
*/
function toClick(
instance: PuppeteerInstance,
selector: Selector | string,
options?: ToClickOptions
): Promise<void>;
interface ToClickOptions extends ToMatchElementOptions {
/** Mouse button to click (default: "left") */
button?: "left" | "right" | "middle";
/** Number of clicks (default: 1) */
count?: number;
/** Delay between mousedown and mouseup in milliseconds */
delay?: number;
/** Click offset coordinates */
offset?: { x: number; y: number };
}Usage Examples:
// Basic click
await expect(page).toClick("button");
// Click with text matching
await expect(page).toClick("button", { text: "Submit" });
// Click with XPath selector
await expect(page).toClick({ type: "xpath", value: "//button[text()='Submit']" });
// Right-click with delay
await expect(page).toClick(".context-menu-trigger", {
button: "right",
delay: 100
});
// Double-click
await expect(page).toClick(".item", { count: 2 });Waits for an input element to exist, then clears it and fills it with new text.
/**
* Wait for input element then fill it with text (clears existing content first)
* @param instance - Puppeteer instance (page, frame, or element)
* @param selector - CSS selector string or Selector object for input element
* @param value - Text value to fill
* @param options - Fill and element matching options
*/
function toFill(
instance: PuppeteerInstance,
selector: Selector | string,
value: string,
options?: ToFillOptions
): Promise<void>;
interface ToFillOptions extends ToMatchElementOptions {
/** Delay between keystrokes in milliseconds */
delay?: number;
}Usage Examples:
// Fill input field
await expect(page).toFill('input[name="email"]', "user@example.com");
// Fill with typing delay
await expect(page).toFill('input[name="search"]', "search query", { delay: 50 });
// Fill within a specific form element
const form = await expect(page).toMatchElement("form#login");
await expect(form).toFill('input[name="username"]', "admin");Waits for a form element to exist, then fills multiple fields within it by name attribute.
/**
* Wait for form element then fill multiple fields by name attribute
* @param instance - Puppeteer instance (page, frame, or element)
* @param selector - CSS selector string or Selector object for form element
* @param values - Object mapping field names to values
* @param options - Fill and element matching options
*/
function toFillForm(
instance: PuppeteerInstance,
selector: Selector | string,
values: Record<string, string>,
options?: ToFillFormOptions
): Promise<void>;
interface ToFillFormOptions extends ToFillOptions {}Usage Examples:
// Fill entire form
await expect(page).toFillForm("form#registration", {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
password: "secure123"
});
// Fill form with specific text matching
await expect(page).toFillForm("form", {
username: "admin",
password: "password"
}, { text: "Login Form" });Waits for a select element to exist, then selects an option by value or text content.
/**
* Wait for select element then select option by value or text
* @param instance - Puppeteer instance (page, frame, or element)
* @param selector - CSS selector string or Selector object for select element
* @param valueOrText - Option value or text content to select
* @param options - Element matching options
*/
function toSelect(
instance: PuppeteerInstance,
selector: Selector | string,
valueOrText: string,
options?: ToMatchElementOptions
): Promise<void>;Usage Examples:
// Select by option value
await expect(page).toSelect('select[name="country"]', "US");
// Select by option text
await expect(page).toSelect('select[name="country"]', "United States");
// Select within specific form
await expect(page).toSelect("form#checkout select[name='shipping']", "express");Waits for a file input element to exist, then uploads one or more files to it.
/**
* Wait for file input element then upload files
* @param instance - Puppeteer instance (page, frame, or element)
* @param selector - CSS selector string or Selector object for input[type="file"] element
* @param filePaths - Single file path or array of file paths to upload
* @param options - Element matching options
*/
function toUploadFile(
instance: PuppeteerInstance,
selector: Selector | string,
filePaths: string | string[],
options?: ToMatchElementOptions
): Promise<void>;Usage Examples:
import { join } from "path";
// Upload single file
await expect(page).toUploadFile(
'input[type="file"]',
join(__dirname, "document.pdf")
);
// Upload multiple files
await expect(page).toUploadFile(
'input[type="file"][multiple]',
[
join(__dirname, "image1.jpg"),
join(__dirname, "image2.png")
]
);
// Upload with element text matching
await expect(page).toUploadFile(
'input[type="file"]',
join(__dirname, "resume.pdf"),
{ text: "Upload Resume" }
);All interaction matchers support the following base options from ToMatchElementOptions:
interface ToMatchElementOptions {
/** 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;
}All interaction matchers will throw enhanced errors if: