testdriverai 6.2.2 → 7.1.0

package/docs/v7/api/scroll.mdx

@@ -0,0 +1,300 @@
+---
+title: "scroll()"
+sidebarTitle: "scroll"
+description: "Scroll pages and elements"
+icon: "arrows-up-down"
+---
+
+## Overview
+
+Scroll the page or active element in any direction using mouse wheel or keyboard.
+
+## Syntax
+
+```javascript
+await testdriver.scroll(direction, amount, method)
+```
+
+## Parameters
+
+<ParamField path="direction" type="string" default="down">
+  Direction to scroll: `'up'`, `'down'`, `'left'`, `'right'`
+</ParamField>
+
+<ParamField path="amount" type="number" default="300">
+  Amount to scroll in pixels
+</ParamField>
+
+<ParamField path="method" type="string" default="mouse">
+  Scroll method: `'mouse'` or `'keyboard'`
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Examples
+
+### Basic Scrolling
+
+```javascript
+// Scroll down (default)
+await testdriver.scroll();
+
+// Scroll down 500 pixels
+await testdriver.scroll('down', 500);
+
+// Scroll up
+await testdriver.scroll('up');
+
+// Scroll up 200 pixels
+await testdriver.scroll('up', 200);
+```
+
+### Horizontal Scrolling
+
+```javascript
+// Scroll right
+await testdriver.scroll('right', 300);
+
+// Scroll left
+await testdriver.scroll('left', 300);
+```
+
+### Scroll Methods
+
+```javascript
+// Mouse wheel scroll (smooth, pixel-precise)
+await testdriver.scroll('down', 300, 'mouse');
+
+// Keyboard scroll (uses Page Down/Up, more compatible)
+await testdriver.scroll('down', 300, 'keyboard');
+```
+
+## Scroll Until Found
+
+### scrollUntilText()
+
+Scroll until specific text appears on screen.
+
+```javascript
+await testdriver.scrollUntilText(text, direction, maxDistance, textMatchMethod, method, invert)
+```
+
+**Parameters:**
+- `text` (string) - Text to find
+- `direction` (string) - Scroll direction (default: `'down'`)
+- `maxDistance` (number) - Max pixels to scroll (default: 10000)
+- `textMatchMethod` (string) - `'turbo'` or `'ai'` (default: `'turbo'`)
+- `method` (string) - `'keyboard'` or `'mouse'` (default: `'keyboard'`)
+- `invert` (boolean) - Scroll until text disappears (default: false)
+
+**Examples:**
+```javascript
+// Scroll down until "Contact Us" appears
+await testdriver.scrollUntilText('Contact Us');
+
+// Scroll up to find text
+await testdriver.scrollUntilText('Header', 'up');
+
+// Scroll until text disappears
+await testdriver.scrollUntilText('Loading...', 'down', 5000, 'turbo', 'keyboard', true);
+
+// Use AI matching for fuzzy text
+await testdriver.scrollUntilText('footer content', 'down', 10000, 'ai');
+```
+
+### scrollUntilImage()
+
+Scroll until a visual element appears.
+
+```javascript
+await testdriver.scrollUntilImage(description, direction, maxDistance, method, path, invert)
+```
+
+**Parameters:**
+- `description` (string) - Description of the image/element
+- `direction` (string) - Scroll direction (default: `'down'`)
+- `maxDistance` (number) - Max pixels to scroll (default: 10000)
+- `method` (string) - `'keyboard'` or `'mouse'` (default: `'keyboard'`)
+- `path` (string | null) - Path to image template (optional)
+- `invert` (boolean) - Scroll until image disappears (default: false)
+
+**Examples:**
+```javascript
+// Scroll until visual element appears
+await testdriver.scrollUntilImage('red subscribe button');
+
+// Scroll using image template
+await testdriver.scrollUntilImage('', 'down', 10000, 'keyboard', './footer-logo.png');
+
+// Scroll until image disappears
+await testdriver.scrollUntilImage('loading spinner', 'down', 5000, 'keyboard', null, true);
+```
+
+## Best Practices
+
+<Check>
+  **Choose the right scroll method**
+  
+  ```javascript
+  // For web pages, mouse scroll is usually smoother
+  await testdriver.scroll('down', 300, 'mouse');
+  
+  // For desktop apps or when mouse doesn't work
+  await testdriver.scroll('down', 300, 'keyboard');
+  ```
+</Check>
+
+<Check>
+  **Use scrollUntil for dynamic content**
+  
+  ```javascript
+  // Instead of guessing scroll amount
+  await testdriver.scrollUntilText('Load More button');
+  
+  const loadMoreBtn = await testdriver.find('Load More button');
+  await loadMoreBtn.click();
+  ```
+</Check>
+
+<Check>
+  **Set reasonable max distance**
+  
+  ```javascript
+  // Avoid infinite scrolling
+  await testdriver.scrollUntilText('Footer', 'down', 5000); // Max 5000px
+  ```
+</Check>
+
+<Warning>
+  **Keyboard scroll uses Page Down/Up**
+  
+  Keyboard scrolling typically moves by one "page" at a time, which may be more than the specified pixel amount. It's more compatible but less precise than mouse scrolling.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Navigate to Footer">
+    ```javascript
+    // Scroll to bottom of page
+    await testdriver.scrollUntilText('Contact Us');
+    
+    const contactLink = await testdriver.find('Contact Us link');
+    await contactLink.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Load More Results">
+    ```javascript
+    // Scroll to load more button
+    await testdriver.scrollUntilText('Load More');
+    
+    const loadBtn = await testdriver.find('Load More button');
+    await loadBtn.click();
+    
+    await new Promise(r => setTimeout(r, 2000));
+    ```
+  </Accordion>
+  
+  <Accordion title="Find Element in Long List">
+    ```javascript
+    // Scroll through list to find item
+    await testdriver.scrollUntilText('Product #42');
+    
+    const product = await testdriver.find('Product #42');
+    await product.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Infinite Scroll">
+    ```javascript
+    // Scroll multiple times for infinite scroll
+    for (let i = 0; i < 5; i++) {
+      await testdriver.scroll('down', 500);
+      await new Promise(r => setTimeout(r, 1000)); // Wait for load
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Horizontal Gallery">
+    ```javascript
+    // Navigate horizontal carousel
+    await testdriver.scroll('right', 300);
+    await new Promise(r => setTimeout(r, 500));
+    
+    const nextImage = await testdriver.find('next image in carousel');
+    await nextImage.click();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Scrolling', () => {
+  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 scroll to find elements', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Scroll to footer
+    await testdriver.scrollUntilText('Contact Information');
+    
+    // Click footer link
+    const privacyLink = await testdriver.find('Privacy Policy link');
+    await privacyLink.click();
+    
+    await testdriver.assert('privacy policy page is displayed');
+  });
+
+  it('should handle infinite scroll', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Scroll multiple times to load content
+    for (let i = 0; i < 3; i++) {
+      await testdriver.scroll('down', 500);
+      await new Promise(r => setTimeout(r, 1500)); // Wait for load
+    }
+    
+    // Verify content loaded
+    await testdriver.assert('more than 10 items are visible');
+  });
+
+  it('should scroll until loading completes', async () => {
+    // Scroll until loading spinner disappears
+    await testdriver.scrollUntilImage(
+      'loading spinner', 
+      'down', 
+      5000, 
+      'keyboard', 
+      null, 
+      true // invert - wait for it to disappear
+    );
+    
+    // Now interact with loaded content
+    const firstResult = await testdriver.find('first search result');
+    await firstResult.click();
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/api/find) - Locate elements after scrolling
+- [`pressKeys()`](/v7/api/pressKeys) - Use Page Down/Up keys
+- [`wait()`](/v7/api/wait) - Wait after scrolling

package/docs/v7/api/type.mdx

@@ -0,0 +1,314 @@
+---
+title: "type()"
+sidebarTitle: "type"
+description: "Type text into focused input fields"
+icon: "keyboard"
+---
+
+## Overview
+
+Type text or numbers into the currently focused input field with optional delay between keystrokes.
+
+## Syntax
+
+```javascript
+await testdriver.type(text, delay)
+```
+
+## Parameters
+
+<ParamField path="text" type="string | number" required>
+  Text to type (can be a string or number)
+</ParamField>
+
+<ParamField path="delay" type="number" default="250">
+  Delay between keystrokes in milliseconds
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Examples
+
+### Basic Typing
+
+```javascript
+// Type text
+await testdriver.type('hello@example.com');
+
+// Type numbers
+await testdriver.type(12345);
+
+// Type with custom delay
+await testdriver.type('slow typing', 500); // 500ms between each character
+```
+
+### Form Filling
+
+```javascript
+// Focus field and type
+const emailField = await testdriver.find('email input');
+await emailField.click();
+await testdriver.type('user@example.com');
+
+// Tab to next field and type
+await testdriver.pressKeys(['tab']);
+await testdriver.type('John Doe');
+
+// Type password
+await testdriver.pressKeys(['tab']);
+await testdriver.type('MySecureP@ssw0rd');
+```
+
+### Clearing and Replacing Text
+
+```javascript
+const searchBox = await testdriver.find('search input');
+await searchBox.click();
+
+// Clear existing text
+await testdriver.pressKeys(['ctrl', 'a']); // Select all
+await testdriver.type('new search query');
+```
+
+## Best Practices
+
+<Check>
+  **Focus the field first**
+  
+  Always click the input field or navigate to it before typing:
+  
+  ```javascript
+  const input = await testdriver.find('username input');
+  await input.click();
+  await testdriver.type('testuser');
+  ```
+</Check>
+
+<Check>
+  **Use Tab for navigation**
+  
+  Navigate between fields using Tab instead of clicking each one:
+  
+  ```javascript
+  const firstField = await testdriver.find('first name');
+  await firstField.click();
+  await testdriver.type('John');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('Doe');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('john@example.com');
+  ```
+</Check>
+
+<Check>
+  **Clear fields before typing**
+  
+  Clear existing content to avoid appending:
+  
+  ```javascript
+  const input = await testdriver.find('search field');
+  await input.click();
+  await testdriver.pressKeys(['ctrl', 'a']); // Select all
+  await testdriver.type('new search');
+  ```
+</Check>
+
+<Warning>
+  **Field must be focused**
+  
+  Typing will only work if an input field is currently focused. If no field is focused, the text may be lost or trigger unexpected keyboard shortcuts.
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Login Forms">
+    ```javascript
+    await testdriver.focusApplication('Google Chrome');
+    
+    const usernameField = await testdriver.find('username input');
+    await usernameField.click();
+    await testdriver.type('testuser@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MyP@ssword123');
+    
+    await testdriver.pressKeys(['enter']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Search Fields">
+    ```javascript
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    await testdriver.type('laptop computers');
+    await testdriver.pressKeys(['enter']);
+    
+    // Wait for results
+    await new Promise(r => setTimeout(r, 2000));
+    ```
+  </Accordion>
+  
+  <Accordion title="Multi-Field Forms">
+    ```javascript
+    // First field
+    const nameField = await testdriver.find('full name input');
+    await nameField.click();
+    await testdriver.type('Jane Smith');
+    
+    // Navigate with Tab
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('jane.smith@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('+1-555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('123 Main Street');
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Editors">
+    ```javascript
+    const editor = await testdriver.find('text editor area');
+    await editor.click();
+    
+    await testdriver.type('# My Document', 100);
+    await testdriver.pressKeys(['enter', 'enter']);
+    await testdriver.type('This is the first paragraph.', 50);
+    ```
+  </Accordion>
+  
+  <Accordion title="Numeric Input">
+    ```javascript
+    const quantityField = await testdriver.find('quantity input');
+    await quantityField.click();
+    
+    // Clear field
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Type number
+    await testdriver.type(5);
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Typing Speed
+
+Adjust the delay parameter based on your needs:
+
+```javascript
+// Fast typing (100ms delay)
+await testdriver.type('quick entry', 100);
+
+// Normal typing (250ms - default)
+await testdriver.type('standard speed');
+
+// Slow typing (500ms delay) - useful for fields with live validation
+await testdriver.type('slow and steady', 500);
+
+// Very slow (1000ms delay) - for problematic fields
+await testdriver.type('one by one', 1000);
+```
+
+<Note>
+  Some applications with live validation or autocomplete may require slower typing speeds to avoid race conditions.
+</Note>
+
+## Special Characters
+
+```javascript
+// Email addresses
+await testdriver.type('user@example.com');
+
+// URLs
+await testdriver.type('https://example.com/path?query=value');
+
+// Passwords with special characters
+await testdriver.type('P@ssw0rd!#$%');
+
+// Paths
+await testdriver.type('C:\\Users\\Documents\\file.txt');
+
+// Multi-line text (use pressKeys for Enter)
+await testdriver.type('Line 1');
+await testdriver.pressKeys(['enter']);
+await testdriver.type('Line 2');
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Form Filling with Type', () => {
+  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 fill out registration form', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Email field
+    const emailField = await testdriver.find('email input field');
+    await emailField.click();
+    await testdriver.type('john.doe@example.com');
+    
+    // Tab through form fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('MySecureP@ssword123'); // Confirm password
+    
+    // Verify fields were filled
+    const result = await testdriver.assert('all form fields are filled');
+    expect(result).toBeTruthy();
+  });
+
+  it('should update search query', async () => {
+    const searchBox = await testdriver.find('search input');
+    await searchBox.click();
+    
+    // Type initial search
+    await testdriver.type('laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Update search
+    await searchBox.click();
+    await testdriver.pressKeys(['ctrl', 'a']); // Select all
+    await testdriver.type('gaming laptops');
+    await testdriver.pressKeys(['enter']);
+    
+    // Verify new search
+    await testdriver.assert('search results for "gaming laptops" are shown');
+  });
+});
+```
+
+## Related Methods
+
+- [`pressKeys()`](/v7/api/pressKeys) - Press keyboard keys and shortcuts
+- [`find()`](/v7/api/find) - Locate input fields
+- [`click()`](/v7/api/click) - Focus input fields

package/docs/v7/commands/assert.mdx

@@ -0,0 +1,45 @@
+---
+title: "assert"
+sidebarTitle: "assert"
+description: "Validate conditions during a test using the assert command."
+icon: "check"
+mode: "wide"
+---
+
+import Replay from "/snippets/tests/assert-replay.mdx";
+import Example from "/snippets/tests/assert-yaml.mdx";
+
+<Replay />
+<Example />
+
+## Description
+
+The `assert` command validates that a specific condition is true. It ensures that a task completed successfully by checking the screen for the expected outcome. If the condition isn't met, the test will fail.
+
+## Arguments
+
+| Argument | Type      | Description                                                                                                        |
+| -------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `expect` | `string`  | The condition to check. This should describe what you expect to see on the screen.                                 |
+| `async`  | `boolean` | (Optional) If set to `true`, the test will continue without waiting for the assertion to pass. Default is `false`. |
+| `invert` | `boolean` | (Optional) If set to `true`, will fail if the assertion passes.                                                    |
+
+## Example usage
+
+```yaml
+command: assert
+expect: the video is playing
+```
+
+### Example with `async`
+
+```yaml
+command: assert
+expect: There is no error message
+async: true
+```
+
+## Notes
+
+- Use `async: true` to speed up tests by allowing non-blocking assertions. However, the test will still fail if the condition isn't met.
+- Ensure the `expect` string clearly describes the condition to avoid ambiguity.