testdriverai 7.0.0 → 7.1.1

package/.env.example

@@ -0,0 +1,2 @@
+TD_API_KEY=
+TD_API_ROOT=

package/.github/workflows/linux-tests.yml

@@ -0,0 +1,28 @@
+name: Linux Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+    
+    - name: Install dependencies
+      run: npm ci
+    
+    - name: Run Linux tests
+      run: npx vitest run test/testdriver/assert.test.mjs
+      env:
+        TD_API_KEY: ${{ secrets.TD_API_KEY }}

package/README.md

@@ -10,6 +10,71 @@ Automate and scale QA with computer-use agents.
 
 [Follow the instructions on our docs for more.](https://docs.testdriver.ai/overview/quickstart).
 
+## v7 SDK - Progressive Disclosure
+
+TestDriver v7 introduces **three levels of API** to match your experience level:
+
+### 🟢 Beginner: Presets (Zero Config)
+
+```javascript
+import { test } from 'vitest';
+import { chromePreset } from 'testdriverai/presets';
+
+test('login test', async (context) => {
+  const { client } = await chromePreset(context, {
+    url: 'https://myapp.com'
+  });
+  
+  await client.find('Login button').click();
+});
+```
+
+**Built-in presets:** Chrome, VS Code, Electron, and create your own!
+
+### 🟡 Intermediate: Hooks (Flexible)
+
+```javascript
+import { test } from 'vitest';
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoStart: true,
+    autoStop: true
+  });
+  
+  await client.find('button').click();
+});
+```
+
+**Automatic lifecycle management** - no more forgetting cleanup!
+
+### 🔴 Advanced: Core Classes (Full Control)
+
+```javascript
+import { test } from 'vitest';
+import { TestDriver, Dashcam } from 'testdriverai/core';
+
+test('my test', async () => {
+  const client = new TestDriver(apiKey, { os: 'linux' });
+  const dashcam = new Dashcam(client);
+  
+  await client.auth();
+  await client.connect();
+  await dashcam.start();
+  
+  await client.find('button').click();
+  
+  await dashcam.stop();
+  await client.disconnect();
+});
+```
+
+**Full manual control** for advanced scenarios.
+
+📖 **Learn more:** [MIGRATION.md](./docs/MIGRATION.md) | [PRESETS.md](./docs/PRESETS.md) | [HOOKS.md](./docs/HOOKS.md)
+
 # About
 
 TestDriver isn't like any test framework you've used before. TestDriver is an OS Agent for QA. TestDriver uses AI vision along with mouse and keyboard emulation to control the entire desktop. It's more like a QA employee than a test framework. This kind of black-box testing has some major advantages:
@@ -186,3 +251,64 @@ You can also set the default test file path using environment variables:
 export TD_DEFAULT_TEST_FILE="custom/path/test.yaml"
 node your-script.js
 ```
+
+## MCP Server for AI Agents
+
+TestDriver includes a Model Context Protocol (MCP) server that enables AI agents to **interactively create Vitest test files**.
+
+### How It Works
+
+1. **AI agent connects** to a persistent TestDriver sandbox
+2. **User describes** what they want to test
+3. **AI explores** the application using TestDriver commands
+4. **AI generates** Vitest test code from successful interactions
+
+### Quick Start
+
+```bash
+cd mcp-server
+npm install && npm run build
+npm run deploy  # Install to ~/.mcp/testdriver
+```
+
+### Configuration
+
+Add to your MCP client configuration:
+
+```json
+{
+  "servers": {
+    "testdriverai": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/cli/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+### Example Workflow
+
+```
+User: "Create a test that logs into the app"
+
+AI: [Connects to sandbox with user's API key]
+AI: [Takes screenshot to see login page]
+AI: [Finds username field: await testdriver_find({ description: "username field" })]
+AI: [Clicks and types: await testdriver_type({ text: "test_user" })]
+AI: [Finds password field, enters password]
+AI: [Clicks login button]
+AI: [Asserts login succeeded]
+AI: [Generates Vitest test file from these steps]
+AI: [Saves test/login.test.mjs]
+```
+
+### Key Features
+
+- **Persistent sandbox** - Connection stays alive throughout test creation
+- **Live debugger URL** - User can watch the AI test in real-time
+- **Full SDK access** - All v7 SDK methods available
+- **Code generation** - AI translates interactions into proper Vitest code
+
+See [mcp-server/TEST_CREATION_GUIDE.md](mcp-server/TEST_CREATION_GUIDE.md) for the complete guide.
+

package/agent/index.js

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 // disable depreciation warnings
 process.removeAllListeners("warning");
 
@@ -109,8 +107,8 @@ class TestDriverAgent extends EventEmitter2 {
     // Create analytics instance with this agent's emitter, config, and session
     this.analytics = createAnalytics(this.emitter, this.config, this.session);
 
-    // Create sandbox instance with this agent's emitter and analytics
-    this.sandbox = createSandbox(this.emitter, this.analytics);
+    // Create sandbox instance with this agent's emitter, analytics, and session
+    this.sandbox = createSandbox(this.emitter, this.analytics, this.session);
 
     // Set the OS for the sandbox to use
     this.sandbox.os = this.sandboxOs;
@@ -127,6 +125,7 @@ class TestDriverAgent extends EventEmitter2 {
       this.session,
       () => this.sourceMapper.currentFilePath || this.thisFile,
       this.cliArgs.options.redrawThreshold,
+      null, // getDashcamElapsedTime - will be set by SDK when dashcam is available
     );
     this.commands = commandsResult.commands;
     this.redraw = commandsResult.redraw;
@@ -225,13 +224,12 @@ class TestDriverAgent extends EventEmitter2 {
       this.emitter.emit(events.error.fatal, errorContext);
     } else {
       this.emitter.emit(
-        events.error.fatal,
-        theme.red("Fatal Error") + `\n${error}`,
+        events.error.fatal,error,
       );
     }
 
     if (skipPostrun) {
-      this.exit(true);
+      return await this.exit(true);
     } else {
       try {
         await this.summarize(error.message);
@@ -1927,7 +1925,7 @@ ${regression}
     if (!this.instance) {
       this.emitter.emit(
         events.log.narration,
-        theme.dim(`creating new sandbox (can take up to 2 minutes)...`),
+        theme.dim(`creating new sandbox...`),
       );
       // We don't have resiliency/retries baked in, so let's at least give it 1 attempt
       // to see if that fixes the issue.
@@ -2161,7 +2159,7 @@ Please check your network connection, TD_API_KEY, or the service status.`,
       type: "create",
       resolution: this.config.TD_RESOLUTION,
       ci: this.config.CI,
-      os: this.sandboxOs || "windows",
+      os: this.sandboxOs || "linux",
     };
 
     // Add AMI and instance type if specified

package/agent/interface.js

@@ -69,7 +69,7 @@ function createCommandDefinitions(agent) {
         os: Flags.string({
           description: "Operating system for the sandbox (windows or linux)",
           options: ["windows", "linux"],
-          default: "windows",
+          default: "linux",
         }),
       },
       handler: async (args, flags) => {
@@ -246,7 +246,7 @@ function createCommandDefinitions(agent) {
         os: Flags.string({
           description: "Operating system for the sandbox (windows or linux)",
           options: ["windows", "linux"],
-          default: "windows",
+          default: "linux",
         }),
       },
       handler: async (args, flags) => {
@@ -254,6 +254,17 @@ function createCommandDefinitions(agent) {
         await agent.generate(flags.count || 3, args.prompt);
       },
     },
+
+    init: {
+      description: "Initialize a new TestDriver project with Vitest SDK examples",
+      args: {},
+      flags: {},
+      handler: async () => {
+        // This handler is special - it doesn't need an agent instance
+        // It just scaffolds files, so it will be handled by the CLI command
+        throw new Error("Init mode should be handled by CLI interface");
+      },
+    },
   };
 }