testdriverai 6.2.2 → 7.1.0

package/docs/v7/progressive-apis/PROVISION.md

@@ -0,0 +1,266 @@
+# Provision API
+
+The `provision()` function is the easiest way to set up TestDriver for common applications. It automatically handles TestDriver initialization, application launching, and Dashcam recording.
+
+## Quick Start
+
+```javascript
+import { test } from 'vitest';
+import { provision } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { testdriver } = await provision('chrome', {
+    url: 'https://example.com'
+  }, context);
+  
+  await testdriver.find('Login button').click();
+});
+```
+
+## API
+
+```typescript
+provision(appType, options, context)
+```
+
+**Parameters:**
+- `appType` - Application type: `'chrome'`, `'vscode'`, `'electron'`, or `'webapp'`
+- `options` - Configuration options (varies by app type)
+- `context` - Vitest test context (from your test function parameter)
+
+**Returns:**
+- `testdriver` - TestDriver instance ready to use
+- `dashcam` - Dashcam instance (if enabled)
+- Additional app-specific properties (like `vscode`, `app`)
+
+## Application Types
+
+### Chrome Browser
+
+```javascript
+const { testdriver } = await provision('chrome', {
+  url: 'https://myapp.com',
+  maximized: true,      // Start maximized (default: true)
+  guest: true,          // Use guest mode (default: true)
+  dashcam: true,        // Enable Dashcam (default: true)
+  os: 'linux'          // Target OS (default: 'linux')
+}, context);
+
+await testdriver.find('username').type('user@example.com');
+await testdriver.find('Login').click();
+```
+
+**Options:**
+- `url` - URL to navigate to (default: 'http://testdriver-sandbox.vercel.app/')
+- `maximized` - Start browser maximized (default: `true`)
+- `guest` - Use guest/incognito mode (default: `true`)
+- `dashcam` - Enable Dashcam recording (default: `true`)
+- `os` - Target OS: `'linux'`, `'mac'`, or `'windows'` (default: `'linux'`)
+
+**Returns:**
+- `testdriver` - TestDriver instance
+- `dashcam` - Dashcam instance (if enabled)
+
+### VS Code
+
+```javascript
+const { testdriver, vscode } = await provision('vscode', {
+  workspace: '/path/to/project',
+  extensions: ['ms-python.python'],
+  dashcam: true,
+  os: 'linux'
+}, context);
+
+await vscode.find('File menu').click();
+await vscode.find('New File').click();
+```
+
+**Options:**
+- `workspace` - Workspace/folder path to open (optional)
+- `extensions` - Array of extension IDs to install (optional)
+- `dashcam` - Enable Dashcam recording (default: `true`)
+- `os` - Target OS (default: `'linux'`)
+
+**Returns:**
+- `testdriver` - TestDriver instance
+- `vscode` - Alias for testdriver (semantic clarity)
+- `dashcam` - Dashcam instance (if enabled)
+
+### Electron
+
+```javascript
+const { testdriver, app } = await provision('electron', {
+  appPath: '/path/to/app',
+  args: ['--enable-logging'],
+  dashcam: true,
+  os: 'linux'
+}, context);
+
+await app.find('main window').click();
+```
+
+**Options:**
+- `appPath` - Path to Electron application (required)
+- `args` - Additional command-line arguments (optional)
+- `dashcam` - Enable Dashcam recording (default: `true`)
+- `os` - Target OS (default: `'linux'`)
+
+**Returns:**
+- `testdriver` - TestDriver instance
+- `app` - Alias for testdriver (semantic clarity)
+- `dashcam` - Dashcam instance (if enabled)
+
+### Web App
+
+Generic wrapper for web applications (currently uses Chrome):
+
+```javascript
+const { testdriver } = await provision('webapp', {
+  url: 'https://example.com',
+  browser: 'chrome'  // Only 'chrome' supported currently
+}, context);
+```
+
+## Complete Example
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { provision } from 'testdriverai/presets';
+
+describe('Login Flow', () => {
+  it('should login successfully', async (context) => {
+    // Provision Chrome with your app
+    const { testdriver, dashcam } = await provision('chrome', {
+      url: 'https://myapp.com/login',
+      maximized: true
+    }, context);
+    
+    // Interact with the application
+    await testdriver.find('email input').type('user@example.com');
+    await testdriver.find('password input').type('password123');
+    await testdriver.find('Login button').click();
+    
+    // Verify results
+    const result = await testdriver.assert('Welcome message is visible');
+    expect(result).toBeTruthy();
+    
+    // Dashcam automatically stops and saves replay at test end
+    // No cleanup needed - handled automatically!
+  });
+});
+```
+
+## How It Works
+
+When you call `provision()`:
+
+1. **Creates TestDriver client** - Initializes and connects to sandbox
+2. **Sets up Dashcam** - Authenticates and starts recording (if enabled)
+3. **Launches application** - Opens the specified app with your configuration
+4. **Focuses window** - Ensures the app is ready for interaction
+5. **Returns ready-to-use instances** - Everything is set up and ready
+
+At test end:
+- Dashcam automatically stops and saves replay URL
+- TestDriver automatically disconnects
+- All cleanup is handled for you
+
+## Automatic Lifecycle
+
+The `provision()` function uses Vitest hooks under the hood to manage the entire lifecycle:
+
+```javascript
+// ✅ This:
+const { testdriver } = await provision('chrome', { url }, context);
+
+// Is equivalent to manually doing:
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+
+const dashcam = new Dashcam(client);
+await dashcam.auth();
+await dashcam.start();
+
+await client.exec('sh', 'google-chrome --start-maximized --guest "https://example.com" &', 30000);
+await client.focusApplication('Google Chrome');
+
+// ... your test code ...
+
+await dashcam.stop();
+await client.disconnect();
+```
+
+That's **15+ lines of boilerplate** reduced to **1 line**!
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import { provision } from 'testdriverai/presets';
+
+test('typed test', async (context) => {
+  const { testdriver } = await provision('chrome', {
+    url: 'https://example.com',
+    maximized: true,
+    os: 'linux' // ✅ Type-safe: only 'linux' | 'mac' | 'windows'
+  }, context);
+  
+  // ✅ Full autocomplete for testdriver methods
+  await testdriver.find('button').click();
+});
+```
+
+## Direct Preset Functions
+
+You can also use the individual preset functions directly:
+
+```javascript
+import { chrome, vscode, electron } from 'testdriverai/presets';
+
+// Same as provision('chrome', options, context)
+const { testdriver } = await chrome(context, {
+  url: 'https://example.com'
+});
+
+// Same as provision('vscode', options, context)
+const { vscode } = await vscode(context, {
+  workspace: '/path/to/project'
+});
+```
+
+These are available for when you prefer explicit function names.
+
+## Best Practices
+
+1. **Always pass context** - Required for automatic cleanup
+2. **Enable dashcam** - Great for debugging test failures
+3. **Use descriptive variables** - `testdriver`, `vscode`, `app` based on what you're testing
+4. **Leverage TypeScript** - Get autocomplete and type safety
+5. **Keep URLs in config** - Use environment variables for different environments
+
+## Error Handling
+
+```javascript
+test('handles errors gracefully', async (context) => {
+  try {
+    const { testdriver } = await provision('chrome', {
+      url: 'https://example.com'
+    }, context);
+    
+    await testdriver.find('button').click();
+  } catch (error) {
+    // Cleanup still happens automatically
+    console.error('Test failed:', error);
+    throw error; // Re-throw to mark test as failed
+  }
+});
+```
+
+## See Also
+
+- [Hooks API](./HOOKS.md) - For more control over lifecycle
+- [Core Classes](./CORE.md) - For full manual control
+- [Migration Guide](../MIGRATION.md) - Upgrading from v6
+- [Examples](../../testdriver/acceptance-sdk/presets-example.test.mjs) - Working examples

package/eslint.config.js

@@ -35,9 +35,27 @@ module.exports = [
       },
     },
   },
+  {
+    // Config for ES Module files (.mjs) - used in SDK tests
+    files: ["**/*.mjs"],
+    languageOptions: {
+      sourceType: "module",
+      ecmaVersion: 2022,
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
   {
     // this needs to be it's own object for some reason
     // https://github.com/eslint/eslint/issues/17400
-    ignores: ["agent/lib/subimage/**", "node_modules/**", ".git"],
+    ignores: [
+      "agent/lib/subimage/**",
+      "node_modules/**",
+      ".git",
+      "test-results/**",
+      "examples/test-recording-example.test.js",
+      "vitest.config.example.js",
+    ],
   },
 ];

package/interfaces/cli/lib/base.js

@@ -37,12 +37,14 @@ class BaseCommand extends Command {
   }
 
   sendToSandbox(message) {
+    if (!message) return;
+
     // ensure message is a string
     if (typeof message !== "string") {
       message = JSON.stringify(message);
     }
+
     this.agent.sandbox.send({
-      os: "linux",
       type: "output",
       output: Buffer.from(message).toString("base64"),
     });
@@ -95,7 +97,7 @@ class BaseCommand extends Command {
     });
 
     // Handle sandbox connection with pattern matching for subsequent events
-    this.agent.emitter.on("sandbox:connected", () => {
+    this.agent.emitter.once("sandbox:connected", () => {
       isConnected = true;
       // Once sandbox is connected, send all log and error events to sandbox
       this.agent.emitter.on("log:*", (message) => {
@@ -145,8 +147,12 @@ class BaseCommand extends Command {
       console.log(`Live test execution: `);
       if (this.agent.config.CI) {
         let u = new URL(url);
-        u = JSON.parse(u.searchParams.get("data"));
-        console.log(`${u.url}&view_only=true`);
+        try {
+          u = JSON.parse(u.searchParams.get("data"));
+          console.log(`${u.url}&view_only=true`);
+        } catch {
+          console.log(url);
+        }
       } else {
         console.log(url);
         await openBrowser(url);

package/interfaces/logger.js

@@ -21,6 +21,8 @@ class CustomTransport extends Transport {
         this.sandbox = require("../agent/lib/sandbox");
       }
 
+      console.log("CustomTransport log message:", message);
+
       if (this.sandbox && this.sandbox.instanceSocketConnected) {
         if (typeof message === "object") {
           console.log(chalk.cyan("protecting against base64 error"));
@@ -29,7 +31,6 @@ class CustomTransport extends Transport {
         }
 
         this.sandbox.send({
-          os: "linux",
           type: "output",
           output: Buffer.from(message).toString("base64"),
         });

package/interfaces/shared-test-state.mjs

@@ -0,0 +1,69 @@
+/**
+ * Shared Test State Module
+ *
+ * This module uses Node.js module caching to share state between
+ * the reporter process and worker processes in Vitest.
+ *
+ * Since Node.js caches modules, all imports of this file will
+ * receive the same state object instance.
+ */
+
+// Shared state object that persists across all imports
+const sharedState = {
+  testRun: null,
+  testRunId: null,
+  token: null,
+  apiKey: null,
+  apiRoot: null,
+  startTime: null,
+};
+
+/**
+ * Set the test run information
+ */
+export function setTestRunInfo(info) {
+  console.log("[SharedState] Setting test run info:", {
+    testRunId: info.testRunId,
+    hasToken: !!info.token,
+    hasTestRun: !!info.testRun,
+  });
+
+  if (info.testRun) sharedState.testRun = info.testRun;
+  if (info.testRunId) sharedState.testRunId = info.testRunId;
+  if (info.token) sharedState.token = info.token;
+  if (info.apiKey) sharedState.apiKey = info.apiKey;
+  if (info.apiRoot) sharedState.apiRoot = info.apiRoot;
+  if (info.startTime) sharedState.startTime = info.startTime;
+}
+
+/**
+ * Get the test run information
+ */
+export function getTestRunInfo() {
+  return {
+    testRun: sharedState.testRun,
+    testRunId: sharedState.testRunId,
+    token: sharedState.token,
+    apiKey: sharedState.apiKey,
+    apiRoot: sharedState.apiRoot,
+    startTime: sharedState.startTime,
+  };
+}
+
+/**
+ * Clear the test run information
+ */
+export function clearTestRunInfo() {
+  console.log("[SharedState] Clearing test run info");
+  sharedState.testRun = null;
+  sharedState.testRunId = null;
+  sharedState.token = null;
+  sharedState.startTime = null;
+}
+
+/**
+ * Direct access to state (for debugging)
+ */
+export function getState() {
+  return sharedState;
+}