Browser Control & Navigation

/**
 * Initialize WebDriver session with configured capabilities
 * @returns Promise resolving when session is ready
 */
browser.init();

/**
 * End the current WebDriver session gracefully
 * @param endSession - Whether to close browser (default: true)
 * @returns Promise resolving when session ended
 */
browser.end(endSession?: boolean);

/**
 * Quit the WebDriver session immediately
 * @returns Promise resolving when session terminated
 */
browser.quit();

/**
 * Pause test execution for specified duration
 * @param ms - Milliseconds to pause
 * @returns Promise resolving after pause
 */
browser.pause(ms: number);

/**
 * Enter interactive debug mode
 * @returns Promise resolving when debug session ends
 */
browser.debug();

/**
 * Perform sequence of WebDriver actions
 * @param actions - Array of actions to perform
 * @returns Promise resolving when actions complete
 */
browser.perform(actions: Action[]);

// Initialize session at test start
browser.init();

// Pause execution
browser.pause(2000); // Wait 2 seconds

// End session at test completion
browser.end();

/**
 * Navigate to specified URL
 * @param url - URL to navigate to
 * @returns Promise resolving when navigation completes
 */
browser.url(url: string);

/**
 * Navigate back in browser history
 * @returns Promise resolving when navigation completes
 */
browser.back();

/**
 * Navigate forward in browser history
 * @returns Promise resolving when navigation completes
 */
browser.forward();

/**
 * Refresh the current page
 * @returns Promise resolving when page reloads
 */
browser.refresh();

/**
 * Get current page URL
 * @returns Promise resolving with current URL
 */
browser.getCurrentUrl(): Promise<string>;

/**
 * Get page title
 * @returns Promise resolving with page title
 */
browser.getTitle(): Promise<string>;

/**
 * Get or set URL hash fragment
 * @param hash - Hash to set (optional)
 * @returns Promise resolving with current hash
 */
browser.urlHash(hash?: string): Promise<string>;

// Navigate to page
browser.url("https://example.com");

// Navigate back and forward
browser.back();
browser.forward();

// Get current location
browser.getCurrentUrl().then(url => {
  console.log("Current URL:", url);
});

/**
 * Maximize browser window
 * @returns Promise resolving when window maximized
 */
browser.maximizeWindow();

/**
 * Resize window to specific dimensions
 * @param width - Window width in pixels
 * @param height - Window height in pixels
 * @returns Promise resolving when window resized
 */
browser.resizeWindow(width: number, height: number);

/**
 * Get current window dimensions
 * @returns Promise resolving with window size object
 */
browser.getWindowSize(): Promise<{width: number, height: number}>;

/**
 * Set window dimensions
 * @param width - Window width in pixels
 * @param height - Window height in pixels
 * @returns Promise resolving when size set
 */
browser.setWindowSize(width: number, height: number);

/**
 * Get current window position
 * @returns Promise resolving with position object
 */
browser.getWindowPosition(): Promise<{x: number, y: number}>;

/**
 * Set window position
 * @param x - X coordinate in pixels
 * @param y - Y coordinate in pixels
 * @returns Promise resolving when position set
 */
browser.setWindowPosition(x: number, y: number);

/**
 * Get window rectangle (position and size)
 * @returns Promise resolving with rectangle object
 */
browser.getWindowRect(): Promise<{x: number, y: number, width: number, height: number}>;

/**
 * Set window rectangle
 * @param options - Rectangle properties
 * @returns Promise resolving when rectangle set
 */
browser.setWindowRect(options: {x?: number, y?: number, width?: number, height?: number});

// Maximize window for consistent testing
browser.maximizeWindow();

// Set specific window size
browser.setWindowSize(1024, 768);

// Position window
browser.setWindowPosition(100, 100);

/**
 * Get complete page HTML source
 * @returns Promise resolving with HTML source string
 */
browser.pageSource(): Promise<string>;

/**
 * Capture and save screenshot
 * @param filename - Path to save screenshot
 * @returns Promise resolving when screenshot saved
 */
browser.saveScreenshot(filename: string);

/**
 * Save DOM snapshot to file
 * @param filename - Path to save snapshot
 * @returns Promise resolving when snapshot saved
 */
browser.saveSnapshot(filename: string);

/**
 * Inject JavaScript into page
 * @param script - JavaScript code to inject
 * @returns Promise resolving when script injected
 */
browser.injectScript(script: string);

/**
 * Execute synchronous JavaScript
 * @param script - JavaScript code to execute
 * @param args - Arguments to pass to script
 * @returns Promise resolving with script result
 */
browser.executeScript(script: string | Function, ...args: any[]): Promise<any>;

/**
 * Execute asynchronous JavaScript
 * @param script - JavaScript code to execute
 * @param args - Arguments to pass to script
 * @returns Promise resolving with script result
 */
browser.executeAsyncScript(script: string | Function, ...args: any[]): Promise<any>;

// Capture screenshot
browser.saveScreenshot("./screenshots/test-result.png");

// Execute JavaScript
browser.executeScript("return document.title;").then(title => {
  console.log("Page title:", title);
});

// Get page source
browser.pageSource().then(html => {
  console.log("Page HTML length:", html.length);
});

/**
 * Get specific cookie by name
 * @param name - Cookie name
 * @returns Promise resolving with cookie object
 */
browser.getCookie(name: string): Promise<Cookie>;

/**
 * Get all cookies for current domain
 * @returns Promise resolving with array of cookies
 */
browser.getCookies(): Promise<Cookie[]>;

/**
 * Set cookie with properties
 * @param cookie - Cookie object to set
 * @returns Promise resolving when cookie set
 */
browser.setCookie(cookie: Cookie);

/**
 * Delete specific cookie by name
 * @param name - Cookie name to delete
 * @returns Promise resolving when cookie deleted
 */
browser.deleteCookie(name: string);

/**
 * Delete all cookies for current domain
 * @returns Promise resolving when cookies deleted
 */
browser.deleteCookies();

interface Cookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  expires?: Date;
  httpOnly?: boolean;
  secure?: boolean;
}

// Set authentication cookie
browser.setCookie({
  name: "auth_token",
  value: "abc123",
  domain: "example.com",
  path: "/",
  httpOnly: true
});

// Get specific cookie
browser.getCookie("auth_token").then(cookie => {
  console.log("Auth token:", cookie.value);
});

// Clear all cookies
browser.deleteCookies();

/**
 * Use CSS selector strategy for element finding
 * @returns Promise resolving when strategy set
 */
browser.useCss();

/**
 * Use XPath selector strategy for element finding
 * @returns Promise resolving when strategy set
 */
browser.useXpath();

// Switch to XPath strategy
browser.useXpath();
browser.click("//button[@type='submit']");

// Switch back to CSS strategy
browser.useCss();
browser.click("button[type='submit']");

/**
 * Execute commands within element context
 * @param selector - Element selector for context
 * @param callback - Function to execute in context
 * @returns Promise resolving when context operations complete
 */
browser.within(selector: string, callback: (api: NightwatchAPI) => void);

// Execute commands within a form context
browser.within("#login-form", (form) => {
  form.setValue("input[name='username']", "testuser");
  form.setValue("input[name='password']", "password123");
  form.click("button[type='submit']");
});