@testdriverai/agent 7.8.0-canary.10

package/ai/skills/testdriver-screenshots/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: testdriver:screenshots
+description: Capture and manage screenshots during test execution
+---
+<!-- Generated from screenshots.mdx. DO NOT EDIT. -->
+
+## Overview
+
+TestDriver can capture screenshots manually at any point during a test, or automatically before and after every command. Screenshots are saved to a structured directory for easy debugging.
+
+## Manual Screenshots
+
+Use `testdriver.screenshot()` to capture the current screen:
+
+```javascript
+const path = await testdriver.screenshot();
+console.log('Saved to:', path);
+// .testdriver/screenshots/my-test/screenshot-1719849312345.png
+```
+
+### Options
+
+```javascript
+await testdriver.screenshot(filename?)
+```
+
+<ParamField path="filename" type="string">
+  Custom filename for the screenshot. `.png` is appended automatically if missing. If omitted, defaults to `screenshot-<timestamp>.png`.
+</ParamField>
+
+**Returns:** `Promise<string>` — the absolute file path of the saved screenshot.
+
+```javascript
+// Default filename
+await testdriver.screenshot();
+// → .testdriver/screenshots/my-test/screenshot-1719849312345.png
+
+// Custom filename
+await testdriver.screenshot('login-page');
+// → .testdriver/screenshots/my-test/login-page.png
+
+// With .png extension
+await testdriver.screenshot('dashboard-loaded.png');
+// → .testdriver/screenshots/my-test/dashboard-loaded.png
+```
+
+## Auto Screenshots
+
+Enable automatic screenshots before and after every command:
+
+```javascript
+const testdriver = new TestDriver({
+  autoScreenshots: true,
+});
+```
+
+<ParamField path="autoScreenshots" type="boolean" default={false}>
+  When `true`, captures a screenshot before and after every SDK command (`click`, `type`, `find`, `scroll`, `hover`, `pressKeys`, `assert`, `exec`, etc.). On error, an error-phase screenshot replaces the after-phase screenshot.
+</ParamField>
+
+### Filename Format
+
+Auto-screenshots follow this naming convention:
+
+```
+<seq>-<action>-<phase>-L<line>-<description>.png
+```
+
+| Part | Description | Example |
+|---|---|---|
+| `seq` | 3-digit zero-padded sequence number | `001` |
+| `action` | Command name | `click`, `type`, `find` |
+| `phase` | `before`, `after`, or `error` | `before` |
+| `L<line>` | Source line number from your test file | `L42` |
+| `description` | Sanitized from command arguments (max 30 chars) | `submit-button` |
+
+**Examples:**
+```
+001-find-before-L15-login-button.png
+002-find-after-L15-login-button.png
+003-click-before-L16-login-button.png
+004-click-after-L16-login-button.png
+005-type-before-L18-username-field.png
+006-type-error-L18-username-field.png
+```
+
+### Phases
+
+| Phase | When | Description |
+|---|---|---|
+| `before` | Before command executes | Captures the screen state before the action |
+| `after` | After successful command | Captures the result of the action |
+| `error` | After failed command | Captures the screen at the point of failure (replaces `after`) |
+
+## Screenshot Directory
+
+Screenshots are saved to:
+
+```
+<cwd>/.testdriver/screenshots/<testFileName>/
+```
+
+Where `<testFileName>` is the test file name without its extension. For example, a test at `tests/login.test.mjs` saves screenshots to `.testdriver/screenshots/login.test/`.
+
+### Directory Cleanup
+
+The screenshot directory for each test file is **automatically cleaned** at the start of a test run. This happens once per process per test file to prevent concurrent tests from the same file from interfering with each other.
+
+## Debug Screenshots
+
+Elements have a `saveDebugScreenshot()` method for debugging element detection:
+
+```javascript
+const el = await testdriver.find('submit button');
+
+// Save the screenshot that was used to detect this element
+const debugPath = await el.saveDebugScreenshot();
+console.log('Debug screenshot:', debugPath);
+// → ./debug-screenshot-1719849312345.png
+
+// Custom path
+await el.saveDebugScreenshot('./my-debug.png');
+```
+
+This saves the screenshot that was captured during the `find()` call, which can be useful for understanding what the AI "saw" when locating the element.
+
+## Complete Example
+
+```javascript
+import { describe, it, beforeAll, afterAll } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Screenshot Example', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    testdriver = new TestDriver({
+      autoScreenshots: true,   // capture every step
+    });
+    await testdriver.ready();
+    await testdriver.provision.chrome({ url: 'https://example.com' });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('captures the login flow', async () => {
+    // Auto-screenshots capture before/after each command
+
+    // Manual screenshot for a specific moment
+    await testdriver.screenshot('initial-page-load');
+
+    const username = await testdriver.find('username input');
+    await username.click();
+    await testdriver.type('testuser@example.com');
+
+    await testdriver.screenshot('after-username-entry');
+
+    const password = await testdriver.find('password input');
+    await password.click();
+    await testdriver.type('password123');
+
+    await testdriver.find('login button').click();
+
+    await testdriver.screenshot('after-login-click');
+  });
+});
+```
+
+After running, your screenshot directory will contain:
+```
+.testdriver/screenshots/login-flow.test/
+├── initial-page-load.png
+├── 001-find-before-L18-username-input.png
+├── 002-find-after-L18-username-input.png
+├── 003-click-before-L19-username-input.png
+├── 004-click-after-L19-username-input.png
+├── 005-type-before-L20-testuser-example-com.png
+├── 006-type-after-L20-testuser-example-com.png
+├── after-username-entry.png
+├── 007-find-before-L24-password-input.png
+├── ...
+```

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>

package/ai/skills/testdriver-self-hosted/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: testdriver:self-hosted
+description: Unlimited test execution, complete privacy, and the ability to customize everything — all for a predictable flat license fee.
+---
+<!-- Generated from self-hosted.mdx. DO NOT EDIT. -->
+
+Self-hosted pricing is based on **parallel test capacity**: the number of tests you can run simultaneously on **your infrastructure**. 
+
+With self-hosting, you get:.
+
+- **Flat license fee** per parallel test slot
+- **Unlimited test execution** — run as many tests as you want
+- **No device-second metering** — predictable monthly costs
+- **Use your own AI keys** — control data usage with your own OpenAI, Anthropic, or other AI provider keys
+- **Custom hardware & software** — choose instance types, resolution, install specific software, and configure networking as needed
+- **Debug & Customize** — RDP into test machines, install custom software, modify the AMI, and debug issues directly. No black boxes.
+
+## Get Started
+
+Ready to self-host? Follow our comprehensive AWS setup guide:
+
+<Card
+  title="AWS Setup Guide"
+  icon="aws"
+  href="/v7/aws-setup"
+>
+  Step-by-step instructions for deploying TestDriver on your AWS infrastructure using CloudFormation.
+</Card>
+
+
+## Who Should Self-Host?
+
+Self-hosting is ideal for teams that:
+
+- **Run high test volumes** — Flat pricing becomes more economical at scale
+- **Want infrastructure control** — Custom hardware, specific software dependencies, or network configurations
+- **Prefer predictable costs** — Budget with confidence using flat monthly fees
+
+
+## How It Works
+
+With self-hosting, you run test sandboxes on your own AWS infrastructure. TestDriver still provides:
+
+- **Dashboard** — View test results, analytics, and reports at [console.testdriver.ai](https://console.testdriver.ai)
+- **API** — Orchestration and AI-powered test execution
+- **License Management** — Your parallel test capacity
+
+You provide:
+
+- **AWS Infrastructure** — EC2 instances running in your account
+- **AI API Keys** — Use your own OpenAI, Anthropic, or other AI provider keys
+- **Custom Configuration** — Hardware specs, networking, installed software
+
+## Comparison vs Cloud
+
+| Feature | Cloud | Self-Hosted |
+|---------|-------|-------------|
+| **Setup Time** | Minutes | Hours |
+| **Pricing Model** | Device-seconds | Flat license fee |
+| **Infrastructure Management** | TestDriver | You |
+| **Device Location** | TestDriver cloud | Your AWS account |
+| **AI API Keys** | TestDriver's | Your own |
+| **Custom Software** | Limited | Full control |
+| **Hardware Selection** | Standard | Your choice |
+| **Debugging Access** | Replays only | Full RDP access |