testdriverai 7.2.47 → 7.2.48

package/.github/workflows/acceptance-linux-scheduled.yaml

@@ -31,7 +31,7 @@ jobs:
 
     - name: Run Linux tests with Sentry Cron monitoring
       run: |
-        sentry-cli monitors run testdriver-linux-acceptance -- npx vitest run test/testdriver/*.test.mjs
+        sentry-cli monitors run testdriver-linux-acceptance -- npx vitest run examples/*.test.mjs
       env:
         SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
         TD_API_KEY: ${{ secrets.TD_API_KEY }}

package/.github/workflows/acceptance.yaml

@@ -29,7 +29,7 @@ jobs:
       run: npm ci
     
     - name: Run Linux tests
-      run: npx vitest run test/testdriver/*.test.mjs
+      run: npx vitest run examples/*.test.mjs
       env:
         TD_API_KEY: ${{ secrets.TD_API_KEY }}
         TD_OS: linux
@@ -52,7 +52,7 @@ jobs:
     if: contains(github.event.pull_request.labels.*.name, 'test-windows')
     uses: ./.github/workflows/windows-self-hosted.yaml
     with:
-      test_pattern: 'test/testdriver/assert.test.mjs'
+      test_pattern: 'examples/assert.test.mjs'
     secrets:
       TD_API_KEY: ${{ secrets.TD_API_KEY }}
       TD_WEBSITE: ${{ secrets.TD_WEBSITE }}

package/.github/workflows/windows-self-hosted.yaml

@@ -7,7 +7,7 @@ on:
         description: 'Test file pattern to run'
         required: false
         type: string
-        default: 'test/testdriver/*.test.mjs'
+        default: 'examples/*.test.mjs'
     secrets:
       TD_API_KEY:
         required: true

package/README.md

@@ -11,7 +11,7 @@
 <br />
 <br />
   
-[🚀 **Quick Start**](#-quick-start) • [📖 **Documentation**](https://docs.testdriver.ai) • [💻 **Examples**](https://github.com/testdriverai/testdriverai/tree/main/test/testdriver) • [📖 **Pricing**](https://docs.testdriver.ai) • [💬 **Discord**](https://discord.com/invite/cWDFW8DzPm) • [🌐 **Website**](https://testdriver.ai)
+[🚀 **Quick Start**](#-quick-start) • [📖 **Documentation**](https://docs.testdriver.ai) • [💻 **Examples**](https://github.com/testdriverai/testdriverai/tree/main/examples) • [📖 **Pricing**](https://docs.testdriver.ai) • [💬 **Discord**](https://discord.com/invite/cWDFW8DzPm) • [🌐 **Website**](https://testdriver.ai)
 
 </div>
 
@@ -41,7 +41,7 @@ const result = await testdriver.assert(
 expect(result).toBeTruthy();
 ```
 
-[See Full Example](https://github.com/testdriverai/testdriverai/blob/main/test/testdriver/drag-and-drop.test.mjs) • [Browse All Examples](https://github.com/testdriverai/testdriverai/tree/main/test/testdriver)
+[See Full Example](https://github.com/testdriverai/testdriverai/blob/main/examples/drag-and-drop.test.mjs) • [Browse All Examples](https://github.com/testdriverai/testdriverai/tree/main/examples)
 
 ---
 

package/docs/TEST-GITHUB-COMMENTS.md

@@ -38,7 +38,7 @@
 
 ## What the Test Does
 
-The workflow runs `test/testdriver/assert.test.mjs` which:
+The workflow runs `examples/assert.test.mjs` which:
 - Provisions a Chrome browser
 - Navigates to https://saucedemo.com
 - Performs login actions
@@ -72,7 +72,7 @@ Skipped: 0 ⏭️
 
 | Status | Test | File | Duration | Replay |
 |--------|------|------|----------|--------|
-| ✅ | Assert Test | `test/testdriver/assert.test.mjs` | 25.3s | [🎥 View](https://console.testdriver.ai/replay/...) |
+| ✅ | Assert Test | `examples/assert.test.mjs` | 25.3s | [🎥 View](https://console.testdriver.ai/replay/...) |
 
 ## 🎥 Dashcam Replays
 

package/docs/v7/_drafts/plugin-migration.mdx

@@ -142,7 +142,7 @@ export default defineConfig({
 
 ### Test Helpers
 
-- ✅ **Removed**: `test/testdriver/setup/` folder (legacy helpers)
+- ✅ **Removed**: `examples/setup/` folder (legacy helpers)
   - Code moved to `lib/vitest/hooks.mjs` framework
   - Tests now use `TestDriver(context, options)` pattern directly
 

package/docs/v7/aws-setup.mdx

@@ -257,7 +257,7 @@ jobs:
         run: npm ci
 
       - name: Run Windows tests with self-hosted instances
-        run: npx vitest run test/testdriver/*.test.mjs
+        run: npx vitest run examples/*.test.mjs
         env:
           TD_API_KEY: ${{ secrets.TD_API_KEY }}
           TD_OS: windows

package/docs/v7/examples.mdx

@@ -1,5 +1,5 @@
 ---
 title: "Examples"
-url: "https://github.com/testdriverai/testdriverai/tree/main/test/testdriver"
+url: "https://github.com/testdriverai/testdriverai/tree/main/examples"
 icon: 'code'
 ---

package/{test/testdriver → examples}/chrome-extension.test.mjs

@@ -55,7 +55,7 @@ describe("Chrome Extension Test", () => {
     // When clicked, it shows a popup with "Hello Extensions"
 
     // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar");
+    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar", {zoom: true});
     await extensionsButton.click();
 
     // Look for the hello world extension in the extensions menu

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.47",
+  "version": "7.2.48",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",

package/test/manual/reconnect-provision.test.mjs

@@ -8,8 +8,8 @@
  * Run reconnect-signin.test.mjs within 2 minutes of this test completing.
  * 
  * Usage:
- *   1. npm test -- test/testdriver/reconnect-provision.test.mjs
- *   2. (within 2 minutes) npm test -- test/testdriver/reconnect-signin.test.mjs
+ *   1. npm test -- examples/reconnect-provision.test.mjs
+ *   2. (within 2 minutes) examples/reconnect-signin.test.mjs
  */
 
 import { afterAll, describe, expect, it } from "vitest";

package/testdriver-plugin/skills/actions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: actions
+description: Perform actions in TestDriver tests. Use when clicking, typing, pressing keys, scrolling, hovering, dragging, or interacting with UI elements.
+---
+
+# Performing Actions
+
+Read these docs:
+- `node_modules/testdriverai/docs/v7/click.mdx`
+- `node_modules/testdriverai/docs/v7/type.mdx`
+- `node_modules/testdriverai/docs/v7/press-keys.mdx`
+- `node_modules/testdriverai/docs/v7/scroll.mdx`
+- `node_modules/testdriverai/docs/v7/hover.mdx`
+- `node_modules/testdriverai/docs/v7/double-click.mdx`
+- `node_modules/testdriverai/docs/v7/right-click.mdx`
+- `node_modules/testdriverai/docs/v7/mouse-down.mdx`
+- `node_modules/testdriverai/docs/v7/mouse-up.mdx`
+
+## Click Actions
+
+```javascript
+const element = await testdriver.find("button");
+await element.click();
+await element.doubleClick();
+await element.rightClick();
+await element.hover();
+```
+
+## Typing
+
+```javascript
+await testdriver.find("Email input").click();
+await testdriver.type("user@example.com");
+```
+
+### Clear before typing
+```javascript
+await testdriver.find("Search input").click();
+await testdriver.pressKeys(["ctrl", "a"]);
+await testdriver.type("new search term");
+```
+
+## Keyboard Input
+
+```javascript
+await testdriver.pressKeys(["enter"]);
+await testdriver.pressKeys(["tab"]);
+await testdriver.pressKeys(["escape"]);
+await testdriver.pressKeys(["ctrl", "a"]);  // Select all
+await testdriver.pressKeys(["ctrl", "c"]);  // Copy
+await testdriver.pressKeys(["ctrl", "v"]);  // Paste
+await testdriver.pressKeys(["alt", "f4"]);  // Close (Windows)
+await testdriver.pressKeys(["cmd", "q"]);   // Quit (macOS)
+```
+
+## Scrolling
+
+```javascript
+await testdriver.scroll("down");
+await testdriver.scroll("up");
+await testdriver.scrollUntilText("Footer content");
+await testdriver.scrollUntilImage("Product image at bottom");
+```
+
+## Drag and Drop
+
+```javascript
+const source = await testdriver.find("Draggable item");
+const target = await testdriver.find("Drop zone");
+await source.mouseDown();
+await target.hover();
+await target.mouseUp();
+```
+
+## Execute Code in Sandbox
+
+```javascript
+// JavaScript (browser)
+const title = await testdriver.exec("js", "return document.title", 5000);
+
+// Shell (Linux)
+await testdriver.exec("sh", "ls -la", 5000);
+
+// PowerShell (Windows)
+await testdriver.exec("pwsh", "Get-Date", 5000);
+```
+
+## Examples
+
+- `node_modules/testdriverai/examples/type.test.mjs`
+- `node_modules/testdriverai/examples/press-keys.test.mjs`
+- `node_modules/testdriverai/examples/scroll.test.mjs`
+- `node_modules/testdriverai/examples/drag-and-drop.test.mjs`

package/testdriver-plugin/skills/assertions/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: assertions
+description: Make assertions in TestDriver tests. Use when verifying UI state, checking visual conditions, or validating test outcomes with natural language.
+---
+
+# Making Assertions
+
+Read: `node_modules/testdriverai/docs/v7/assert.mdx`
+Read: `node_modules/testdriverai/docs/v7/making-assertions.mdx`
+
+## Basic Usage
+
+```javascript
+const result = await testdriver.assert("the dashboard is visible");
+expect(result).toBeTruthy();
+```
+
+## Writing Good Assertions
+
+**Be specific:**
+```javascript
+// ✅ Good
+await testdriver.assert("the login button is visible in the header");
+await testdriver.assert("user's name 'John' appears in the profile section");
+await testdriver.assert("error message 'Invalid email' is displayed");
+
+// ❌ Vague
+await testdriver.assert("button visible");
+await testdriver.assert("it worked");
+```
+
+**Describe what you see:**
+```javascript
+await testdriver.assert("the settings panel is open on the right side");
+await testdriver.assert("a green success checkmark appears next to the form");
+await testdriver.assert("the page shows 'Welcome back, John'");
+```
+
+**Include context:**
+```javascript
+await testdriver.assert("the shopping cart shows 3 items");
+await testdriver.assert("the price total is $99.99");
+await testdriver.assert("the submit button is disabled");
+```
+
+## Common Patterns
+
+### After navigation
+```javascript
+await testdriver.find("Settings link").click();
+const result = await testdriver.assert("Settings page is displayed");
+expect(result).toBeTruthy();
+```
+
+### Form validation
+```javascript
+await testdriver.find("Submit button").click();
+const hasError = await testdriver.assert("email validation error is shown");
+expect(hasError).toBeTruthy();
+```
+
+### State changes
+```javascript
+await testdriver.find("Toggle switch").click();
+const isOn = await testdriver.assert("the toggle is now in the ON position");
+expect(isOn).toBeTruthy();
+```
+
+### Negative assertions
+```javascript
+const noError = await testdriver.assert("no error messages are visible");
+expect(noError).toBeTruthy();
+```
+
+## Examples
+
+See `node_modules/testdriverai/examples/assert.test.mjs`

package/testdriver-plugin/skills/caching/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: caching
+description: Understand TestDriver element caching. Use when optimizing test speed, managing cache keys, or troubleshooting cached element issues.
+---
+
+# Element Caching
+
+Read: `node_modules/testdriverai/docs/v7/caching.mdx`
+
+## How Caching Works
+
+TestDriver caches element locations to speed up subsequent test runs. When you `find()` an element, the result is stored and reused in future runs.
+
+## Cache Options
+
+```javascript
+const testdriver = TestDriver(context, {
+  cache: true,           // Enable caching (default: true)
+  cacheKey: 'my-test',   // Custom cache key
+});
+```
+
+## When to Use Custom Cache Keys
+
+Use different cache keys when:
+- Testing different pages/states with similar elements
+- Running tests in different environments
+- Elements have different positions in different contexts
+
+```javascript
+// Login page test
+const testdriver = TestDriver(context, { cacheKey: 'login-page' });
+
+// Dashboard test
+const testdriver = TestDriver(context, { cacheKey: 'dashboard' });
+```
+
+## Disabling Cache
+
+Disable caching when:
+- Elements frequently change position
+- Debugging element detection issues
+- Dynamic content that varies between runs
+
+```javascript
+const testdriver = TestDriver(context, { cache: false });
+```
+
+## Cache Invalidation
+
+The cache is automatically invalidated when:
+- Element is not found at cached location
+- Test fails due to element mismatch
+- Cache key changes
+
+## Troubleshooting
+
+**Element found at wrong position?**
+- Try disabling cache: `cache: false`
+- Use a different cache key
+- The UI may have changed since last run
+
+**Tests slower than expected?**
+- Ensure caching is enabled
+- Use consistent cache keys
+- Cache builds up over successful runs

package/testdriver-plugin/skills/creating-tests/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: creating-tests
+description: Create TestDriver tests. Use when writing new test files, structuring test suites, using the two-file workflow pattern, or setting up provision for browser/desktop testing.
+---
+
+# Creating Tests
+
+Read: `node_modules/testdriverai/docs/v7/quickstart.mdx`
+
+## Basic Test Structure
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("My Test Suite", () => {
+  it("should do something", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({ url: 'https://example.com' });
+
+    const button = await testdriver.find("Sign In button");
+    await button.click();
+
+    const result = await testdriver.assert("dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Provisioning
+
+### Web Testing
+```javascript
+await testdriver.provision.chrome({ url: 'https://your-app.com' });
+```
+
+### Desktop App Testing
+```javascript
+await testdriver.provision.installer({
+  url: 'https://example.com/app.deb',  // or .msi, .exe
+  launch: true,
+});
+```
+
+## Two-File Workflow (Recommended for Development)
+
+Use two files to iterate efficiently without restarting from scratch.
+
+### setup.test.mjs
+```javascript
+import { afterAll, describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Setup", () => {
+  afterAll(async () => {
+    console.log("Sandbox staying alive for reconnect");
+  });
+
+  it("should set up state", async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://your-app.com' });
+    const result = await testdriver.assert("page loaded");
+    expect(result).toBeTruthy();
+    console.log("✅ Run experiment.test.mjs now");
+  });
+});
+```
+
+### experiment.test.mjs
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Experiment", () => {
+  it("should continue", async (context) => {
+    const testdriver = TestDriver(context, { reconnect: true });
+    // NO provision - sandbox already running
+    // Add new steps here...
+  });
+});
+```
+
+Run setup first, then experiment within 2 minutes.
+
+⚠️ **NEVER remove `reconnect: true`** unless combining into a final test.
+
+## TestDriver Options
+
+```javascript
+TestDriver(context, {
+  newSandbox: true,       // Create new sandbox
+  reconnect: false,       // Reconnect to last sandbox
+  keepAlive: 30000,       // Keep alive after test (ms)
+  os: 'linux',            // 'linux' | 'windows'
+  resolution: '1366x768', // Sandbox resolution
+});
+```
+
+See `node_modules/testdriverai/docs/v7/device-config.mdx` for all options.
+
+## Examples
+
+See `node_modules/testdriverai/examples/` for working test patterns.

package/testdriver-plugin/skills/finding-elements/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: finding-elements
+description: Find elements in TestDriver tests. Use when locating UI elements by natural language description, understanding element properties, or debugging element detection.
+---
+
+# Finding Elements
+
+Read: `node_modules/testdriverai/docs/v7/find.mdx`
+Read: `node_modules/testdriverai/docs/v7/elements.mdx`
+Read: `node_modules/testdriverai/docs/v7/locating-elements.mdx`
+
+## Basic Usage
+
+```javascript
+const button = await testdriver.find("Sign In button");
+const input = await testdriver.find("Email input field");
+const link = await testdriver.find("Forgot password link");
+```
+
+## Find All Matching Elements
+
+```javascript
+const items = await testdriver.findAll("Product cards in the grid");
+console.log(`Found ${items.length} products`);
+```
+
+## Element Properties
+
+```javascript
+const element = await testdriver.find("Submit button");
+
+// Check if found
+console.log(element.found());  // boolean
+
+// Coordinates
+console.log(element.x, element.y);             // top-left
+console.log(element.centerX, element.centerY); // center
+
+// Dimensions
+console.log(element.width, element.height);
+
+// AI detection info
+console.log(element.confidence);  // 0-1
+console.log(element.text);        // detected text
+console.log(element.boundingBox); // full box
+```
+
+## Tips for Good Element Descriptions
+
+**Be specific:**
+- ✅ "Sign In button in the header"
+- ❌ "button"
+
+**Include context:**
+- ✅ "Email input field in the login form"
+- ❌ "input"
+
+**Describe visual appearance:**
+- ✅ "Blue Submit button at bottom of form"
+- ✅ "User avatar in top right corner"
+
+## Debugging
+
+Log element info to understand what AI sees:
+
+```javascript
+const element = await testdriver.find("Some element");
+console.log("Found:", element.found());
+console.log("Position:", element.x, element.y);
+console.log("Size:", element.width, element.height);
+console.log("Confidence:", element.confidence);
+console.log("Text:", element.text);
+```
+
+## Examples
+
+See `node_modules/testdriverai/examples/hover-text.test.mjs`

package/testdriver-plugin/skills/github-actions/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: github-actions
+description: Integrate TestDriver with GitHub Actions. Use when setting up CI/CD pipelines, configuring workflows, or automating test runs on pull requests.
+---
+
+# GitHub Actions Integration
+
+Read: `node_modules/testdriverai/docs/v7/ci-cd.mdx`
+
+## Basic Workflow
+
+Create `.github/workflows/testdriver.yml`:
+
+```yaml
+name: TestDriver Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Run TestDriver tests
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        run: npx vitest run
+        
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results
+          path: test-report.junit.xml
+```
+
+## Required Secrets
+
+Add to your repository secrets (Settings → Secrets → Actions):
+- `TD_API_KEY` - Your TestDriver API key
+
+## Windows Testing
+
+For Windows sandbox testing, add AWS credentials:
+
+```yaml
+- name: Run TestDriver tests (Windows)
+  env:
+    TD_API_KEY: ${{ secrets.TD_API_KEY }}
+    TD_OS: windows
+    AWS_REGION: ${{ secrets.AWS_REGION }}
+    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    AMI_ID: ${{ secrets.AMI_ID }}
+    AWS_LAUNCH_TEMPLATE_ID: ${{ secrets.AWS_LAUNCH_TEMPLATE_ID }}
+  run: npx vitest run
+```
+
+## JUnit Test Reports
+
+TestDriver outputs JUnit XML for CI integration:
+
+```yaml
+- name: Publish Test Results
+  uses: dorny/test-reporter@v1
+  if: always()
+  with:
+    name: TestDriver Results
+    path: test-report.junit.xml
+    reporter: java-junit
+```
+
+## Parallel Testing
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        test-file: [login, checkout, settings]
+    steps:
+      # ...
+      - name: Run tests
+        run: npx vitest run tests/${{ matrix.test-file }}.test.mjs
+```