testdriverai 7.3.12 → 7.3.13

package/.github/skills/testdriver:focus-application/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: testdriver:focus-application
+description: Bring an application window to the foreground
+---
+<!-- Generated from focus-application.mdx. DO NOT EDIT. -->
+
+## 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.extract('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();
+  });
+
+  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.extract('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/exec) - Launch applications with PowerShell
+- [`pressKeys()`](/v7/press-keys) - Use Alt+Tab to switch windows
+- [`find()`](/v7/find) - Locate elements in the focused window

package/.github/skills/testdriver:generating-tests/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: testdriver:generating-tests
+description: Use AI coding agents and exploration mode to generate TestDriver tests
+---
+<!-- Generated from generating-tests.mdx. DO NOT EDIT. -->
+
+## Instructions for Coding Agents
+
+We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agent instructions file.
+
+<Card title="TestDriver Agent Instructions" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md?plain=1">
+  Copy the current version of our agent instructions to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
+</Card>
+
+Then, you can prompt your coding agent to generate tests. Here is an example prompt:
+
+```md
+Make me a TestDriver test that does the following steps:
+
+Navigate to practicetestautomation.com
+Type username student into Username field
+Type password Password123 into Password field
+Push Submit button
+Verify new page contains expected text 'logged in'
+```
+
+## AI Exploration Mode
+
+Within a test, the `ai()` method lets TestDriver autonomously figure out how to accomplish a task. It's useful for dynamic or unpredictable UIs where explicit actions may be difficult to define.
+
+```javascript
+// Handle dynamic or unpredictable UI
+await testdriver.ai('dismiss any popups or modals that appear');
+```
+
+<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>

package/.github/skills/testdriver:hover/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: testdriver:hover
+description: Hover over elements or coordinates
+---
+<!-- Generated from hover.mdx. DO NOT EDIT. -->
+
+## 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.extract('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();
+  });
+
+  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.extract('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/find) - Locate elements to hover
+- [`click()`](/v7/click) - Click after hovering
+- [`mouseDown()`](/v7/click) - Start drag operations

package/.github/skills/testdriver:locating-elements/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: testdriver:locating-elements
+description: Find UI elements using natural language descriptions
+---
+<!-- Generated from locating-elements.mdx. DO NOT EDIT. -->
+
+## Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+## Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+## Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```

package/.github/skills/testdriver:making-assertions/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: testdriver:making-assertions
+description: Verify application state with AI-powered assertions
+---
+<!-- Generated from making-assertions.mdx. DO NOT EDIT. -->
+
+## Making Assertions
+
+Use AI-powered assertions to verify application state:
+
+```javascript
+// Verify visibility
+await testdriver.assert('login page is displayed');
+await testdriver.assert('submit button is visible');
+await testdriver.assert('loading spinner is not visible');
+
+// Verify content
+await testdriver.assert('page title is "Welcome"');
+await testdriver.assert('success message says "Account created"');
+await testdriver.assert('error message contains "Invalid email"');
+
+// Verify state
+await testdriver.assert('checkbox is checked');
+await testdriver.assert('dropdown shows "United States"');
+await testdriver.assert('button is disabled');
+
+// Verify visual appearance
+await testdriver.assert('submit button is blue');
+await testdriver.assert('form has red border');
+```
+
+<Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>