testdriverai 7.8.0-test.8 → 7.8.0

package/docs/v7/events.mdx

@@ -0,0 +1,358 @@
+---
+title: "Events"
+sidebarTitle: "Events"
+description: "Listen to SDK lifecycle events with wildcard support"
+icon: "bolt"
+mode: "wide"
+---
+
+## Overview
+
+TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a colon-delimited namespace pattern and support wildcard listeners.
+
+Access the emitter through `testdriver.emitter`:
+
+```javascript
+testdriver.emitter.on('command:start', (data) => {
+  console.log(`Running: ${data.command}`);
+});
+```
+
+### Configuration
+
+The internal emitter is created with:
+
+```javascript
+new EventEmitter2({
+  wildcard: true,
+  delimiter: ':',
+  maxListeners: 20,
+  verboseMemoryLeak: false,
+  ignoreErrors: false,
+});
+```
+
+### Wildcard Listeners
+
+Use `*` to match a single level or `**` to match multiple levels:
+
+```javascript
+// Match all log events
+testdriver.emitter.on('log:*', (message) => {
+  console.log(message);
+});
+
+// Match all events in any namespace
+testdriver.emitter.on('**', (...args) => {
+  console.log('Event:', this.event, args);
+});
+```
+
+## Event Reference
+
+### Command Events
+
+Emitted during the execution of SDK commands (`click`, `type`, `find`, etc.).
+
+| Event | Payload |
+|---|---|
+| `command:start` | `{ command, depth, data, timestamp, sourcePosition }` |
+| `command:success` | `{ command, depth, data, duration, response, timestamp, sourcePosition }` |
+| `command:error` | `{ command, depth, data, error, duration, timestamp, sourcePosition }` |
+| `command:status` | `{ command, status: "executing", data, depth, timestamp }` |
+| `command:progress` | `{ command, status: "completed", timing, data, depth, timestamp }` |
+
+```javascript
+testdriver.emitter.on('command:start', ({ command, data }) => {
+  console.log(`Starting ${command}`, data);
+});
+
+testdriver.emitter.on('command:error', ({ command, error, duration }) => {
+  console.error(`${command} failed after ${duration}ms: ${error}`);
+});
+```
+
+### Step Events
+
+Emitted for each AI reasoning step within a command.
+
+| Event | Payload |
+|---|---|
+| `step:start` | `{ stepIndex, prompt, commandCount, timestamp, sourcePosition }` |
+| `step:success` | `{ stepIndex, prompt, commandCount, duration, timestamp, sourcePosition }` |
+| `step:error` | `{ stepIndex, prompt, error, duration?, timestamp, sourcePosition? }` |
+
+```javascript
+testdriver.emitter.on('step:start', ({ stepIndex, prompt }) => {
+  console.log(`Step ${stepIndex}: ${prompt}`);
+});
+```
+
+### Test Events
+
+Emitted when a test file execution starts.
+
+| Event | Payload |
+|---|---|
+| `test:start` | `{ filePath, timestamp }` |
+| `test:success` | *Emitted on test completion* |
+| `test:error` | *Emitted on test failure* |
+
+### Log Events
+
+Emitted for all log output from the SDK.
+
+| Event | Payload |
+|---|---|
+| `log:log` | `(message: string)` — general log message |
+| `log:warn` | `(message: string)` — warning message |
+| `log:debug` | `(message: string)` — debug output (only when `VERBOSE`/`DEBUG`/`TD_DEBUG` env set) |
+| `log:info` | `(message: string)` — informational message |
+| `log:error` | `(message: string)` — error message |
+| `log:narration` | `(message: string, overwrite?: boolean)` — in-place status line |
+| `log:markdown` | `(markdown: string)` — full static markdown content |
+| `log:markdown:start` | `(streamId: string)` — begin streaming markdown |
+| `log:markdown:chunk` | `(streamId: string, chunk: string)` — incremental chunk |
+| `log:markdown:end` | `(streamId: string)` — end streaming markdown |
+
+```javascript
+// Capture all logs
+testdriver.emitter.on('log:*', function (message) {
+  console.log(`[${this.event}]`, message);
+});
+```
+
+### Screen Capture Events
+
+Emitted during screenshot capture.
+
+| Event | Payload |
+|---|---|
+| `screen-capture:start` | `{ scale, silent, display }` |
+| `screen-capture:end` | `{ scale, silent, display }` |
+| `screen-capture:error` | `{ error, scale, silent, display }` |
+
+### Sandbox Events
+
+Emitted for sandbox WebSocket lifecycle and communication.
+
+| Event | Payload |
+|---|---|
+| `sandbox:connected` | *No payload* — WebSocket connection established |
+| `sandbox:authenticated` | `{ traceId }` — authentication successful |
+| `sandbox:error` | `(err: Error \| string)` — connection or sandbox error |
+| `sandbox:sent` | `(message: object)` — WebSocket message sent |
+| `sandbox:received` | *No payload* — successful message reply received |
+| `sandbox:progress` | `{ step, message }` — sandbox setup progress |
+
+```javascript
+testdriver.emitter.on('sandbox:connected', () => {
+  console.log('Connected to sandbox');
+});
+
+testdriver.emitter.on('sandbox:progress', ({ step, message }) => {
+  console.log(`Sandbox: [${step}] ${message}`);
+});
+```
+
+### Redraw Events
+
+Emitted during screen stability detection. See [Redraw](/v7/redraw) for more details.
+
+| Event | Payload |
+|---|---|
+| `redraw:status` | `{ redraw: { enabled, settled, hasChangedFromInitial, consecutiveFramesStable, diffFromInitial, diffFromLast, text }, network: { enabled, settled, rxBytes, txBytes, text }, timeout: { isTimeout, elapsed, max, text } }` |
+| `redraw:complete` | `{ screenSettled, hasChangedFromInitial, consecutiveFramesStable, networkSettled, isTimeout, timeElapsed }` |
+
+```javascript
+testdriver.emitter.on('redraw:complete', (result) => {
+  if (result.isTimeout) {
+    console.warn('Redraw timed out after', result.timeElapsed, 'ms');
+  }
+});
+```
+
+### File Events
+
+Emitted during file load/save operations in the agent.
+
+| Event | Payload |
+|---|---|
+| `file:start` | `{ operation: "load" \| "save" \| "run", filePath, timestamp }` |
+| `file:stop` | `{ operation, filePath, duration, success, sourceMap?, reason?, timestamp }` |
+| `file:load` | `{ filePath, size, timestamp }` |
+| `file:save` | `{ filePath, size, timestamp }` |
+| `file:diff` | `{ filePath, diff: { patches, sourceMaps, summary: { additions, deletions, modifications } }, timestamp }` |
+| `file:error` | `{ operation, filePath, error, duration?, timestamp }` |
+
+### Error Events
+
+Emitted for errors at various severity levels.
+
+| Event | Payload |
+|---|---|
+| `error:fatal` | `(error: string \| Error)` — terminates the process |
+| `error:general` | `(message: string)` — non-fatal error |
+| `error:sandbox` | `(err: Error \| string)` — sandbox/WebSocket error |
+
+```javascript
+testdriver.emitter.on('error:*', function (err) {
+  console.error(`[${this.event}]`, err);
+});
+```
+
+### SDK Events
+
+Emitted for API request lifecycle.
+
+| Event | Payload |
+|---|---|
+| `sdk:request` | `{ path }` — outgoing API request |
+| `sdk:response` | `{ path }` — API response received |
+| `sdk:retry` | `{ path, attempt, error, delayMs }` — request retry |
+
+### Other Events
+
+| Event | Payload |
+|---|---|
+| `exit` | `(exitCode: number)` — `0` for success, `1` for failure |
+| `status` | `(message: string)` — general status updates |
+| `mouse-click` | `{ x, y, button, click, double }` — mouse click performed |
+| `terminal:stdout` | Terminal stdout output |
+| `terminal:stderr` | Terminal stderr output |
+
+## Practical Examples
+
+### Custom Test Reporter
+
+```javascript
+const results = [];
+
+testdriver.emitter.on('command:success', ({ command, duration }) => {
+  results.push({ command, duration, status: 'pass' });
+});
+
+testdriver.emitter.on('command:error', ({ command, duration, error }) => {
+  results.push({ command, duration, status: 'fail', error });
+});
+
+// After test completes
+afterAll(() => {
+  console.table(results);
+});
+```
+
+### Progress Monitoring
+
+```javascript
+testdriver.emitter.on('step:start', ({ stepIndex, prompt }) => {
+  process.stdout.write(`\r  Step ${stepIndex}: ${prompt}`);
+});
+
+testdriver.emitter.on('command:progress', ({ command, timing }) => {
+  process.stdout.write(`\r  ${command} completed in ${timing}ms`);
+});
+```
+
+### Debug Logging
+
+```javascript
+// Log every event (verbose)
+testdriver.emitter.on('**', function (...args) {
+  console.debug(`[EVENT] ${this.event}`, ...args);
+});
+```
+
+## Types
+
+```typescript
+interface CommandStartEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface CommandSuccessEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  duration: number;
+  response: any;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface CommandErrorEvent {
+  command: string;
+  depth: number;
+  data: Record<string, any>;
+  error: string;
+  duration: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface StepStartEvent {
+  stepIndex: number;
+  prompt: string;
+  commandCount: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface StepSuccessEvent {
+  stepIndex: number;
+  prompt: string;
+  commandCount: number;
+  duration: number;
+  timestamp: number;
+  sourcePosition: SourcePosition;
+}
+
+interface RedrawStatusEvent {
+  redraw: {
+    enabled: boolean;
+    settled: boolean;
+    hasChangedFromInitial: boolean;
+    consecutiveFramesStable: number;
+    diffFromInitial: number;
+    diffFromLast: number;
+    text: string;
+  };
+  network: {
+    enabled: boolean;
+    settled: boolean;
+    rxBytes: number;
+    txBytes: number;
+    text: string;
+  };
+  timeout: {
+    isTimeout: boolean;
+    elapsed: number;
+    max: number;
+    text: string;
+  };
+}
+
+interface RedrawCompleteEvent {
+  screenSettled: boolean;
+  hasChangedFromInitial: boolean;
+  consecutiveFramesStable: number;
+  networkSettled: boolean;
+  isTimeout: boolean;
+  timeElapsed: number;
+}
+
+interface SandboxProgressEvent {
+  step: string;
+  message: string;
+}
+
+interface SourcePosition {
+  file: string;
+  line: number;
+  column: number;
+}
+```

package/docs/v7/examples/exec-output.mdx

@@ -0,0 +1,85 @@
+---
+title: "Exec Output Test Example"
+sidebarTitle: "Exec Output"
+description: "Example test demonstrating how to capture and use output from PowerShell exec commands."
+icon: "terminal"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* exec-output.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/69a62b42fc0ac3cc632a918c/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="exec-output.test.mjs" {22-27}
+/**
+ * TestDriver SDK - Exec Output Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-output.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec Output Test", () => {
+  it(
+    "should set date using PowerShell and navigate to calendar",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Generate date in query string format
+      const queryString = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("yyyy-MM-dd")
+    `,
+        10000,
+      );
+
+      // Assert that the date is valid
+      const dateValidResult = await testdriver.assert(
+        `${queryString} is a valid date`,
+      );
+      expect(dateValidResult).toBeTruthy();
+
+      // Generate date in display format
+      const expectedDate = await testdriver.exec(
+        "pwsh",
+        `
+$date = (Get-Date).AddMonths(1)
+Write-Output $date.ToString("ddd MMM d yyyy")
+    `,
+        10000,
+      );
+
+      // Navigate to calendar with date parameter
+      await testdriver.focusApplication("Google Chrome");
+      await testdriver.pressKeys(["ctrl", "l"]);
+      await testdriver.type(
+        `https://teamup.com/ks48cf2135e7e080bc?view=d&date=${queryString}`,
+      );
+      await testdriver.pressKeys(["enter"]);
+
+      // Assert that the expected date shows
+      await testdriver.focusApplication("Google Chrome");
+      const result = await testdriver.assert(
+        `the text ${expectedDate} is visible on screen`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```

package/docs/v7/examples/exec-pwsh.mdx

@@ -0,0 +1,83 @@
+---
+title: "Exec PowerShell Test Example"
+sidebarTitle: "Exec Pwsh"
+description: "Example test demonstrating how to generate dynamic data using PowerShell and use it in test interactions."
+icon: "terminal"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* exec-pwsh.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/69a62b42565d339e8065f180/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="exec-pwsh.test.mjs" {20-38}
+/**
+ * TestDriver SDK - Exec Shell Test (Vitest)
+ * Converted from: testdriver/acceptance/exec-shell.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe.skip("Exec PowerShell Test", () => {
+  it(
+    "should generate random email using PowerShell and enter it",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Generate random email using PowerShell
+      const randomEmail = await testdriver.exec({
+        language: "pwsh",
+        code: `
+# Random email generator in PowerShell
+
+# Arrays of possible names and domains
+$firstNames = @("john", "jane", "alex", "chris", "sara", "mike", "lisa", "david", "emma", "ryan")
+$lastNames = @("smith", "johnson", "williams", "brown", "jones", "garcia", "miller", "davis", "martin", "lee")
+$domains = @("example.com", "testmail.com", "mailinator.com", "demo.org", "company.net")
+
+# Random selection
+$first = Get-Random -InputObject $firstNames
+$last = Get-Random -InputObject $lastNames
+$domain = Get-Random -InputObject $domains
+$number = Get-Random -Minimum 1 -Maximum 1000
+
+# Generate the email
+$email = "$first.$last$number@$domain".ToLower()
+
+# Output
+Write-Output "$email"
+    `,
+        timeout: 10000,
+      });
+
+      // Enter the email in username field
+      const usernameField = await testdriver.find(
+        "Username, input field for username",
+      );
+      await usernameField.click();
+      await testdriver.type(randomEmail);
+
+      // Assert that the username field shows a valid email address
+      const result = await testdriver.assert(
+        `the username field contains ${randomEmail} which is a valid email address`,
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```

package/docs/v7/examples/focus-window.mdx

@@ -0,0 +1,62 @@
+---
+title: "Focus Window Test Example"
+sidebarTitle: "Focus Window"
+description: "Example test demonstrating how to switch focus between application windows."
+icon: "window-maximize"
+mode: "wide"
+---
+
+## Demo Test Run
+
+Watch this test execute in a real sandbox environment:
+
+{/* focus-window.test.mjs output */}
+<iframe 
+  src="https://testdriver-api.onrender.com/api/v1/testdriver/testcase/69a62b4549845ced0b71e2b1/replay" 
+  width="100%" 
+  height="390" 
+  style={{ border: "1px solid #333", borderRadius: "8px" }}
+  allow="fullscreen"
+/>
+
+## Source Code
+
+```javascript title="focus-window.test.mjs" {23-25}
+/**
+ * TestDriver SDK - Focus Window Test (Vitest)
+ * Converted from: testdriver/acceptance/focus-window.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+import { getDefaults } from "./config.mjs";
+
+describe("Focus Window Test", () => {
+  it.skip(
+    "should click Microsoft Edge icon and focus Google Chrome",
+    async (context) => {
+      const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
+      // Show desktop
+      await testdriver.pressKeys(["winleft", "d"]);
+
+      // Click on the Microsoft Edge icon
+      const edgeIcon = await testdriver.find(
+        "a blue and green swirl icon on the taskbar representing Microsoft Edge",
+      );
+      await edgeIcon.click();
+
+      // Focus Google Chrome
+      await testdriver.focusApplication("Google Chrome");
+
+      // Assert Chrome is focused (implicit through successful focus)
+      const result = await testdriver.assert(
+        "Google Chrome is the focused application",
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+});
+```

package/docs/v7/{cloud.mdx → hosted.mdx}

@@ -1,18 +1,56 @@
 ---
-title: "Cloud Plan"
-sidebarTitle: "Cloud"
+title: "Hosted"
+sidebarTitle: "Hosted"
 description: "The fastest way to get started with TestDriver. Just set your API key and start testing."
 icon: "cloud"
+mode: "wide"
 ---
 
-Cloud pricing is based on **device-seconds**: the amount of time your tests run on **our infrastructure**.
+Hosted pricing is based on **device-seconds**: the amount of time your tests run on **our infrastructure**.
 
 - **Zero Setup** — Start testing immediately. No DevOps required.
 - **Free Tier** — Get started with a limited preview at no cost.
 - **Pay As You Go** — Only pay for the device-seconds you use.
 
+## Hosted Plans
+
+<CardGroup cols={3}>
+  <Card title="Free Trial" icon="gift" href="https://docs.testdriver.ai">
+    **$0/month**
+    
+    - 1 Concurrent Sandbox
+    - 60 Minutes Included
+    - 1 Team User
+    - Community Support
+  </Card>
+  
+  <Card title="Pro" icon="rocket" href="https://console.testdriver.ai/checkout/pro">
+    **$20/month**
+    
+    - 2 Concurrent Sandboxes
+    - 600 Minutes Included
+    - Overage: $0.002/second
+    - 1 Team User
+    - Test Recordings
+    - Community Support
+  </Card>
+  
+  <Card title="Team" icon="users" href="https://console.testdriver.ai/checkout/team">
+    **$600/month**
+    
+    - 8 Concurrent Sandboxes
+    - 10,000 Minutes Included
+    - Overage: $0.001/second
+    - 5 Team Users
+    - Test Recordings
+    - Private Support
+    - Test Analytics
+    - CPU, RAM, & Network Profiles
+  </Card>
+</CardGroup>
+
 ## Get Started
-Cloud is the default when you follow the Quickstart guide. 
+Hosted is the default when you follow the Quickstart guide. 
 <Card
   title="Try the Quickstart"  
   icon="play"
@@ -102,7 +140,7 @@ To prevent tests from failing due to exceeding your license slot limit, we recom
 
 ## When to Consider Self-Hosted
 
-Cloud is perfect for getting started and for teams that want zero infrastructure management. However, you might consider [Self-Hosted](/v7/self-hosted) if you:
+Hosted is perfect for getting started and for teams that want zero infrastructure management. However, you might consider [Self-Hosted](/v7/self-hosted) if you:
 
 - Want to escape per-second billing with a flat license fee
 - Require greater concurrency than offered in Cloud plans

package/docs/v7/mcp.mdx

@@ -0,0 +1,9 @@
+---
+title: "GitHub Copilot Guide"
+sidebarTitle: "GitHub Copilot Guide"
+description: "Execute natural language tasks using AI"
+icon: "github"
+---
+
+## Overview
+