testdriverai 7.3.12 → 7.3.13

package/.github/skills/testdriver:debugging-with-screenshots/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: testdriver:debugging-with-screenshots
+description: View and analyze saved screenshots using MCP commands for test debugging and development
+---
+<!-- Generated from debugging-with-screenshots.mdx. DO NOT EDIT. -->
+
+## Overview
+
+TestDriver MCP provides powerful commands to view and analyze screenshots saved during test execution. This enables rapid debugging, test development, and comparison workflows without manually opening image files.
+
+## MCP Commands
+
+### list_local_screenshots
+
+List all screenshots saved in the `.testdriver/screenshots/` directory:
+
+```
+list_local_screenshots()
+```
+
+**Optional Parameters:**
+
+<ParamField path="directory" type="string" optional>
+  Filter screenshots by subdirectory (e.g., specific test file). If omitted, lists all screenshots.
+</ParamField>
+
+**Returns:**
+
+Array of screenshot metadata including:
+- `path` - Full absolute path to the screenshot file
+- `relativePath` - Path relative to `.testdriver/screenshots/`
+- `testFile` - The test file that created this screenshot
+- `filename` - Screenshot filename
+- `size` - File size in bytes
+- `modified` - Last modification timestamp
+- `created` - Creation timestamp
+
+**Example Response:**
+
+```json
+[
+  {
+    "path": "/Users/user/project/.testdriver/screenshots/login.test/screenshot-1737633600000.png",
+    "relativePath": "login.test/screenshot-1737633600000.png",
+    "testFile": "login.test",
+    "filename": "screenshot-1737633600000.png",
+    "size": 145632,
+    "modified": "2026-01-23T10:00:00.000Z",
+    "created": "2026-01-23T10:00:00.000Z"
+  }
+]
+```
+
+### view_local_screenshot
+
+View a specific screenshot from the list:
+
+```
+view_local_screenshot({ path: "/full/path/to/screenshot.png" })
+```
+
+**Parameters:**
+
+<ParamField path="path" type="string" required>
+  Full absolute path to the screenshot file (as returned by `list_local_screenshots`)
+</ParamField>
+
+**Returns:**
+
+- Image content (displayed to both AI and user via MCP App)
+- Screenshot metadata
+- Success/error status
+
+## Common Workflows
+
+### Test Debugging After Failures
+
+When a test fails, view the saved screenshots to understand what went wrong:
+
+1. **List screenshots from the failed test:**
+
+```
+list_local_screenshots({ directory: "login.test" })
+```
+
+2. **View screenshots in chronological order** (sorted by creation time) to trace the test execution:
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/screenshot-1737633600000.png" })
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/screenshot-1737633610000.png" })
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/screenshot-1737633620000.png" })
+```
+
+3. **Analyze the UI state** at each step to identify where things went wrong
+
+4. **Compare expected vs actual** - if you added descriptive filenames with `screenshot("step-name")`, you can easily identify key moments
+
+### Interactive Test Development
+
+While building tests using MCP tools, view screenshots to verify your test logic:
+
+1. **After a test run**, list screenshots to see what was captured:
+
+```
+list_local_screenshots()
+```
+
+2. **Review key points** in the test execution:
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/my-test.test/after-login.png" })
+```
+
+3. **Verify element locations and states** before adding assertions
+
+4. **Iterate** - adjust your test code based on what you see in the screenshots
+
+### Comparison and Analysis
+
+Compare screenshots across multiple test runs to identify flaky behavior or UI changes:
+
+1. **List screenshots from multiple test runs** (note: each test run clears the folder, so copy screenshots elsewhere for comparison if needed)
+
+2. **View screenshots side-by-side** to spot differences:
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/test.test/before-click.png" })
+// Analyze first run
+
+view_local_screenshot({ path: ".testdriver/screenshots-backup/test.test/before-click.png" })
+// Compare with previous run
+```
+
+3. **Identify timing issues** - if element positions or states vary between runs, you may have timing/race condition issues
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Use descriptive filenames">
+    When saving screenshots in tests, use descriptive names to make them easier to identify:
+    
+    ```javascript
+    await testdriver.screenshot("initial-page-load");
+    await testdriver.screenshot("after-login-click");
+    await testdriver.screenshot("dashboard-loaded");
+    ```
+    
+    Then when listing screenshots, you can quickly identify key moments without viewing every image.
+  </Accordion>
+
+  <Accordion title="List before viewing">
+    Always call `list_local_screenshots` first to see what's available. The list is sorted by modification time (newest first), making it easy to find recent test runs.
+  </Accordion>
+
+  <Accordion title="Filter by test file">
+    When debugging a specific test, use the `directory` parameter to filter screenshots:
+    
+    ```
+    list_local_screenshots({ directory: "problematic-test.test" })
+    ```
+    
+    This avoids clutter from other tests.
+  </Accordion>
+
+  <Accordion title="View screenshots before and after failures">
+    When a test fails (especially with assertions), look at screenshots immediately before the failure. They show exactly what the AI or test "saw" at that moment, helping you understand why an assertion failed or why an element wasn't found.
+  </Accordion>
+
+  <Accordion title="Combine with test reports">
+    TestDriver test reports include screenshots in the timeline. Use MCP screenshot viewing for interactive debugging during development, and test reports for post-run analysis and team sharing.
+  </Accordion>
+
+  <Accordion title="Archive important screenshots">
+    Remember that each test run clears its screenshot folder. If you need to preserve screenshots for comparison:
+    
+    ```bash
+    # Copy screenshots before next run
+    cp -r .testdriver/screenshots/my-test.test .testdriver/screenshots-backup/
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Screenshot File Organization
+
+Understanding the directory structure helps with efficient screenshot viewing:
+
+```
+.testdriver/
+  screenshots/
+    login.test/              # Test file name (without .mjs extension)
+      screenshot-1737633600000.png   # Auto-generated timestamp filename
+      initial-state.png              # Custom descriptive filename
+      after-click.png
+    checkout.test/
+      screenshot-1737633700000.png
+      product-page.png
+    profile.test/
+      screenshot-1737633800000.png
+```
+
+- Each test file gets its own subdirectory
+- Filenames are either timestamps (default) or custom names you provide
+- Folders are cleared at the start of each test run
+- All screenshots are PNG format
+
+## Integration with Test Development
+
+### During MCP Interactive Development
+
+When using TestDriver MCP tools (`session_start`, `find_and_click`, etc.), screenshots are automatically captured and displayed. Additionally, you can view previously saved screenshots:
+
+```
+# After test development session
+list_local_screenshots({ directory: "my-new-test.test" })
+view_local_screenshot({ path: ".testdriver/screenshots/my-new-test.test/login-page.png" })
+```
+
+This helps verify your test logic before running the full test file.
+
+### After Test Runs
+
+When tests fail or behave unexpectedly:
+
+1. **Run the test** with `vitest run tests/my-test.test.mjs`
+2. **List screenshots** using `list_local_screenshots`
+3. **View relevant screenshots** to diagnose the issue
+4. **Update test code** based on what you see
+5. **Re-run and verify** the fix
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="No screenshots found">
+    If `list_local_screenshots` returns an empty array:
+    
+    - Ensure your test includes `await testdriver.screenshot()` calls
+    - Verify the test actually ran (check test output)
+    - Check that `.testdriver/screenshots/` directory exists
+    - Confirm you're in the correct project directory
+  </Accordion>
+
+  <Accordion title="Screenshot not displaying">
+    If `view_local_screenshot` returns an error:
+    
+    - Verify the path is exactly as returned by `list_local_screenshots`
+    - Check file permissions - ensure the screenshot file is readable
+    - Confirm the file hasn't been deleted or moved
+  </Accordion>
+
+  <Accordion title="Too many screenshots">
+    If you have hundreds of screenshots making it hard to find what you need:
+    
+    - Use the `directory` parameter to filter by test file
+    - Consider adding more descriptive filenames in your tests
+    - Clean up old screenshot folders: `rm -rf .testdriver/screenshots/*`
+  </Accordion>
+
+  <Accordion title="Screenshots from old test runs">
+    Remember that screenshot folders are cleared at the start of each test run. If you see old screenshots:
+    
+    - The test may not have run recently
+    - Or the test failed before reaching the clearing logic
+    - Manually clear: `rm -rf .testdriver/screenshots/<test-name>/`
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [screenshot()](/v7/screenshot) - Capture screenshots during test execution
+- [Dashcam](/v7/dashcam) - Record full test sessions with video and logs
+- [assert()](/v7/assert) - Make AI-powered assertions that benefit from screenshot context

package/.github/skills/testdriver:device-config/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: testdriver:device-config
+description: Launch browsers, desktop apps, and extensions in your TestDriver sandbox
+---
+<!-- Generated from device-config.mdx. DO NOT EDIT. -->
+
+Provision methods are the starting point for most tests. They launch applications in your sandbox and prepare the environment for testing.
+
+## Chrome Browser
+
+The most common starting point for web testing. Launches Chrome browser and navigates to a URL.
+
+```javascript
+await testdriver.provision.chrome({
+  url: 'https://example.com',
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | `'http://testdriver-sandbox.vercel.app/'` | URL to navigate to |
+| `maximized` | boolean | `true` | Start browser maximized |
+| `guest` | boolean | `false` | Use guest mode (no profile) |
+
+### Example: Basic Web Test
+
+```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',
+    });
+
+    await testdriver.find("Email input").click();
+    await testdriver.type("user@example.com");
+    
+    await testdriver.find("Password input").click();
+    await testdriver.type("password123");
+    
+    await testdriver.find("Sign In button").click();
+    
+    const result = await testdriver.assert("the dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+<Info>
+  `provision.chrome()` automatically starts Dashcam recording and waits for Chrome to be ready before returning.
+</Info>
+
+---
+
+## Chrome Extensions
+
+Launch Chrome with a custom extension loaded. Supports both local extensions and Chrome Web Store extensions.
+
+### Load from Local Path
+
+Clone or create an extension locally, then load it:
+
+```javascript
+// First, get the extension onto the sandbox
+await testdriver.exec(
+  'sh',
+  'git clone https://github.com/user/my-extension.git /tmp/my-extension',
+  60000
+);
+
+// Launch Chrome with the extension
+await testdriver.provision.chromeExtension({
+  extensionPath: '/tmp/my-extension',
+  url: 'https://example.com'
+});
+```
+
+### Load from Chrome Web Store
+
+Load any published extension by its Chrome Web Store ID:
+
+```javascript
+await testdriver.provision.chromeExtension({
+  extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
+  url: 'https://example.com'
+});
+```
+
+<Tip>
+  Find the extension ID in the Chrome Web Store URL. For example, `https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm` → ID is `cjpalhdlnbpafiamejdnhcphjbkeiagm`
+</Tip>
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `extensionPath` | string | - | Local path to unpacked extension directory |
+| `extensionId` | string | - | Chrome Web Store extension ID |
+| `url` | string | - | URL to navigate to after launch |
+| `maximized` | boolean | `true` | Start browser maximized |
+
+<Warning>
+  You must provide either `extensionPath` or `extensionId`, but not both.
+</Warning>
+
+### Example: Testing a Chrome Extension
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Chrome Extension Test", () => {
+  it("should load and interact with extension", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Clone extension from GitHub
+    await testdriver.exec(
+      'sh',
+      'git clone https://github.com/user/my-extension.git /tmp/my-extension',
+      60000,
+      true
+    );
+
+    // Launch Chrome with extension loaded
+    await testdriver.provision.chromeExtension({
+      extensionPath: '/tmp/my-extension',
+      url: 'https://testdriver.ai'
+    });
+
+    // Click extensions puzzle icon
+    const extensionsButton = await testdriver.find("puzzle-shaped icon in Chrome toolbar");
+    await extensionsButton.click();
+
+    // Interact with your extension
+    const myExtension = await testdriver.find("My Extension in the dropdown");
+    await myExtension.click();
+
+    const result = await testdriver.assert("extension popup is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+---
+
+## Desktop Apps
+
+Download and install desktop applications. Supports `.deb`, `.rpm`, `.msi`, `.exe`, `.AppImage`, `.dmg`, `.pkg`, and shell scripts.
+
+```javascript
+const filePath = await testdriver.provision.installer({
+  url: 'https://example.com/app.deb',
+  appName: 'MyApp',  // Focus this app after install
+  launch: true,      // Auto-launch after install
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | **required** | URL to download the installer from |
+| `filename` | string | auto-detected | Filename to save as |
+| `appName` | string | - | Application name to focus after install |
+| `launch` | boolean | `true` | Launch the app after installation |
+
+### Supported File Types
+
+| Extension | OS | Install Method |
+|-----------|-----|----------------|
+| `.deb` | Linux | `dpkg -i` + `apt-get install -f` |
+| `.rpm` | Linux | `rpm -i` |
+| `.AppImage` | Linux | `chmod +x` |
+| `.sh` | Linux | `chmod +x` + execute |
+| `.msi` | Windows | `msiexec /i /quiet` |
+| `.exe` | Windows | Silent install (`/S`) |
+| `.dmg` | macOS | Mount + copy to Applications |
+| `.pkg` | macOS | `installer -pkg` |
+
+### Example: Install and Test a Desktop App
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Desktop App Test", () => {
+  it("should install and launch app", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Download and install
+    const installerPath = await testdriver.provision.installer({
+      url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
+    });
+
+    // Verify installation
+    const output = await testdriver.exec('sh', 'bat --version', 5000);
+    expect(output).toContain('bat');
+  });
+});
+```
+
+### Example: Windows Installer
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Windows App Test", () => {
+  it("should install on Windows", async (context) => {
+    const testdriver = TestDriver(context, { 
+      os: 'windows'
+    });
+
+    // Download MSI installer
+    const installerPath = await testdriver.provision.installer({
+      url: 'https://example.com/app.msi',
+      launch: false,  // Don't auto-launch
+    });
+
+    // Custom installation if needed
+    await testdriver.exec(
+      'pwsh',
+      `Start-Process msiexec.exe -ArgumentList "/i", "${installerPath}", "/qn" -Wait`,
+      120000
+    );
+
+    // Verify installation
+    const result = await testdriver.assert("application is installed");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+### Manual Installation
+
+Set `launch: false` to download without auto-installing:
+
+```javascript
+const filePath = await testdriver.provision.installer({
+  url: 'https://example.com/custom-script.sh',
+  launch: false,
+});
+
+// Run custom install commands
+await testdriver.exec('sh', `chmod +x "${filePath}"`, 5000);
+await testdriver.exec('sh', `"${filePath}" --custom-flag`, 60000);
+```
+
+---
+
+## VS Code
+
+Launch Visual Studio Code with optional workspace and extensions.
+
+```javascript
+await testdriver.provision.vscode({
+  workspace: '/home/testdriver/my-project',
+  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `workspace` | string | - | Workspace folder to open |
+| `extensions` | string[] | `[]` | Extensions to install (by ID) |
+
+### Example: VS Code Extension Test
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("VS Code Test", () => {
+  it("should open workspace with extensions", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Create a test project
+    await testdriver.exec('sh', 'mkdir -p /tmp/test-project && echo "print(1)" > /tmp/test-project/test.py', 10000);
+
+    // Launch VS Code
+    await testdriver.provision.vscode({
+      workspace: '/tmp/test-project',
+      extensions: ['ms-python.python'],
+    });
+
+    // Verify VS Code is ready
+    const result = await testdriver.assert("VS Code is open with the project");
+    expect(result).toBeTruthy();
+
+    // Open the Python file
+    await testdriver.find("test.py in the explorer").click();
+  });
+});
+```
+
+---
+
+## Choosing the Right Provision Method
+
+| Use Case | Method |
+|----------|--------|
+| Testing a website | `provision.chrome` |
+| Testing a Chrome extension | `provision.chromeExtension` |
+| Testing a desktop app (needs installation) | `provision.installer` |
+| Testing VS Code or VS Code extensions | `provision.vscode` |
+
+<Tip>
+  All provision methods automatically start Dashcam recording and wait for the application to be ready before returning. You don't need to call `dashcam.start()` manually.
+</Tip>

package/.github/skills/testdriver:double-click/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: testdriver:double-click
+description: Perform a double-click action on an element or at specific coordinates
+---
+<!-- Generated from double-click.mdx. DO NOT EDIT. -->
+
+## Overview
+
+The `doubleClick()` method performs a double-click action on an element. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Double-click on an element
+await element.doubleClick();
+
+// Double-click using a selector
+await ai.doubleClick('selector');
+```
+
+## Parameters
+
+When called on an `Element`, no parameters are required.
+
+When called directly on the AI client:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | The selector describing the element to double-click |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the double-click action completes.
+
+## Examples
+
+### Double-Click on Found Element
+
+```javascript
+const fileItem = await ai.find('README.md file');
+await fileItem.doubleClick();
+```
+
+### Direct Double-Click with Selector
+
+```javascript
+await ai.doubleClick('README.md in the file list');
+```
+
+### Opening Files in VS Code
+
+```javascript
+import { test } from 'vitest';
+import { vscode } from '@testdriver/sdk';
+
+test('opens a file by double-clicking', async () => {
+  const { ai } = await vscode();
+  
+  // Double-click to open a file in the explorer
+  await ai.doubleClick('package.json in the file explorer');
+  
+  // Verify the file opened
+  const editor = await ai.find('text editor showing package.json');
+  expect(editor).toBeTruthy();
+});
+```
+
+### Opening Folders in File Manager
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('navigates folders in Google Drive', async () => {
+  const { ai } = await chrome('https://drive.google.com');
+  
+  // Double-click to open a folder
+  await ai.doubleClick('Documents folder');
+  
+  // Wait for folder to open
+  await ai.find('breadcrumb showing Documents');
+});
+```
+
+### Selecting Text with Double-Click
+
+```javascript
+// Double-click to select a word
+await ai.doubleClick('word "TestDriver" in the paragraph');
+
+// Verify selection
+const selectedText = await ai.exec('window.getSelection().toString()');
+expect(selectedText).toBe('TestDriver');
+```
+
+## Related Methods
+
+- [`click()`](/v7/click) - Single click on an element
+- [`rightClick()`](/v7/right-click) - Right-click to open context menu
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`mouseUp()`](/v7/mouse-up) - Release mouse button
+- [`hover()`](/v7/hover) - Move mouse over element without clicking