testdriverai 7.2.77 → 7.2.79

package/agent/index.js

@@ -2026,6 +2026,7 @@ ${regression}
         url: url,
         token: "V3b8wG9",
         testFile: this.testFile || null,
+        os: this.sandboxOs || "linux",
       };
 
       // Base64 encode the data (the debugger expects base64, not URL encoding)
@@ -2034,7 +2035,47 @@ ${regression}
       // Use the debugger URL instead of the VNC URL
       const urlToOpen = `${this.debuggerUrl}?data=${encodedData}`;
 
-      this.emitter.emit(events.showWindow, urlToOpen);
+      // Check preview mode from config
+      const previewMode = this.config.TD_PREVIEW || "browser";
+
+      if (previewMode === "ide") {
+        // Write session file for VSCode extension to pick up
+        this.writeIdeSessionFile(urlToOpen, data);
+      } else if (previewMode !== "none") {
+        // Open in browser (default behavior)
+        this.emitter.emit(events.showWindow, urlToOpen);
+      }
+      // If preview is "none", don't open anything
+    }
+  }
+
+  // Write session file for IDE preview mode
+  writeIdeSessionFile(debuggerUrl, data) {
+    const fs = require("fs");
+    const os = require("os");
+    const path = require("path");
+
+    const sessionDir = path.join(os.homedir(), ".testdriver");
+    const sessionFile = path.join(sessionDir, "ide-session.json");
+
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(sessionDir)) {
+        fs.mkdirSync(sessionDir, { recursive: true });
+      }
+
+      const sessionData = {
+        debuggerUrl: debuggerUrl,
+        resolution: data.resolution || this.config.TD_RESOLUTION,
+        testFile: data.testFile || this.thisFile,
+        os: data.os || this.sandboxOs || "linux",
+        timestamp: Date.now(),
+      };
+
+      fs.writeFileSync(sessionFile, JSON.stringify(sessionData, null, 2));
+      logger.log(`IDE session file written: ${sessionFile}`);
+    } catch (error) {
+      logger.warn(`Failed to write IDE session file: ${error.message}`);
     }
   }
 

package/agent/lib/debugger-server.js

@@ -113,6 +113,10 @@ async function startDebugger(config = {}, emitter) {
       });
     }
 
+    // Store the debugger URL and config for later use
+    module.exports.debuggerUrl = url;
+    module.exports.config = config;
+
     return { port, url };
   } catch (error) {
     console.error("Failed to start debugger server:", error);
@@ -140,4 +144,6 @@ module.exports = {
   stopDebugger,
   broadcastEvent,
   createDebuggerServer,
+  debuggerUrl: null,
+  config: null,
 };

package/ai/agents/testdriver.md

@@ -1,7 +1,7 @@
 ---
 name: testdriver
 description: An expert at creating and refining automated tests using TestDriver.ai
-tools: ["*"]
+tools: ['vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/openSimpleBrowser', 'vscode/runCommand', 'vscode/askQuestions', 'vscode/switchAgent', 'vscode/vscodeAPI', 'vscode/extensions', 'execute/runNotebookCell', 'execute/testFailure', 'execute/getTerminalOutput', 'execute/awaitTerminal', 'execute/killTerminal', 'execute/runTask', 'execute/createAndRunTask', 'execute/runInTerminal', 'execute/runTests', 'read/getNotebookSummary', 'read/problems', 'read/readFile', 'read/readNotebookCellOutput', 'read/terminalSelection', 'read/terminalLastCommand', 'read/getTaskOutput', 'agent/runSubagent', 'edit/createDirectory', 'edit/createFile', 'edit/createJupyterNotebook', 'edit/editFiles', 'edit/editNotebook', 'search/changes', 'search/codebase', 'search/fileSearch', 'search/listDirectory', 'search/searchResults', 'search/textSearch', 'search/usages', 'search/searchSubagent', 'web/fetch', 'web/githubRepo', 'testdriver/assert', 'testdriver/check', 'testdriver/click', 'testdriver/exec', 'testdriver/find', 'testdriver/find_and_click', 'testdriver/findall', 'testdriver/focus_application', 'testdriver/hover', 'testdriver/list_local_screenshots', 'testdriver/press_keys', 'testdriver/screenshot', 'testdriver/scroll', 'testdriver/session_extend', 'testdriver/session_start', 'testdriver/session_status', 'testdriver/type', 'testdriver/view_local_screenshot', 'testdriver/wait', 'todo']
 mcp-servers:
   testdriver:
     command: npx
@@ -48,6 +48,41 @@ Use this agent when the user asks to:
 
 ## Prerequisites
 
+### Quick Start - Creating Your First TestDriver Test
+
+**For new projects, use the `init` command to automatically set up everything:**
+
+**CLI:**
+```bash
+npx testdriverai@beta init
+```
+
+**MCP (via this agent):**
+```
+// apiKey is optional - if not provided, user adds it to .env manually after init
+init({ directory: "." })
+
+// Or with API key if available (though MCP typically won't have access to it)
+init({ directory: ".", apiKey: "your_api_key" })
+```
+
+**Note:** The `apiKey` parameter is optional. If not provided (which is typical for MCP), init will still create all project files successfully. The user can manually add `TD_API_KEY=...` to the `.env` file afterward.
+
+The `init` command creates:
+- ✅ `package.json` with proper dependencies
+- ✅ Example test files (`tests/example.test.js`, `tests/login.js`)
+- ✅ `vitest.config.js` with correct timeouts
+- ✅ `.gitignore` with `.env`
+- ✅ GitHub Actions workflow (`.github/workflows/testdriver.yml`)
+- ✅ VSCode MCP config (`.vscode/mcp.json`)
+- ✅ TestDriver skills and agents in `.github/`
+- ✅ `.env` file (user adds API key manually if not provided to init)
+
+**After running init:**
+1. User adds their API key to `.env`: `TD_API_KEY=...`
+2. Test the setup: `npx vitest run`
+3. Start building custom tests using the examples as templates
+
 ### API Key Setup
 
 The user **must** have a TestDriver API key set in their environment:
@@ -59,14 +94,12 @@ TD_API_KEY=your_api_key_here
 
 Get your API key at: **https://console.testdriver.ai/team**
 
-### Installation
+### Manual Installation
 
-Always use the **beta** tag when installing TestDriver:
+If not using `init`, always use the **beta** tag when installing TestDriver:
 
 ```bash
 npm install --save-dev testdriverai@beta
-# or
-npx testdriverai@beta init
 ```
 
 ### Test Runner
@@ -119,6 +152,7 @@ describe("My Test Suite", () => {
     const button = await testdriver.find("Sign In button");
     await testdriver.screenshot(); // Capture before click
     await button.click();
+    await testdriver.wait(2000); // Wait for state change
     await testdriver.screenshot(); // Capture after click
 
     // Assert using natural language
@@ -207,6 +241,23 @@ await testdriver.screenshot(1, false, true);
 - After any action that changes the page state
 - When debugging a flaky or failing test
 
+**⚠️ Important: Add delays before screenshots after actions**
+
+When you click or interact with an element that triggers a state change (page navigation, modal opening, content loading), **add a short delay before taking a screenshot** to allow the application state to update:
+
+```javascript
+await element.click();
+await testdriver.wait(2000); // Wait 2-3 seconds for state change
+await testdriver.screenshot(); // Now capture the updated state
+```
+
+This is especially important for:
+- Navigation clicks (page transitions)
+- Button clicks that open modals or dialogs
+- Form submissions
+- Actions that trigger AJAX requests or animations
+- Any interaction where visual feedback takes time to appear
+
 **Screenshot file organization:**
 
 ```
@@ -258,6 +309,7 @@ find_and_click({ description: "email input field" })
 → Returns: screenshot with element highlighted
 → ⚠️ IMMEDIATELY append to test file:
    await testdriver.find("email input field").click();
+   await testdriver.wait(2000); // Wait for state change
    await testdriver.screenshot(); // Capture after click
 
 type({ text: "user@example.com" })
@@ -320,17 +372,60 @@ Analyze the output, fix any issues, and iterate until the test passes.
 | `assert` | AI-powered boolean assertion - GENERATES CODE for test files |
 | `exec` | Execute JavaScript, shell, or PowerShell in sandbox |
 | `screenshot` | Capture screenshot - **only use when user explicitly asks** |
+| `list_local_screenshots` | List screenshots saved in `.testdriver` directory |
+| `view_local_screenshot` | View a local screenshot (returns image to AI + displays to user) |
+
+### Debugging with Local Screenshots
+
+After test runs (successful or failed), you can view saved screenshots to understand test behavior:
+
+**1. List available screenshots:**
+
+```
+list_local_screenshots({ directory: "login.test" })
+```
+
+This returns all screenshots from the specified test file, sorted by modification time (newest first).
+
+**2. View specific screenshots:**
+
+```
+view_local_screenshot({ path: ".testdriver/screenshots/login.test/after-click.png" })
+```
+
+This displays the screenshot to both you (the AI) and the user via MCP App.
+
+**When to use screenshot viewing:**
+
+- **After test failures** - View screenshots to see exactly what the UI looked like when the test failed
+- **Debugging element finding issues** - See if elements are actually visible or have different appearances than expected
+- **Comparing test runs** - View screenshots from multiple runs to identify flaky behavior
+- **Verifying test logic** - Before running a test, view screenshots from previous runs to understand the UI flow
+
+**Workflow example:**
+
+```
+# Test failed, let's debug
+list_local_screenshots({ directory: "checkout.test" })
+
+# View the last few screenshots to see what happened
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/screenshot-1737633620000.png" })
+view_local_screenshot({ path: ".testdriver/screenshots/checkout.test/before-assertion.png" })
+
+# Analyze the UI state and update test code accordingly
+```
 
 ### Tips for MCP Workflow
 
 1. **⚠️ Write code IMMEDIATELY** - After EVERY action, append generated code to test file RIGHT AWAY
 2. **⚠️ Run tests YOURSELF** - Use `npx vitest run` - do NOT tell user to run tests
 3. **⚠️ Add screenshots liberally** - Include `await testdriver.screenshot()` after every significant action for debugging
-4. **Work incrementally** - Don't try to build the entire test at once
-5. **Use `check` after actions** - Verify your actions succeeded before moving on (for YOUR understanding)
-6. **Use `assert` for test verifications** - These generate code that goes in the test file
-7. **Be specific with element descriptions** - "the blue Sign In button in the header" is better than "button"
-8. **Extend session proactively** - Sessions expire after 5 minutes; use `session_extend` if needed
+4. **⚠️ Use screenshot viewing for debugging** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` to understand what went wrong
+5. **Work incrementally** - Don't try to build the entire test at once
+6. **Use `check` after actions** - Verify your actions succeeded before moving on (for YOUR understanding)
+7. **Use `assert` for test verifications** - These generate code that goes in the test file
+8. **Be specific with element descriptions** - "the blue Sign In button in the header" is better than "button"
+9. **Extend session proactively** - Sessions expire after 5 minutes; use `session_extend` if needed
 
 ## Recommended Development Workflow
 
@@ -356,6 +451,7 @@ it("should incrementally build test", async (context) => {
 
   // Step 2: Interact
   await element.click();
+  await testdriver.wait(2000); // Wait for state change
   await testdriver.screenshot(); // Capture after click
 
   // Step 3: Assert and log
@@ -420,10 +516,23 @@ await element.click();
 
 ### Scrolling
 
+**⚠️ Important: Ensure proper focus before scrolling**
+
+Scrolling requires the page or frame to be focused, not an input field or other interactive element. If an input is focused, scroll commands may not work as expected.
+
 ```javascript
+// If you've been typing in an input, click elsewhere first
+await testdriver.find("page background").click();
+// Or press Escape to unfocus
+await testdriver.pressKeys(["escape"]);
+
+// Now scroll
 await testdriver.scroll("down");
 await testdriver.scrollUntilText("Footer text");
 await testdriver.scrollUntilImage("Product image at bottom");
+
+// If scroll is not working, try using Page Down key directly
+await testdriver.pressKeys(["pagedown"]);
 ```
 
 ### Executing Code in Sandbox
@@ -455,6 +564,7 @@ await testdriver.provision.chrome({ url: "https://example.com" });
 await testdriver.screenshot(); // After page load
 
 await testdriver.find("Login button").click();
+await testdriver.wait(2000); // Wait for state change
 await testdriver.screenshot(); // After click
 
 await testdriver.type("user@example.com");
@@ -469,15 +579,16 @@ const result = await testdriver.assert("dashboard is visible");
 1. **⚠️ WRITE CODE IMMEDIATELY** - After EVERY successful MCP action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the session ends.
 2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `npx vitest run <testFile> --reporter=dot`. Always use `--reporter=dot` for cleaner output. Analyze the output and iterate until the test passes. **Always share the test report link** (e.g., `https://app.testdriver.ai/projects/.../reports/...`) with the user after each run.
 3. **⚠️ ADD SCREENSHOTS LIBERALLY** - Include `await testdriver.screenshot()` throughout your tests: after provision, before/after clicks, after typing, and before assertions. This creates a visual trail that makes debugging failures much easier.
-4. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
-5. **Use MCP tools for development** - Build tests interactively with visual feedback
-6. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
-7. **Look at test samples** in `node_modules/testdriverai/test` for working examples
-8. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
-9. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
-10. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
-11. **Start simple** - get one step working before adding more
-12. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
+4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. This is often faster than re-running the test.
+5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+6. **Use MCP tools for development** - Build tests interactively with visual feedback
+7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
+8. **Look at test samples** in `node_modules/testdriverai/test` for working examples
+9. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
+10. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
+11. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
+12. **Start simple** - get one step working before adding more
+13. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
 
    ```json
    // eslint.config.js (for TypeScript projects)

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

@@ -55,12 +55,18 @@ const testdriver = new TestDriver(apiKey, options)
 ```javascript
 import TestDriver from 'testdriverai';
 
-const testdriver = new TestDriver(process.env.TD_API_KEY, {
+// API key is automatically loaded from TD_API_KEY in .env
+const testdriver = new TestDriver({
   os: 'windows',
   resolution: '1920x1080',
   logging: true,
   analytics: true
 });
+
+// Or pass API key explicitly
+const testdriver = new TestDriver('your-api-key', {
+  os: 'windows'
+});
 ```
 
 ## Authentication
@@ -266,8 +272,8 @@ describe('My Test Suite', () => {
   let testdriver;
 
   beforeAll(async () => {
-    // Initialize client
-    client = new TestDriver(process.env.TD_API_KEY, {
+    // Initialize client - API key loaded automatically from .env
+    testdriver = new TestDriver({
       os: 'windows',
       resolution: '1366x768',
       logging: true
@@ -319,10 +325,15 @@ describe('My Test Suite', () => {
   </Accordion>
   
   <Accordion title="Use environment variables for API keys">
-    Never hardcode API keys. Use environment variables:
+    Never hardcode API keys. The SDK automatically loads `TD_API_KEY` from your `.env` file:
+    
+    ```bash .env
+    TD_API_KEY=your_api_key_here
+    ```
     
     ```javascript
-    const testdriver = new TestDriver(process.env.TD_API_KEY);
+    // API key is loaded automatically - no need to pass it!
+    const testdriver = new TestDriver();
     ```
   </Accordion>
 </AccordionGroup>

package/ai/skills/testdriver:generating-tests/SKILL.md

@@ -6,10 +6,10 @@ description: Use AI coding agents and exploration mode to generate TestDriver te
 
 ## Instructions for Coding Agents
 
-We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agents.md file.
+We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agent instructions file.
 
-<Card title="Agents.md" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/agents.md?plain=1">
-  Copy the current version of agents.md to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
+<Card title="TestDriver Agent Instructions" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md?plain=1">
+  Copy the current version of our agent instructions to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
 </Card>
 
 Then, you can prompt your coding agent to generate tests. Here is an example prompt:

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

@@ -133,7 +133,35 @@ describe("Login Flow", () => {
   </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