Page Interaction

/**
 * Navigate to a URL
 * @param url - URL to navigate to
 * @param options - Navigation options
 * @returns Response object or null
 */
goto(url: string, options?: PageGotoOptions): Promise<Response | null>;

/**
 * Reload the current page
 * @param options - Reload options
 * @returns Response object or null
 */
reload(options?: PageReloadOptions): Promise<Response | null>;

/**
 * Navigate back in browser history
 * @param options - Navigation options
 * @returns Response object or null
 */
goBack(options?: PageGoBackOptions): Promise<Response | null>;

/**
 * Navigate forward in browser history
 * @param options - Navigation options
 * @returns Response object or null
 */
goForward(options?: PageGoForwardOptions): Promise<Response | null>;

// Basic navigation
await page.goto('https://example.com');

// Navigation with options
await page.goto('https://example.com', {
  waitUntil: 'networkidle',
  timeout: 30000
});

// Handle navigation responses
const response = await page.goto('https://api.example.com/data');
if (response && response.status() === 200) {
  console.log('Navigation successful');
}

// Page history navigation
await page.goBack();
await page.goForward();
await page.reload();

/**
 * Click an element matching the selector
 * @param selector - Element selector
 * @param options - Click options
 */
click(selector: string, options?: PageClickOptions): Promise<void>;

/**
 * Double-click an element matching the selector
 * @param selector - Element selector
 * @param options - Click options
 */
dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;

/**
 * Fill an input element with text
 * @param selector - Input element selector
 * @param value - Text to fill
 * @param options - Fill options
 */
fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;

/**
 * Type text into an element
 * @param selector - Element selector
 * @param text - Text to type
 * @param options - Type options
 */
type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;

/**
 * Press a key on an element
 * @param selector - Element selector
 * @param key - Key to press
 * @param options - Press options
 */
press(selector: string, key: string, options?: PagePressOptions): Promise<void>;

/**
 * Check a checkbox or select a radio button
 * @param selector - Element selector
 * @param options - Check options
 */
check(selector: string, options?: PageCheckOptions): Promise<void>;

/**
 * Uncheck a checkbox
 * @param selector - Element selector
 * @param options - Uncheck options
 */
uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;

/**
 * Select options from a dropdown
 * @param selector - Select element selector
 * @param values - Values to select
 * @param options - Select options
 */
selectOption(selector: string, values: string | ElementHandle | SelectOption | string[] | ElementHandle[] | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;

// Form interaction
await page.fill('input[name="email"]', 'user@example.com');
await page.fill('input[name="password"]', 'secretpassword');
await page.check('input[name="rememberMe"]');
await page.click('button[type="submit"]');

// Dropdown selection
await page.selectOption('select[name="country"]', 'us');
await page.selectOption('select[name="options"]', ['option1', 'option2']);

// Keyboard interaction
await page.press('input[name="search"]', 'Enter');
await page.type('textarea', 'This is some text', { delay: 100 });

// Advanced clicking
await page.click('button', {
  position: { x: 10, y: 10 },
  modifiers: ['Shift'],
  clickCount: 2
});

/**
 * Get the full HTML content of the page
 * @returns HTML content as string
 */
content(): Promise<string>;

/**
 * Set the HTML content of the page
 * @param html - HTML content to set
 * @param options - Content options
 */
setContent(html: string, options?: PageSetContentOptions): Promise<void>;

/**
 * Get the page title
 * @returns Page title
 */
title(): Promise<string>;

/**
 * Get the current page URL
 * @returns Current URL
 */
url(): string;

/**
 * Get inner text of an element
 * @param selector - Element selector
 * @param options - Text options
 * @returns Inner text or null
 */
innerText(selector: string, options?: PageInnerTextOptions): Promise<string>;

/**
 * Get text content of an element
 * @param selector - Element selector
 * @param options - Text options
 * @returns Text content or null
 */
textContent(selector: string, options?: PageTextContentOptions): Promise<string | null>;

/**
 * Get innerHTML of an element
 * @param selector - Element selector
 * @param options - HTML options
 * @returns Inner HTML
 */
innerHTML(selector: string, options?: PageInnerHTMLOptions): Promise<string>;

/**
 * Get attribute value of an element
 * @param selector - Element selector
 * @param name - Attribute name
 * @param options - Attribute options
 * @returns Attribute value or null
 */
getAttribute(selector: string, name: string, options?: PageGetAttributeOptions): Promise<string | null>;

// Get page information
const title = await page.title();
const url = page.url();
const content = await page.content();

// Extract element content
const headerText = await page.textContent('h1');
const emailValue = await page.getAttribute('input[name="email"]', 'value');
const divHtml = await page.innerHTML('div.content');

// Set page content
await page.setContent('<html><body><h1>Test Page</h1></body></html>');

/**
 * Execute JavaScript in the page context
 * @param pageFunction - Function to execute
 * @param arg - Optional argument to pass
 * @returns Serializable result
 */
evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<R>;

/**
 * Execute JavaScript and return a JSHandle
 * @param pageFunction - Function to execute
 * @param arg - Optional argument to pass
 * @returns JSHandle to the result
 */
evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<JSHandle<R>>;

/**
 * Add a script tag to the page
 * @param options - Script options
 * @returns ElementHandle to the script tag
 */
addScriptTag(options: PageAddScriptTagOptions): Promise<ElementHandle>;

/**
 * Add a style tag to the page
 * @param options - Style options
 * @returns ElementHandle to the style tag
 */
addStyleTag(options: PageAddStyleTagOptions): Promise<ElementHandle>;

// Execute JavaScript and get result
const result = await page.evaluate(() => {
  return document.querySelectorAll('a').length;
});

// Pass arguments to page function
const text = await page.evaluate((selector) => {
  return document.querySelector(selector)?.textContent;
}, 'h1');

// Get JSHandle for complex objects
const windowHandle = await page.evaluateHandle(() => window);
const location = await windowHandle.getProperty('location');

// Add external script
await page.addScriptTag({ url: 'https://code.jquery.com/jquery-3.6.0.min.js' });

// Add inline script
await page.addScriptTag({
  content: 'window.myVariable = "test";'
});

// Add CSS styles
await page.addStyleTag({
  content: 'body { background-color: red; }'
});

/**
 * Wait for an element to appear
 * @param selector - Element selector
 * @param options - Wait options
 * @returns ElementHandle or null
 */
waitForSelector(selector: string, options?: PageWaitForSelectorOptions): Promise<ElementHandle | null>;

/**
 * Wait for a JavaScript function to return truthy
 * @param pageFunction - Function to evaluate
 * @param arg - Optional argument
 * @param options - Wait options
 * @returns Result of the function
 */
waitForFunction<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg, options?: PageWaitForFunctionOptions): Promise<JSHandle<R>>;

/**
 * Wait for a page event
 * @param event - Event name
 * @param optionsOrPredicate - Options or predicate function
 * @returns Event data
 */
waitForEvent(event: string, optionsOrPredicate?: PageWaitForEventOptions | Function): Promise<any>;

/**
 * Wait for URL to match pattern
 * @param url - URL pattern
 * @param options - Wait options
 */
waitForURL(url: string | RegExp | ((url: URL) => boolean), options?: PageWaitForURLOptions): Promise<void>;

/**
 * Wait for page load state
 * @param state - Load state to wait for
 * @param options - Wait options
 */
waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle', options?: PageWaitForLoadStateOptions): Promise<void>;

/**
 * Wait for specified timeout
 * @param timeout - Timeout in milliseconds
 */
waitForTimeout(timeout: number): Promise<void>;

// Wait for elements
await page.waitForSelector('.loading', { state: 'hidden' });
await page.waitForSelector('button.submit', { state: 'visible' });

// Wait for custom conditions
await page.waitForFunction(() => {
  return document.querySelectorAll('.item').length > 10;
});

// Wait for events
const response = await page.waitForEvent('response', response => {
  return response.url().includes('/api/data');
});

// Wait for navigation
await Promise.all([
  page.waitForNavigation(),
  page.click('a.next-page')
]);

// Wait for load states
await page.waitForLoadState('networkidle');
await page.waitForURL('**/dashboard/**');

/**
 * Take a screenshot of the page
 * @param options - Screenshot options
 * @returns Buffer containing image data
 */
screenshot(options?: PageScreenshotOptions): Promise<Buffer>;

/**
 * Generate a PDF of the page
 * @param options - PDF options
 * @returns Buffer containing PDF data
 */
pdf(options?: PagePdfOptions): Promise<Buffer>;

// Full page screenshot
await page.screenshot({ path: 'page.png' });

// Element screenshot
await page.screenshot({
  path: 'element.png',
  clip: { x: 0, y: 0, width: 300, height: 200 }
});

// Screenshot options
await page.screenshot({
  path: 'page.jpg',
  type: 'jpeg',
  quality: 80,
  fullPage: true
});

// Generate PDF
await page.pdf({
  path: 'page.pdf',
  format: 'A4',
  printBackground: true
});

interface PageGotoOptions {
  /** When to consider navigation complete */
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
  /** Maximum navigation time in milliseconds */
  timeout?: number;
  /** Referer header value */
  referer?: string;
}

interface PageReloadOptions {
  /** When to consider reload complete */
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
  /** Maximum reload time in milliseconds */
  timeout?: number;
}

interface PageClickOptions {
  /** Which button to click */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
  /** Time to wait between mousedown and mouseup */
  delay?: number;
  /** Exact position to click */
  position?: { x: number; y: number; };
  /** Modifier keys to hold */
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
  /** Whether to bypass actionability checks */
  force?: boolean;
  /** Actions that do not have a target element should be performed on this element */
  trial?: boolean;
  /** Maximum time to wait for element */
  timeout?: number;
}

interface PageFillOptions {
  /** Whether to bypass actionability checks */
  force?: boolean;
  /** Actions that do not have a target element should be performed on this element */
  trial?: boolean;
  /** Maximum time to wait for element */
  timeout?: number;
}

interface PageTypeOptions {
  /** Time to wait between key presses */
  delay?: number;
  /** Maximum time to wait for element */
  timeout?: number;
}

interface PageWaitForSelectorOptions {
  /** Element state to wait for */
  state?: 'attached' | 'detached' | 'visible' | 'hidden';
  /** Maximum time to wait */
  timeout?: number;
}

interface PageWaitForFunctionOptions {
  /** Maximum time to wait */
  timeout?: number;
  /** Polling interval */
  polling?: number | 'raf';
}

interface PageWaitForEventOptions {
  /** Maximum time to wait for event */
  timeout?: number;
  /** Predicate function to filter events */
  predicate?: Function;
}

interface PageScreenshotOptions {
  /** File path to save screenshot */
  path?: string;
  /** Image type */
  type?: 'png' | 'jpeg';
  /** JPEG quality (0-100) */
  quality?: number;
  /** Omits default background */
  omitBackground?: boolean;
  /** Capture full scrollable page */
  fullPage?: boolean;
  /** Clip area to screenshot */
  clip?: { x: number; y: number; width: number; height: number; };
  /** Hides default caret */
  caret?: 'hide' | 'initial';
  /** Scale factor for high-DPI displays */
  scale?: 'css' | 'device';
  /** Screenshot animations */
  animations?: 'disabled' | 'allow';
}