testdriverai 7.3.12 → 7.3.13

package/ai/skills/testdriver:screenshot/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: testdriver:screenshot
+description: Capture and save screenshots during test execution
+---
+<!-- Generated from screenshot.mdx. DO NOT EDIT. -->
+
+## Overview
+
+Capture a screenshot of the current screen and automatically save it to a local file. Screenshots are organized by test file for easy debugging and review.
+
+<Note>
+  **Automatic Screenshots (Default: Enabled)**: TestDriver automatically captures screenshots before and after every command (click, type, find, etc.). These are saved with descriptive filenames like `001-click-before-L42-submit-button.png` that include the line number from your test file. You can disable this with `autoScreenshots: false` in your TestDriver options.
+</Note>
+
+## Syntax
+
+```javascript
+const filePath = await testdriver.screenshot(filename)
+```
+
+## Parameters
+
+<ParamField path="filename" type="string" optional>
+  Custom filename for the screenshot (without .png extension). If not provided, a timestamp-based filename is generated automatically.
+</ParamField>
+
+## Returns
+
+`Promise<string>` - The absolute file path where the screenshot was saved
+
+## File Organization
+
+Screenshots are automatically saved to `.testdriver/screenshots/<test-file-name>/` in your project root:
+
+```
+.testdriver/
+  screenshots/
+    login.test/
+      001-find-before-L15-email-input.png     # Auto: before find()
+      002-find-after-L15-email-input.png      # Auto: after find()
+      003-click-before-L16-email-input.png    # Auto: before click()
+      004-click-after-L16-email-input.png     # Auto: after click()
+      005-type-before-L17-userexamplecom.png  # Auto: before type()
+      006-type-after-L17-userexamplecom.png   # Auto: after type()
+      custom-screenshot.png                    # Manual: screenshot("custom-screenshot")
+    checkout.test/
+      001-find-before-L12-checkout-button.png
+      ...
+```
+
+### Automatic Screenshot Naming
+
+When `autoScreenshots` is enabled (default), filenames follow this format:
+
+`<seq>-<action>-<phase>-L<line>-<description>.png`
+
+| Component | Description | Example |
+|-----------|-------------|---------|
+| `seq` | Sequential number (001, 002, ...) | `001` |
+| `action` | Command name | `click`, `type`, `find` |
+| `phase` | Before, after, or error | `before`, `after` |
+| `L<line>` | Line number from test file | `L42` |
+| `description` | Element description or action target | `submit-button` |
+
+<Note>
+  The screenshot folder for each test file is automatically cleared when the test starts. This ensures you only see screenshots from the most recent test run.
+</Note>
+
+## Examples
+
+### Basic Screenshot
+
+```javascript
+// Capture a screenshot with auto-generated filename
+const screenshotPath = await testdriver.screenshot();
+console.log('Screenshot saved to:', screenshotPath);
+```
+
+### Custom Filename
+
+```javascript
+// Save with a descriptive filename
+await testdriver.screenshot("login-page");
+// Saves to: .testdriver/screenshots/<test>/login-page.png
+
+await testdriver.screenshot("after-click");
+// Saves to: .testdriver/screenshots/<test>/after-click.png
+```
+
+### Debugging with Screenshots
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Login Flow", () => {
+  it("should log in successfully", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://myapp.com/login',
+    });
+
+    // Capture initial state
+    await testdriver.screenshot();
+
+    // Fill in login form
+    const emailInput = await testdriver.find("email input");
+    await emailInput.click();
+    await testdriver.type("user@example.com");
+
+    // Capture state after typing
+    await testdriver.screenshot();
+
+    const passwordInput = await testdriver.find("password input");
+    await passwordInput.click();
+    await testdriver.type("password123");
+
+    // Capture before clicking login
+    await testdriver.screenshot();
+
+    const loginButton = await testdriver.find("Login button");
+    await loginButton.click();
+
+    // Capture after login attempt
+    await testdriver.screenshot();
+
+    const result = await testdriver.assert("dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Automatic Screenshots
+
+By default, TestDriver captures screenshots **automatically** before and after every command. This creates a complete visual timeline of your test execution without any additional code.
+
+### Enabling/Disabling
+
+```javascript
+// Auto-screenshots enabled by default
+const testdriver = TestDriver(context);
+
+// Explicitly disable if needed (not recommended)
+const testdriver = TestDriver(context, {
+  autoScreenshots: false
+});
+```
+
+### What Gets Captured
+
+Automatic screenshots are taken around these commands:
+- `find()` / `findAll()`
+- `click()` / `hover()` / `doubleClick()` / `rightClick()`
+- `type()` / `pressKeys()`
+- `scroll()` / `scrollUntilText()` / `scrollUntilImage()`
+- `waitForText()` / `waitForImage()`
+- `focusApplication()`
+- `assert()` / `extract()` / `exec()`
+
+### Example Output
+
+For this test code:
+
+```javascript
+// Line 15: Find email input
+const emailInput = await testdriver.find("email input");
+// Line 16: Click it
+await emailInput.click();
+// Line 17: Type email
+await testdriver.type("user@example.com");
+```
+
+TestDriver automatically saves:
+
+```
+001-find-before-L15-email-input.png
+002-find-after-L15-email-input.png
+003-click-before-L16-email-input.png
+004-click-after-L16-email-input.png
+005-type-before-L17-userexamplecom.png
+006-type-after-L17-userexamplecom.png
+```
+
+If an error occurs, the phase will be `error` instead of `after`.
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Let automatic screenshots do the work">
+    With `autoScreenshots: true` (default), you get comprehensive coverage without adding manual `screenshot()` calls. Only add manual screenshots for specific named checkpoints.
+  </Accordion>
+  
+  <Accordion title="Use screenshots for debugging flaky tests">
+    When a test fails intermittently, add screenshots at key steps to capture the actual screen state. This helps identify timing issues or unexpected UI states.
+  </Accordion>
+
+  <Accordion title="Capture before assertions">
+    Take a screenshot before making assertions. If the assertion fails, you'll have a visual record of what the screen looked like.
+    
+    ```javascript
+    await testdriver.screenshot();
+    const result = await testdriver.assert("checkout button is visible");
+    ```
+  </Accordion>
+
+  <Accordion title="Add to .gitignore">
+    Add `.testdriver/screenshots/` to your `.gitignore` to avoid committing screenshots to version control:
+    
+    ```
+    # .gitignore
+    .testdriver/screenshots/
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Viewing Saved Screenshots
+
+After saving screenshots during test execution, you can view them using TestDriver MCP commands. This is especially useful for debugging failed tests or verifying test behavior.
+
+### MCP Commands for Screenshot Viewing
+
+**List all saved screenshots:**
+
+```
+list_local_screenshots()
+```
+
+**View a specific screenshot:**
+
+```
+view_local_screenshot({ path: "/full/path/to/screenshot.png" })
+```
+
+These commands allow you to:
+- View screenshots from failed tests to understand what went wrong
+- Review test execution flow by examining screenshots in chronological order
+- Compare screenshots across test runs to identify flaky behavior
+
+<Note>
+  For detailed workflows and examples of using these MCP commands for debugging, see the [Debugging with Screenshots](/v7/debugging-with-screenshots) guide.
+</Note>
+
+## Related
+
+- [Debugging with Screenshots](/v7/debugging-with-screenshots) - View and analyze saved screenshots using MCP
+- [assert()](/v7/assert) - Make AI-powered assertions
+- [find()](/v7/find) - Locate elements on screen

package/ai/skills/testdriver:scroll/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: testdriver:scroll
+description: Scroll pages and elements
+---
+<!-- Generated from scroll.mdx. DO NOT EDIT. -->
+
+## Overview
+
+Scroll the page or active element in any direction using mouse wheel or keyboard.
+
+<Warning>
+  **Focus Requirements**
+  
+  Scrolling requires the page or a frame to be focused. If an input field or other interactive element has focus, scroll commands may not work as expected. Before scrolling, ensure focus is on the page by:
+  - Clicking on a non-interactive area (e.g., page background)
+  - Pressing the Escape key to unfocus interactive elements
+  - Clicking outside of input fields or text areas
+  
+  **If scroll is still not working**, try using Page Down/Page Up keys directly:
+  ```javascript
+  await testdriver.pressKeys(['pagedown']); // Scroll down
+  await testdriver.pressKeys(['pageup']);   // Scroll up
+  ```
+</Warning>
+
+## 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>
+  **Ensure page has focus before scrolling**
+  
+  ```javascript
+  // After typing in an input, unfocus it first
+  await testdriver.find('email input').click();
+  await testdriver.type('user@example.com');
+  
+  // Click elsewhere or press Escape before scrolling
+  await testdriver.pressKeys(['escape']);
+  // Or click a non-interactive area
+  // await testdriver.find('page background').click();
+  
+  // Now scroll will work properly
+  await testdriver.scroll('down', 300);
+  
+  // If scroll still doesn't work, use Page Down directly
+  // await testdriver.pressKeys(['pagedown']);
+  ```
+</Check>
+
+<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();
+  });
+
+  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/find) - Locate elements after scrolling
+- [`pressKeys()`](/v7/press-keys) - Use Page Down/Up keys
+- [`wait()`](/v7/wait) - Wait after scrolling

package/ai/skills/testdriver:secrets/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: testdriver:secrets
+description: Securely manage passwords and sensitive data in your tests
+---
+<!-- Generated from secrets.mdx. DO NOT EDIT. -->
+
+Protect sensitive information like passwords, API keys, and tokens in your TestDriver tests.
+
+## Typing Secrets Securely
+
+When typing sensitive information like passwords, use the `secret: true` option to prevent the value from being logged or stored:
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('login with secure password', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: 'https://myapp.com/login' 
+  });
+
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  await testdriver.find('password input').click();
+  // Password is masked in logs and recordings
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  await testdriver.find('login button').click();
+  await testdriver.assert('dashboard is visible');
+});
+```
+
+<Note>
+When `secret: true` is set, the typed text appears as `****` in all logs, recordings, and dashcam output.
+</Note>
+
+## Storing Secrets in GitHub
+
+Store sensitive credentials as GitHub repository secrets so they're never exposed in your code:
+
+<Steps>
+  <Step title="Navigate to Repository Settings">
+    Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions**
+  </Step>
+  <Step title="Add Repository Secrets">
+    Click **New repository secret** and add your secrets:
+    - `TD_API_KEY` - Your TestDriver API key
+    - `TD_USERNAME` - Test account username
+    - `TD_PASSWORD` - Test account password
+  </Step>
+  <Step title="Use in GitHub Actions">
+    Reference secrets in your workflow file:
+    ```yaml .github/workflows/test.yml
+    - name: Run TestDriver tests
+      env:
+        TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        TD_USERNAME: ${{ secrets.TD_USERNAME }}
+        TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
+      run: vitest run
+    ```
+  </Step>
+</Steps>
+
+## Local Development
+
+For local development, store secrets in a `.env` file:
+
+```bash .env
+TD_API_KEY=your_api_key_here
+TD_USERNAME=testuser@example.com
+TD_PASSWORD=your_secure_password
+```
+
+<Warning>
+Never commit `.env` files to version control. Add `.env` to your `.gitignore` file.
+</Warning>
+
+## Complete Example
+
+Here's a full login test with proper secrets handling:
+
+```javascript tests/login.test.js
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('secure login flow', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: process.env.TD_WEBSITE || 'https://staging.myapp.com'
+  });
+
+  // Enter username (not sensitive)
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  // Enter password securely
+  await testdriver.find('password input').click();
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  // Submit login
+  await testdriver.find('login button').click();
+  
+  // Verify successful login
+  const loggedIn = await testdriver.assert('user is logged in');
+  expect(loggedIn).toBeTruthy();
+});
+```
+
+<Card title="Secrets Best Practices" icon="shield-check">
+  - **Always use `secret: true`** when typing passwords, tokens, or sensitive data
+  - **Use environment variables** to keep secrets out of code
+  - **Store secrets in your CI provider** (GitHub Actions, GitLab CI, etc.)
+  - **Never commit secrets** to version control
+  - **Rotate secrets regularly** to maintain security
+</Card>