Browser Automation

/**
 * Clicks a DOM element
 * @param selector - Element selector (string or Selector object)
 * @param options - Click options including modifiers and position
 * @returns Promise resolving to test controller for chaining
 */
click(selector: string | Selector, options?: ClickOptions): Promise<TestController>;

/**
 * Right-clicks a DOM element
 * @param selector - Element selector
 * @param options - Click options
 * @returns Promise resolving to test controller for chaining
 */
rightClick(selector: string | Selector, options?: ClickOptions): Promise<TestController>;

/**
 * Double-clicks a DOM element
 * @param selector - Element selector
 * @param options - Click options
 * @returns Promise resolving to test controller for chaining
 */
doubleClick(selector: string | Selector, options?: ClickOptions): Promise<TestController>;

interface ClickOptions {
    modifiers?: {
        ctrl?: boolean;
        alt?: boolean;
        shift?: boolean;
        meta?: boolean;
    };
    offsetX?: number;
    offsetY?: number;
    caretPos?: number;
    speed?: number;
}

import { Selector } from 'testcafe';

fixture('Click Examples')
    .page('https://example.com');

test('Click operations', async t => {
    // Simple click
    await t.click('#submit-button');
    
    // Click with modifiers
    await t.click('.item', { 
        modifiers: { ctrl: true } 
    });
    
    // Right-click for context menu
    await t.rightClick('.file-item');
    
    // Double-click to edit
    await t.doubleClick('.editable-text');
});

/**
 * Types text into an input element
 * @param selector - Target input element
 * @param text - Text to type
 * @param options - Typing options including speed and replacement mode
 * @returns Promise resolving to test controller for chaining
 */
typeText(selector: string | Selector, text: string, options?: TypeOptions): Promise<TestController>;

/**
 * Selects text in an input element
 * @param selector - Target input element
 * @param startPos - Start position of selection
 * @param endPos - End position of selection
 * @param options - Selection options
 * @returns Promise resolving to test controller for chaining
 */
selectText(selector: string | Selector, startPos?: number, endPos?: number, options?: ActionOptions): Promise<TestController>;

/**
 * Selects all text content in a textarea
 * @param selector - Target textarea element
 * @param startLine - Start line for selection
 * @param startPos - Start position in start line
 * @param endLine - End line for selection
 * @param endPos - End position in end line
 * @param options - Selection options
 * @returns Promise resolving to test controller for chaining
 */
selectTextAreaContent(selector: string | Selector, startLine?: number, startPos?: number, endLine?: number, endPos?: number, options?: ActionOptions): Promise<TestController>;

/**
 * Selects editable content in contenteditable elements
 * @param selector - Target contenteditable element
 * @param startSelector - Start position selector
 * @param endSelector - End position selector
 * @param options - Selection options
 * @returns Promise resolving to test controller for chaining
 */
selectEditableContent(selector: string | Selector, startSelector?: string | Selector, endSelector?: string | Selector, options?: ActionOptions): Promise<TestController>;

interface TypeOptions extends ActionOptions {
    replace?: boolean;
    paste?: boolean;
}

interface ActionOptions {
    speed?: number;
}

test('Text input operations', async t => {
    // Type into input field
    await t.typeText('#username', 'john.doe');
    
    // Replace existing text
    await t.typeText('#email', 'new@example.com', { replace: true });
    
    // Select text range
    await t.selectText('#username', 0, 4); // Select "john"
    
    // Select all content in textarea
    await t.selectTextAreaContent('#description');
});

/**
 * Presses keyboard keys
 * @param keys - Key sequence to press (supports special keys and combinations)
 * @param options - Key press options
 * @returns Promise resolving to test controller for chaining
 */
pressKey(keys: string, options?: ActionOptions): Promise<TestController>;

test('Keyboard input', async t => {
    // Press single key
    await t.pressKey('enter');
    
    // Press key combination
    await t.pressKey('ctrl+a');
    
    // Press sequence of keys
    await t.pressKey('tab tab enter');
    
    // Special keys
    await t.pressKey('left right up down');
    await t.pressKey('home end pageup pagedown');
    await t.pressKey('f1 f2 f3');
});

/**
 * Hovers over an element
 * @param selector - Element to hover over
 * @param options - Hover options
 * @returns Promise resolving to test controller for chaining
 */
hover(selector: string | Selector, options?: HoverOptions): Promise<TestController>;

/**
 * Drags an element
 * @param selector - Element to drag
 * @param dragOffsetX - Horizontal drag distance
 * @param dragOffsetY - Vertical drag distance
 * @param options - Drag options
 * @returns Promise resolving to test controller for chaining
 */
drag(selector: string | Selector, dragOffsetX: number, dragOffsetY: number, options?: DragOptions): Promise<TestController>;

/**
 * Drags an element to another element
 * @param selector - Element to drag
 * @param destinationSelector - Drop target element
 * @param options - Drag options
 * @returns Promise resolving to test controller for chaining
 */
dragToElement(selector: string | Selector, destinationSelector: string | Selector, options?: DragOptions): Promise<TestController>;

interface HoverOptions extends ActionOptions {
    offsetX?: number;
    offsetY?: number;
}

interface DragOptions extends ActionOptions {
    offsetX?: number;
    offsetY?: number;
    destinationOffsetX?: number;
    destinationOffsetY?: number;
    modifiers?: {
        ctrl?: boolean;
        alt?: boolean;
        shift?: boolean;
        meta?: boolean;
    };
}

/**
 * Sets files to upload for file input elements
 * @param selector - File input element selector
 * @param filePath - Path to file(s) to upload
 * @param options - Upload options
 * @returns Promise resolving to test controller for chaining
 */
setFilesToUpload(selector: string | Selector, filePath: string | string[], options?: ActionOptions): Promise<TestController>;

/**
 * Clears file upload input
 * @param selector - File input element selector  
 * @param options - Clear options
 * @returns Promise resolving to test controller for chaining
 */
clearUpload(selector: string | Selector, options?: ActionOptions): Promise<TestController>;

test('File upload', async t => {
    // Upload single file
    await t.setFilesToUpload('#file-input', './uploads/document.pdf');
    
    // Upload multiple files
    await t.setFilesToUpload('#multi-file-input', [
        './uploads/image1.jpg',
        './uploads/image2.png'
    ]);
    
    // Clear upload
    await t.clearUpload('#file-input');
});

/**
 * Navigates to a URL
 * @param url - Target URL to navigate to
 * @param options - Navigation options
 * @returns Promise resolving to test controller for chaining
 */
navigateTo(url: string, options?: ActionOptions): Promise<TestController>;

test('Navigation', async t => {
    // Navigate to specific URL
    await t.navigateTo('https://example.com/login');
    
    // Navigate to relative URL
    await t.navigateTo('/dashboard');
    
    // Navigate back and perform action
    await t
        .navigateTo('https://example.com/page1')
        .click('#next-button')
        .navigateTo('https://example.com/page2');
});

/**
 * Scrolls the page or element
 * @param selector - Element to scroll (or page if not specified)
 * @param scrollLeft - Horizontal scroll position
 * @param scrollTop - Vertical scroll position
 * @param options - Scroll options
 * @returns Promise resolving to test controller for chaining
 */
scroll(selector: string | Selector, scrollLeft: number, scrollTop: number, options?: ActionOptions): Promise<TestController>;

/**
 * Scrolls by offset
 * @param selector - Element to scroll
 * @param x - Horizontal scroll offset
 * @param y - Vertical scroll offset
 * @param options - Scroll options
 * @returns Promise resolving to test controller for chaining
 */
scrollBy(selector: string | Selector, x: number, y: number, options?: ActionOptions): Promise<TestController>;

/**
 * Scrolls element into view
 * @param selector - Element to scroll into view
 * @param options - Scroll options
 * @returns Promise resolving to test controller for chaining
 */
scrollIntoView(selector: string | Selector, options?: ActionOptions): Promise<TestController>;

/**
 * Opens a new browser window
 * @param url - URL to open in new window
 * @returns Promise resolving to test controller for chaining
 */
openWindow(url: string): Promise<TestController>;

/**
 * Closes the current browser window
 * @returns Promise resolving to test controller for chaining
 */
closeWindow(): Promise<TestController>;

/**
 * Switches to a specific browser window
 * @param windowDescriptor - Window to switch to
 * @returns Promise resolving to test controller for chaining
 */
switchToWindow(windowDescriptor: string | WindowDescriptor): Promise<TestController>;

/**
 * Switches to window matching predicate function
 * @param predicate - Function to identify target window
 * @returns Promise resolving to test controller for chaining
 */
switchToWindowByPredicate(predicate: (window: WindowDescriptor) => boolean): Promise<TestController>;

/**
 * Switches to parent window
 * @returns Promise resolving to test controller for chaining
 */
switchToParentWindow(): Promise<TestController>;

/**
 * Switches to previously active window
 * @returns Promise resolving to test controller for chaining
 */
switchToPreviousWindow(): Promise<TestController>;

/**
 * Gets current window descriptor
 * @returns Promise resolving to current window information
 */
getCurrentWindow(): Promise<WindowDescriptor>;

interface WindowDescriptor {
    id: string;
    title: string;
    url: string;
}

/**
 * Switches to iframe context
 * @param selector - Iframe element selector
 * @returns Promise resolving to test controller for chaining
 */
switchToIframe(selector: string | Selector): Promise<TestController>;

/**
 * Switches back to main window context
 * @returns Promise resolving to test controller for chaining
 */
switchToMainWindow(): Promise<TestController>;

/**
 * Sets handler for native browser dialogs
 * @param fn - Function to handle dialog interactions
 * @param options - Dialog handling options
 * @returns Promise resolving to test controller for chaining
 */
setNativeDialogHandler(fn: (type: string, text: string, url: string) => boolean | string, options?: object): Promise<TestController>;

/**
 * Gets history of native dialog interactions
 * @returns Promise resolving to array of dialog interactions
 */
getNativeDialogHistory(): Promise<DialogHistoryItem[]>;

interface DialogHistoryItem {
    type: 'alert' | 'confirm' | 'prompt' | 'beforeunload';
    text: string;
    url: string;
}

/**
 * Gets browser console messages
 * @returns Promise resolving to array of console messages
 */
getBrowserConsoleMessages(): Promise<BrowserConsoleMessage[]>;

/**
 * Gets current Chrome DevTools Protocol session
 * @returns Promise resolving to CDP session object
 */
getCurrentCDPSession(): Promise<CDPSession>;

interface BrowserConsoleMessage {
    type: 'log' | 'info' | 'error' | 'warn';
    text: string;
    source: string;
}

/**
 * Sets the test execution speed
 * @param speed - Speed factor (0.01 to 1, where 1 is maximum speed)
 * @returns Promise resolving to test controller for chaining
 */
setTestSpeed(speed: number): Promise<TestController>;

/**
 * Sets page load timeout
 * @param duration - Timeout duration in milliseconds
 * @returns Promise resolving to test controller for chaining
 */
setPageLoadTimeout(duration: number): Promise<TestController>;

/**
 * Gets browser cookies
 * @param cookies - Cookie names to retrieve (optional, gets all if omitted)
 * @param urls - URLs to get cookies for (optional)
 * @returns Promise resolving to array of cookie objects
 */
getCookies(cookies?: string | string[] | object, urls?: string | string[]): Promise<Cookie[]>;

/**
 * Sets browser cookies
 * @param cookies - Cookie objects or key-value pairs to set
 * @param url - URL to set cookies for (optional)
 * @returns Promise resolving to test controller for chaining
 */
setCookies(cookies: Cookie | Cookie[] | object, url?: string): Promise<TestController>;

/**
 * Deletes browser cookies
 * @param cookies - Cookie names to delete
 * @param urls - URLs to delete cookies from (optional)
 * @returns Promise resolving to test controller for chaining
 */
deleteCookies(cookies: string | string[] | Cookie[], urls?: string | string[]): Promise<TestController>;

interface Cookie {
    name: string;
    value: string;
    domain?: string;
    path?: string;
    expires?: Date;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: 'Strict' | 'Lax' | 'None';
}

/**
 * Takes a screenshot of the entire page or specific element
 * @param options - Screenshot options including path and element selector
 * @returns Promise resolving to test controller for chaining
 */
takeScreenshot(options?: ScreenshotOptions): Promise<TestController>;

/**
 * Takes a screenshot of a specific element
 * @param selector - Element to screenshot
 * @param options - Screenshot options
 * @returns Promise resolving to test controller for chaining
 */
takeElementScreenshot(selector: string | Selector, options?: ScreenshotOptions): Promise<TestController>;

interface ScreenshotOptions {
    path?: string;
    pathPattern?: string;
    fullPage?: boolean;
    thumbnails?: boolean;
}

/**
 * Pauses test execution for specified duration
 * @param timeout - Wait duration in milliseconds
 * @returns Promise resolving to test controller for chaining
 */
wait(timeout: number): Promise<TestController>;

/**
 * Pauses test execution and enters debug mode
 * @param selector - Optional selector to inspect
 * @returns Promise resolving to test controller for chaining
 */
debug(selector?: string | Selector): Promise<TestController>;