testdriverai 6.2.2 → 7.0.0

package/SDK_MIGRATION.md

@@ -0,0 +1,474 @@
+# TestDriver SDK Migration Guide
+
+## New Element Finding API
+
+We've introduced a new, more flexible API for finding and interacting with elements. The new `find()` API provides better control and enables polling patterns for dynamic content.
+
+## Quick Comparison
+
+### Old API (Deprecated)
+
+```javascript
+// Find and click text
+await client.hoverText("Sign In", "black button below password", "click");
+
+// Wait for text to appear
+await client.waitForText("Login button", 10000);
+
+// Find and click image
+await client.hoverImage("submit button icon", "click");
+```
+
+### New API (Recommended)
+
+```javascript
+// Find and click text or image
+const element = await client
+  .find("Sign In, black button below password")
+  .find();
+await element.click();
+
+// Poll until element appears (replaces waitForText/waitForImage)
+let element = client.find("login button");
+while (!element.found()) {
+  console.log("waiting for element to be found");
+  element = await element.find();
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+}
+await element.click();
+```
+
+## Migration Examples
+
+### Example 1: Simple Click
+
+**Before:**
+
+```javascript
+await client.hoverText("Submit", "submit button", "click");
+```
+
+**After:**
+
+```javascript
+const submitBtn = await client.find("Submit button");
+await submitBtn.click();
+```
+
+### Example 2: Waiting for Elements
+
+**Before:**
+
+```javascript
+await client.waitForText("Welcome", 10000);
+await client.hoverText("Welcome", null, "click");
+```
+
+**After:**
+
+```javascript
+let element;
+const maxAttempts = 10;
+let attempts = 0;
+
+while (!element?.found() && attempts < maxAttempts) {
+  element = await client.find("Welcome");
+  if (!element.found()) {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  attempts++;
+}
+
+if (element?.found()) {
+  await element.click();
+}
+```
+
+### Example 3: Hover Actions
+
+**Before:**
+
+```javascript
+await client.hoverText("Menu", null, "hover");
+```
+
+**After:**
+
+```javascript
+const menu = await client.find("Menu").find();
+await menu.hover();
+```
+
+### Example 4: Different Click Types
+
+**Before:**
+
+```javascript
+await client.hoverText("File", null, "right-click");
+await client.hoverText("Save", null, "double-click");
+```
+
+**After:**
+
+```javascript
+const file = await client.find("File").find();
+await file.rightClick();
+
+const save = await client.find("Save").find();
+await save.doubleClick();
+
+// Or use the generic click() method
+await file.click("right-click");
+await save.click("double-click");
+```
+
+### Example 5: Conditional Logic
+
+**Before:**
+
+```javascript
+try {
+  await client.waitForText("Error message", 2000);
+  // Handle error
+} catch (e) {
+  // No error present
+}
+```
+
+**After:**
+
+```javascript
+const errorMsg = await client.find("Error message").find();
+if (errorMsg.found()) {
+  // Handle error
+  console.log("Error found at:", errorMsg.getCoordinates());
+} else {
+  // No error present
+}
+```
+
+## New Element API Reference
+
+### `client.find(description)`
+
+Creates an Element instance for finding and interacting with elements.
+
+**Parameters:**
+
+- `description` (string): Natural language description of the element
+
+**Returns:** `Element` instance
+
+**Example:**
+
+```javascript
+const button = client.find("the sign in button");
+```
+
+### `element.find([newDescription])`
+
+Attempts to locate the element on screen.
+
+**Parameters:**
+
+- `newDescription` (optional string): New description to search for
+
+**Returns:** `Promise<Element>` - The same Element instance (for chaining)
+
+**Example:**
+
+```javascript
+const element = await client.find("login button").find();
+
+// Or with a new description
+element = await element.find("sign in button");
+```
+
+### `element.found()`
+
+Check if the element was successfully located.
+
+**Returns:** `boolean` - true if element coordinates were found
+
+**Example:**
+
+```javascript
+const element = await client.find("button").find();
+if (element.found()) {
+  console.log("Element found!");
+}
+```
+
+### `element.click([action])`
+
+Click on the element.
+
+**Parameters:**
+
+- `action` (optional): Click action type - `'click'`, `'right-click'`, `'double-click'`
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+await element.click();
+await element.click("right-click");
+```
+
+### `element.hover()`
+
+Hover over the element.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+await element.hover();
+```
+
+### `element.doubleClick()`
+
+Double-click on the element. Convenience method for `element.click('double-click')`.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+await element.doubleClick();
+```
+
+### `element.rightClick()`
+
+Right-click on the element. Convenience method for `element.click('right-click')`.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+await element.rightClick();
+```
+
+### `element.mouseDown()`
+
+Press mouse button down on this element (useful for drag operations).
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+const source = await client.find("draggable item").find();
+await source.mouseDown();
+```
+
+### `element.mouseUp()`
+
+Release mouse button on this element (useful for drag operations).
+
+**Returns:** `Promise<void>`
+
+**Example:**
+
+```javascript
+const target = await client.find("drop zone").find();
+await target.mouseUp();
+```
+
+### `element.getCoordinates()`
+
+Get the screen coordinates of the element.
+
+**Returns:** `{x, y, centerX, centerY}` or `null` if not found
+
+**Example:**
+
+```javascript
+const coords = element.getCoordinates();
+if (coords) {
+  console.log(`Element at: ${coords.x}, ${coords.y}`);
+}
+```
+
+### `element.getResponse()`
+
+Get the full API response data from the locate operation.
+
+**Returns:** `Object | null` - Full response containing all available data
+
+**Example:**
+
+```javascript
+const response = element.getResponse();
+console.log("Full response:", response);
+```
+
+## Element Properties
+
+The Element class exposes many properties from the API response:
+
+### Coordinate Properties
+
+- `element.x` - X coordinate (top-left corner)
+- `element.y` - Y coordinate (top-left corner)
+- `element.centerX` - X coordinate of element center
+- `element.centerY` - Y coordinate of element center
+
+### Dimension Properties
+
+- `element.width` - Width of the element (if available)
+- `element.height` - Height of the element (if available)
+- `element.boundingBox` - Bounding box data (if available)
+
+### Match Quality Properties
+
+- `element.confidence` - Confidence score of the match (0-1)
+- `element.screenshot` - Base64 encoded screenshot of the element
+- `element.text` - Text content of the element (if available)
+- `element.label` - Label/aria-label of the element (if available)
+
+### Example Usage
+
+```javascript
+const button = await client.find("login button");
+
+if (button.found()) {
+  console.log("Position:", { x: button.x, y: button.y });
+  console.log("Center:", { x: button.centerX, y: button.centerY });
+  console.log("Size:", { width: button.width, height: button.height });
+  console.log("Confidence:", button.confidence);
+  console.log("Text:", button.text);
+
+  // Save screenshot for debugging
+  if (button.screenshot) {
+    const fs = require("fs");
+    fs.writeFileSync("button.png", Buffer.from(button.screenshot, "base64"));
+  }
+
+  // Conditional actions based on properties
+  if (button.confidence > 0.8) {
+    await button.click();
+  }
+}
+```
+
+For a complete example, see `examples/sdk-element-properties.js`.
+
+## Common Patterns
+
+### Pattern 1: Find and Click
+
+```javascript
+const element = await client.find("description").find();
+if (element.found()) {
+  await element.click();
+}
+```
+
+### Pattern 2: Polling with Timeout
+
+```javascript
+const element = client.find("element description");
+const timeoutMs = 10000;
+const startTime = Date.now();
+
+while (!element.found() && Date.now() - startTime < timeoutMs) {
+  element = await element.find();
+  if (!element.found()) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+}
+
+if (!element.found()) {
+  throw new Error("Element not found within timeout");
+}
+```
+
+### Pattern 3: Retry with Different Descriptions
+
+```javascript
+let element = client.find("primary button");
+element = await element.find();
+
+if (!element.found()) {
+  element = await element.find("submit button");
+}
+
+if (!element.found()) {
+  element = await element.find("blue button on the right");
+}
+
+if (element.found()) {
+  await element.click();
+}
+```
+
+### Pattern 4: Helper Function for Waiting
+
+```javascript
+async function waitForElement(client, description, timeoutMs = 10000) {
+  const element = client.find(description);
+  const startTime = Date.now();
+
+  while (!element.found() && Date.now() - startTime < timeoutMs) {
+    await element.find();
+    if (!element.found()) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+
+  if (!element.found()) {
+    throw new Error(`Element "${description}" not found within ${timeoutMs}ms`);
+  }
+
+  return element;
+}
+
+// Usage
+const button = await waitForElement(client, "login button", 5000);
+await button.click();
+```
+
+## Deprecated Methods
+
+The following methods are now deprecated and will be removed in a future version:
+
+- ❌ `client.hoverText()` → ✅ Use `client.find().find()` + `element.click()`
+- ❌ `client.hoverImage()` → ✅ Use `client.find().find()` + `element.click()`
+- ❌ `client.waitForText()` → ✅ Use polling pattern with `client.find()`
+- ❌ `client.waitForImage()` → ✅ Use polling pattern with `client.find()`
+- ❌ `client.wait()` → ✅ Use element polling instead of arbitrary waits when possible
+
+## Benefits of the New API
+
+1. **More Explicit**: Clear separation between finding and interacting
+2. **Better Error Handling**: Can check if element exists before interacting
+3. **Flexible Polling**: Custom polling logic for dynamic content
+4. **Unified Interface**: Same API for text and images
+5. **More Control**: Access to element state and coordinates
+6. **Composable**: Element instances can be stored and reused
+
+## TypeScript Support
+
+The new API is fully typed:
+
+```typescript
+import TestDriver, { Element } from "testdriverai";
+
+const client = new TestDriver(process.env.TD_API_KEY);
+await client.connect();
+
+const element: Element = await client.find("button").find();
+const found: boolean = element.found();
+const coords = element.getCoordinates(); // {x, y, centerX, centerY} | null
+```
+
+## Questions?
+
+For more examples, see:
+
+- `examples/sdk-find-example.js` - Comprehensive examples of the new API
+- `testdriver/acceptance-sdk/hover-text.test.mjs` - Updated test example