testdriverai 6.2.2 → 7.1.0

package/docs/v7/api/focusApplication.mdx

@@ -0,0 +1,294 @@
+---
+title: "focusApplication()"
+sidebarTitle: "focusApplication"
+description: "Bring an application window to the foreground"
+icon: "window-maximize"
+---
+
+## Overview
+
+Bring a specific application window to the foreground and make it the active window for interactions.
+
+## Syntax
+
+```javascript
+await testdriver.focusApplication(name)
+```
+
+## Parameters
+
+<ParamField path="name" type="string" required>
+  Application name (e.g., `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
+</ParamField>
+
+## Returns
+
+`Promise<string>` - Result message
+
+## Examples
+
+### Common Applications
+
+```javascript
+// Focus Chrome browser
+await testdriver.focusApplication('Google Chrome');
+
+// Focus Edge browser
+await testdriver.focusApplication('Microsoft Edge');
+
+// Focus Notepad
+await testdriver.focusApplication('Notepad');
+
+// Focus File Explorer
+await testdriver.focusApplication('File Explorer');
+
+// Focus Visual Studio Code
+await testdriver.focusApplication('Visual Studio Code');
+```
+
+### After Opening Applications
+
+```javascript
+// Open Chrome and focus it
+await testdriver.exec('pwsh', `
+  Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "https://example.com"
+`, 5000);
+
+await new Promise(r => setTimeout(r, 2000)); // Wait for launch
+
+// Focus the Chrome window
+await testdriver.focusApplication('Google Chrome');
+```
+
+## Best Practices
+
+<Check>
+  **Focus before UI interactions**
+  
+  Always focus the target application before interacting with its UI:
+  
+  ```javascript
+  await testdriver.focusApplication('Google Chrome');
+  
+  const button = await testdriver.find('submit button');
+  await button.click();
+  ```
+</Check>
+
+<Check>
+  **Wait after launching apps**
+  
+  Give applications time to open before focusing:
+  
+  ```javascript
+  await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
+  await new Promise(r => setTimeout(r, 1000)); // Wait for launch
+  await testdriver.focusApplication('Notepad');
+  ```
+</Check>
+
+<Check>
+  **Use exact application names**
+  
+  ```javascript
+  // ✅ Correct
+  await testdriver.focusApplication('Google Chrome');
+  
+  // ❌ May not work
+  await testdriver.focusApplication('Chrome');
+  await testdriver.focusApplication('chrome.exe');
+  ```
+</Check>
+
+<Warning>
+  **Application must be running**
+  
+  The application must already be running. `focusApplication()` won't launch applications, only bring existing windows to the foreground.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Multi-Application Testing">
+    ```javascript
+    // Test workflow across multiple apps
+    await testdriver.focusApplication('Google Chrome');
+    const data = await testdriver.remember('the order number');
+    
+    await testdriver.focusApplication('Notepad');
+    await testdriver.type(data);
+    await testdriver.pressKeys(['ctrl', 's']);
+    
+    await testdriver.focusApplication('Google Chrome');
+    const nextButton = await testdriver.find('next button');
+    await nextButton.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Browser Switching">
+    ```javascript
+    // Compare behavior in different browsers
+    await testdriver.focusApplication('Google Chrome');
+    await testdriver.assert('page loaded correctly in Chrome');
+    
+    await testdriver.focusApplication('Microsoft Edge');
+    await testdriver.assert('page loaded correctly in Edge');
+    ```
+  </Accordion>
+  
+  <Accordion title="Desktop Application Testing">
+    ```javascript
+    // Launch and focus desktop app
+    await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
+    await new Promise(r => setTimeout(r, 1000));
+    
+    await testdriver.focusApplication('Notepad');
+    await testdriver.type('Test content');
+    ```
+  </Accordion>
+  
+  <Accordion title="Window Management">
+    ```javascript
+    // Show desktop first
+    await testdriver.pressKeys(['winleft', 'd']);
+    
+    // Click desktop icon
+    const icon = await testdriver.find('Chrome icon on desktop');
+    await icon.click();
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Focus the opened window
+    await testdriver.focusApplication('Google Chrome');
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Common Application Names
+
+### Browsers
+- `'Google Chrome'`
+- `'Microsoft Edge'`
+- `'Mozilla Firefox'`
+- `'Safari'` (macOS)
+
+### Office Applications
+- `'Microsoft Word'`
+- `'Microsoft Excel'`
+- `'Microsoft PowerPoint'`
+- `'Microsoft Outlook'`
+
+### Development Tools
+- `'Visual Studio Code'`
+- `'Visual Studio'`
+- `'IntelliJ IDEA'`
+- `'Sublime Text'`
+
+### System Applications
+- `'Notepad'`
+- `'File Explorer'`
+- `'Command Prompt'`
+- `'Windows PowerShell'`
+- `'Task Manager'`
+
+### Communication
+- `'Microsoft Teams'`
+- `'Slack'`
+- `'Discord'`
+- `'Zoom'`
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Multi-Application Workflow', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect({ newSandbox: true });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should work across multiple applications', async () => {
+    // Start in browser
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Get data from web page
+    const orderNumber = await testdriver.remember('the order number');
+    console.log('Order:', orderNumber);
+    
+    // Open Notepad
+    await testdriver.exec('pwsh', 'Start-Process notepad', 5000);
+    await new Promise(r => setTimeout(r, 1500));
+    
+    // Focus Notepad and save data
+    await testdriver.focusApplication('Notepad');
+    await testdriver.type(`Order Number: ${orderNumber}`);
+    await testdriver.type('\n');
+    await testdriver.type(`Date: ${new Date().toISOString()}`);
+    
+    // Save file
+    await testdriver.pressKeys(['ctrl', 's']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    await testdriver.type('C:\\order-info.txt');
+    await testdriver.pressKeys(['enter']);
+    
+    // Return to browser
+    await testdriver.focusApplication('Google Chrome');
+    
+    const confirmButton = await testdriver.find('confirm order button');
+    await confirmButton.click();
+    
+    await testdriver.assert('order confirmed');
+  });
+
+  it('should switch between browser tabs', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Open new tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Navigate to URL
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Ensure Chrome is still focused
+    await testdriver.focusApplication('Google Chrome');
+    
+    await testdriver.assert('example.com page is loaded');
+  });
+
+  it('should handle dialog boxes', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    const deleteButton = await testdriver.find('delete account button');
+    await deleteButton.click();
+    
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Dialog appears - make sure it's focused
+    await testdriver.focusApplication('Google Chrome');
+    
+    const confirmBtn = await testdriver.find('confirm deletion button');
+    await confirmBtn.click();
+  });
+});
+```
+
+## Related Methods
+
+- [`exec()`](/v7/api/exec) - Launch applications with PowerShell
+- [`pressKeys()`](/v7/api/pressKeys) - Use Alt+Tab to switch windows
+- [`find()`](/v7/api/find) - Locate elements in the focused window

package/docs/v7/api/hover.mdx

@@ -0,0 +1,279 @@
+---
+title: "hover()"
+sidebarTitle: "hover"
+description: "Hover over elements or coordinates"
+icon: "hand-pointer"
+---
+
+## Overview
+
+Move the mouse cursor over elements or specific coordinates without clicking, useful for revealing tooltips, dropdowns, and hover effects.
+
+## Element Hover
+
+Hover over a located element.
+
+### Syntax
+
+```javascript
+await element.hover()
+```
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Find and hover
+const tooltip = await testdriver.find('info icon');
+await tooltip.hover();
+
+// Wait to see tooltip
+await new Promise(r => setTimeout(r, 1000));
+
+// Hover over menu to reveal submenu
+const menu = await testdriver.find('Products menu');
+await menu.hover();
+
+const submenu = await testdriver.find('Laptops submenu item');
+await submenu.click();
+```
+
+## Coordinate Hover
+
+Hover at specific screen coordinates.
+
+### Syntax
+
+```javascript
+await testdriver.hover(x, y)
+```
+
+### Parameters
+
+<ParamField path="x" type="number" required>
+  X coordinate
+</ParamField>
+
+<ParamField path="y" type="number" required>
+  Y coordinate
+</ParamField>
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Hover at coordinates
+await testdriver.hover(500, 300);
+
+// Hover and wait
+await testdriver.hover(500, 300);
+await new Promise(r => setTimeout(r, 1000));
+```
+
+## Best Practices
+
+<Check>
+  **Prefer element hover over coordinates**
+  
+  ```javascript
+  // ✅ Preferred
+  const icon = await testdriver.find('info icon');
+  await icon.hover();
+  
+  // ❌ Avoid
+  await testdriver.hover(500, 300);
+  ```
+</Check>
+
+<Check>
+  **Wait after hovering for dynamic content**
+  
+  ```javascript
+  const menuItem = await testdriver.find('Settings menu');
+  await menuItem.hover();
+  
+  // Wait for submenu to appear
+  await new Promise(r => setTimeout(r, 500));
+  
+  const subItem = await testdriver.find('Profile submenu');
+  await subItem.click();
+  ```
+</Check>
+
+<Check>
+  **Verify element was found before hovering**
+  
+  ```javascript
+  const element = await testdriver.find('tooltip trigger');
+  if (!element.found()) {
+    throw new Error('Element not found');
+  }
+  await element.hover();
+  ```
+</Check>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Tooltips">
+    ```javascript
+    // Hover to show tooltip
+    const icon = await testdriver.find('help icon');
+    await icon.hover();
+    
+    await new Promise(r => setTimeout(r, 1000));
+    
+    // Read tooltip content
+    const tooltipText = await testdriver.remember('the tooltip text');
+    console.log('Tooltip:', tooltipText);
+    ```
+  </Accordion>
+  
+  <Accordion title="Dropdown Menus">
+    ```javascript
+    // Hover to reveal dropdown
+    const menuItem = await testdriver.find('Products menu item');
+    await menuItem.hover();
+    
+    // Wait for dropdown animation
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Click submenu option
+    const category = await testdriver.find('Electronics category');
+    await category.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Image Previews">
+    ```javascript
+    // Hover over thumbnail to see preview
+    const thumbnail = await testdriver.find('product thumbnail');
+    await thumbnail.hover();
+    
+    await new Promise(r => setTimeout(r, 800));
+    
+    // Verify preview appears
+    await testdriver.assert('product preview is displayed');
+    ```
+  </Accordion>
+  
+  <Accordion title="Hover Effects">
+    ```javascript
+    // Test hover state styling
+    const button = await testdriver.find('call to action button');
+    await button.hover();
+    
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Verify hover effect
+    await testdriver.assert('button background changed to blue');
+    ```
+  </Accordion>
+  
+  <Accordion title="Drag and Drop">
+    ```javascript
+    // Use hover in drag and drop
+    const item = await testdriver.find('draggable item');
+    await item.mouseDown();
+    
+    // Hover over drop zone
+    const dropZone = await testdriver.find('drop area');
+    await dropZone.hover();
+    
+    await new Promise(r => setTimeout(r, 300));
+    await dropZone.mouseUp();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Hover Interactions', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect({ newSandbox: true });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should show tooltip on hover', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find and hover over icon
+    const infoIcon = await testdriver.find('information icon');
+    await infoIcon.hover();
+    
+    // Wait for tooltip to appear
+    await new Promise(r => setTimeout(r, 1000));
+    
+    // Verify tooltip is visible
+    await testdriver.assert('tooltip is displayed');
+    
+    // Extract tooltip text
+    const tooltipText = await testdriver.remember('the tooltip message');
+    console.log('Tooltip says:', tooltipText);
+  });
+
+  it('should navigate dropdown menu', async () => {
+    // Hover over main menu
+    const menu = await testdriver.find('Navigation menu');
+    await menu.hover();
+    
+    // Wait for dropdown
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Hover over submenu item
+    const submenu = await testdriver.find('Account submenu');
+    await submenu.hover();
+    
+    await new Promise(r => setTimeout(r, 300));
+    
+    // Click nested menu item
+    const settings = await testdriver.find('Settings option');
+    await settings.click();
+    
+    await testdriver.assert('settings page is displayed');
+  });
+
+  it('should preview images on hover', async () => {
+    // Hover over product image
+    const productImg = await testdriver.find('product 1 thumbnail');
+    await productImg.hover();
+    
+    // Wait for preview
+    await new Promise(r => setTimeout(r, 800));
+    
+    // Verify preview appeared
+    await testdriver.assert('large product preview is shown');
+    
+    // Move away
+    const otherElement = await testdriver.find('page heading');
+    await otherElement.hover();
+    
+    // Verify preview disappeared
+    await new Promise(r => setTimeout(r, 500));
+    await testdriver.assert('product preview is hidden');
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/api/find) - Locate elements to hover
+- [`click()`](/v7/api/click) - Click after hovering
+- [`mouseDown()`](/v7/api/click) - Start drag operations