testdriverai 6.2.1 → 7.0.0

package/docs/docs.json

@@ -12,175 +12,255 @@
   },
   "favicon": "/images/template/icon.png",
   "navigation": {
-    "groups": [
+    "tabs": [
       {
-        "group": "Overview",
-        "pages": [
-          "/overview/what-is-testdriver",
+        "tab": "Computer-Use SDK",
+        "versions": [
           {
-            "group": "Concepts",
-            "icon": "book",
-            "pages": [
-              "/features/selectorless",
-              "/overview/comparison",
-              "/overview/performance",
-              "/overview/faq"
+            "version": "7.0.0 (SDK)",
+            "groups": [
+              {
+                "group": "Getting Started",
+                "pages": [
+                  "/v7/getting-started/quickstart"
+                ]
+              },
+              {
+                "group": "API Reference",
+                "pages": [
+                  {
+                    "group": "Setup",
+                    "icon": "gear",
+                    "pages": [
+                      "/v7/api/client",
+                      "/v7/api/sandbox"
+                    ]
+                  },
+                  {
+                    "group": "Actions",
+                    "icon": "wand-magic-sparkles",
+                    "pages": [
+                      "/v7/api/ai"
+                    ]
+                  },
+                  {
+                    "group": "Methods",
+                    "icon": "code",
+                    "pages": [
+                      "/v7/api/find",
+                      "/v7/api/click",
+                      "/v7/api/type",
+                      "/v7/api/pressKeys",
+                      "/v7/api/scroll",
+                      "/v7/api/hover",
+                      "/v7/api/exec",
+                      "/v7/api/focusApplication",
+                      "/v7/api/assert"
+                    ]
+                  },
+                  {
+                    "group": "Reference",
+                    "icon": "book",
+                    "pages": [
+                      "/v7/api/elements",
+                      "/v7/api/assertions"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Guides",
+                "pages": [
+                  "/v7/guides/migration"
+                ]
+              }
             ]
           },
-          "/account/enterprise"
-        ]
-      },
-      {
-        "group": "Get Started",
-        "pages": [
-          "/overview/quickstart",
           {
-            "group": "CLI",
-            "icon": "terminal",
-            "pages": [
-              "/cli/overview",
+            "version": "6.X.X (YAML)",
+            "groups": [
               {
-                "group": "Commands",
-                "icon": "command",
+                "group": "Overview",
                 "pages": [
-                  "/interactive/explore",
-                  "/interactive/run",
-                  "/interactive/save"
+                  "/v6/overview/what-is-testdriver",
+                  {
+                    "group": "Concepts",
+                    "icon": "book",
+                    "pages": [
+                      "/v6/features/selectorless",
+                      "/v6/overview/comparison",
+                      "/v6/overview/performance",
+                      "/v6/overview/faq"
+                    ]
+                  },
+                  "/v6/account/enterprise"
+                ]
+              },
+              {
+                "group": "Get Started",
+                "pages": [
+                  "/v6/overview/quickstart",
+                  {
+                    "group": "CLI",
+                    "icon": "terminal",
+                    "pages": [
+                      "/v6/cli/overview",
+                      {
+                        "group": "Commands",
+                        "icon": "command",
+                        "pages": [
+                          "/v6/interactive/explore",
+                          "/v6/interactive/run",
+                          "/v6/interactive/save"
+                        ]
+                      }
+                    ]
+                  },
+                  "/v6/getting-started/self-hosting",
+                  "/v6/getting-started/playwright",
+                  "/v6/getting-started/vscode"
+                ]
+              },
+              {
+                "group": "Examples",
+                "pages": [
+                  {
+                    "group": "Apps",
+                    "icon": "laptop",
+                    "pages": [
+                      "apps/static-websites",
+                      "apps/desktop-apps",
+                      "apps/chrome-extensions",
+                      "apps/mobile-apps",
+                      "apps/tauri-apps"
+                    ]
+                  },
+                  {
+                    "group": "Scenarios",
+                    "icon": "computer-mouse",
+                    "pages": [
+                      "scenarios/ai-chatbot",
+                      "scenarios/cookie-banner",
+                      "scenarios/file-upload",
+                      "scenarios/form-filling",
+                      "scenarios/log-in",
+                      "scenarios/pdf-generation",
+                      "scenarios/spell-check"
+                    ]
+                  },
+                  {
+                    "group": "Build Systems",
+                    "icon": "helmet-safety",
+                    "pages": [
+                      "/v6/integrations/electron",
+                      "/v6/integrations/netlify",
+                      "/v6/integrations/vercel"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Guide",
+                "pages": [
+                  {
+                    "group": "Configuration",
+                    "icon": "desktop",
+                    "pages": [
+                      "/v6/guide/authentication",
+                      "/v6/guide/variables",
+                      "/v6/guide/lifecycle",
+                      "/v6/guide/dashcam",
+                      "/v6/guide/environment-variables",
+                      "/v6/action/ami"
+                    ]
+                  },
+                  {
+                    "group": "Writing",
+                    "icon": "pencil",
+                    "pages": [
+                      "/v6/features/generation",
+                      "/v6/guide/locating",
+                      "/v6/guide/waiting",
+                      "/v6/guide/assertions",
+                      "/v6/guide/code",
+                      "/v6/features/reusable-snippets",
+                      "/v6/guide/protips"
+                    ]
+                  },
+                  {
+                    "group": "Importing",
+                    "icon": "file-import",
+                    "pages": [
+                      "/v6/importing/csv",
+                      "/v6/importing/gherkin",
+                      "/v6/importing/jira",
+                      "/v6/importing/testrail"
+                    ]
+                  },
+                  {
+                    "group": "Running",
+                    "icon": "play",
+                    "pages": [
+                      "/v6/getting-started/running",
+                      "/v6/getting-started/ci",
+                      "/v6/features/parallel-testing",
+                      "/v6/action/performance",
+                      "/v6/action/secrets"
+                    ]
+                  },
+                  {
+                    "group": "Maintaining",
+                    "icon": "wrench",
+                    "pages": ["/v6/getting-started/editing", "/v6/features/auto-healing"]
+                  },
+                  {
+                    "group": "Reporting",
+                    "icon": "chart-simple",
+                    "pages": ["exporting/junit", "/v6/bugs/jira"]
+                  }
+                ]
+              },
+              {
+                "group": "Reference",
+                "pages": [
+                  {
+                    "group": "YAML",
+                    "icon": "file-code",
+                    "pages": [
+                      "/v6/commands/assert",
+                      "/v6/commands/exec",
+                      "/v6/commands/focus-application",
+                      "/v6/commands/hover-image",
+                      "/v6/commands/hover-text",
+                      "/v6/commands/if",
+                      "/v6/commands/match-image",
+                      "/v6/commands/press-keys",
+                      "/v6/commands/remember",
+                      "/v6/commands/run",
+                      "/v6/commands/scroll",
+                      "/v6/commands/scroll-until-image",
+                      "/v6/commands/scroll-until-text",
+                      "/v6/commands/type",
+                      "/v6/commands/wait",
+                      "/v6/commands/wait-for-image",
+                      "/v6/commands/wait-for-text"
+                    ]
+                  }
                 ]
               }
             ]
-          },
-          "/getting-started/self-hosting",
-          "/getting-started/playwright",
-          "/getting-started/vscode"
+          }
         ]
       },
       {
-        "group": "Examples",
-        "pages": [
-          {
-            "group": "Apps",
-            "icon": "laptop",
-            "pages": [
-              "apps/static-websites",
-              "apps/desktop-apps",
-              "apps/chrome-extensions",
-              "apps/mobile-apps",
-              "apps/tauri-apps"
-            ]
-          },
-          {
-            "group": "Scenarios",
-            "icon": "computer-mouse",
-            "pages": [
-              "scenarios/ai-chatbot",
-              "scenarios/cookie-banner",
-              "scenarios/file-upload",
-              "scenarios/form-filling",
-              "scenarios/log-in",
-              "scenarios/pdf-generation",
-              "scenarios/spell-check"
-            ]
-          },
-          {
-            "group": "Build Systems",
-            "icon": "helmet-safety",
-            "pages": [
-              "/integrations/electron",
-              "/integrations/netlify",
-              "/integrations/vercel"
-            ]
-          }
-        ]
+        "tab": "Playwright SDK",
+        "pages": ["v7/playwright"]
       },
       {
-        "group": "Guide",
-        "pages": [
-          {
-            "group": "Configuration",
-            "icon": "desktop",
-            "pages": [
-              "/guide/authentication",
-              "/guide/variables",
-              "/guide/lifecycle",
-              "/guide/dashcam",
-              "/guide/environment-variables",
-              "/action/ami"
-            ]
-          },
-          {
-            "group": "Writing",
-            "icon": "pencil",
-            "pages": [
-              "/features/generation",
-              "/guide/locating",
-              "/guide/waiting",
-              "/guide/assertions",
-              "/guide/code",
-              "/features/reusable-snippets",
-              "/guide/protips"
-            ]
-          },
-          {
-            "group": "Importing",
-            "icon": "file-import",
-            "pages": [
-              "/importing/csv",
-              "/importing/gherkin",
-              "/importing/jira",
-              "/importing/testrail"
-            ]
-          },
-          {
-            "group": "Running",
-            "icon": "play",
-            "pages": [
-              "/getting-started/running",
-              "/getting-started/ci",
-              "/features/parallel-testing",
-              "/action/performance",
-              "/action/secrets"
-            ]
-          },
-          {
-            "group": "Maintaining",
-            "icon": "wrench",
-            "pages": ["/getting-started/editing", "/features/auto-healing"]
-          },
-          {
-            "group": "Reporting",
-            "icon": "chart-simple",
-            "pages": ["exporting/junit", "/bugs/jira"]
-          }
-        ]
+        "tab": "Playwright Studio"
       },
       {
-        "group": "Reference",
-        "pages": [
-          {
-            "group": "YAML",
-            "icon": "file-code",
-            "pages": [
-              "/commands/assert",
-              "/commands/exec",
-              "/commands/focus-application",
-              "/commands/hover-image",
-              "/commands/hover-text",
-              "/commands/if",
-              "/commands/match-image",
-              "/commands/press-keys",
-              "/commands/remember",
-              "/commands/run",
-              "/commands/scroll",
-              "/commands/scroll-until-image",
-              "/commands/scroll-until-text",
-              "/commands/type",
-              "/commands/wait",
-              "/commands/wait-for-image",
-              "/commands/wait-for-text"
-            ]
-          }
-        ]
+        "tab": "Dashcam CLI"
       }
     ]
   },

package/docs/sdk-browser-rendering.md

@@ -0,0 +1,167 @@
+# SDK Browser Rendering Feature
+
+## Overview
+
+The TestDriver SDK now supports automatic browser rendering of the sandbox environment, matching the behavior of the existing agent CLI. When connecting to a sandbox, the SDK will automatically open a browser window showing the live VNC session, allowing you to watch test execution in real-time.
+
+## Changes Made
+
+### 1. SDK Core (`sdk.js`)
+
+#### Added Dependencies
+- Imported `createDebuggerProcess` from `./agent/lib/debugger.js` to enable the debugger server
+
+#### New Instance Variables
+- `debuggerProcess`: Reference to the debugger server process
+- `debuggerUrl`: URL of the debugger web interface
+
+#### Enhanced `connect()` Method
+- Automatically starts the debugger server when connecting (unless in headless mode)
+- Calls `_renderSandbox()` after successful connection to open the browser window
+- Supports new `headless` option to disable browser rendering
+
+#### New Methods
+
+**`_renderSandbox(instance)`**
+- Constructs the VNC URL from the sandbox instance details
+- Creates encoded data payload for the debugger
+- Emits the `show-window` event with the debugger URL
+
+**`_openBrowser(url)`**
+- Uses the `open` npm package to launch the default browser
+- Handles errors gracefully with fallback to manual URL copy
+- Uses dynamic import for ES module compatibility
+
+#### Enhanced `_setupLogging()` Method
+- Added event listener for `show-window` events
+- Automatically opens browser when event is emitted
+- Respects CI mode (prints view-only URL instead of opening browser)
+
+### 2. Documentation Updates
+
+#### SDK README (`SDK_README.md`)
+- Updated `connect()` method documentation
+- Added `headless` parameter description
+- Added note about automatic browser rendering behavior
+- Provided examples for both headless and non-headless modes
+
+### 3. Examples
+
+#### `examples/sdk-with-browser.js`
+- Demonstrates default behavior with browser rendering
+- Shows how to use the SDK with visual feedback
+- Includes detailed console output explaining what's happening
+
+#### `examples/sdk-headless.js`
+- Demonstrates headless mode for CI/CD environments
+- Shows how to disable browser rendering
+- Useful for automated testing scenarios
+
+### 4. Tests
+
+#### `testdriver/acceptance-sdk/sandbox-render.test.mjs`
+- Verifies that the `show-window` event is emitted
+- Tests basic interaction with the rendered sandbox
+- Includes timeout handling for sandbox creation
+
+## How It Works
+
+1. **Connection Phase**
+   - When `connect()` is called without `headless: true`
+   - The debugger server is started on port 3000 (by default)
+   - The sandbox is created/connected as usual
+
+2. **Rendering Phase**
+   - After successful connection, `_renderSandbox()` is called
+   - It constructs the VNC URL: `http://{instance.ip}:{vncPort}/vnc_lite.html?token=V3b8wG9`
+   - Creates data payload with resolution, URL, and token
+   - Builds debugger URL: `{debuggerUrl}?data={encodedData}`
+
+3. **Browser Opening**
+   - The `show-window` event is emitted with the debugger URL
+   - The event listener in `_setupLogging()` catches it
+   - The `_openBrowser()` method is called
+   - Default browser opens to the debugger interface
+   - User can watch live test execution
+
+## Usage Examples
+
+### Default Behavior (Browser Opens)
+
+```javascript
+const TestDriver = require('testdriverai');
+
+const client = new TestDriver(process.env.TD_API_KEY, {
+  logging: true
+});
+
+await client.auth();
+await client.connect(); // Browser opens automatically
+
+await client.hoverText('Submit');
+await client.click();
+```
+
+### Headless Mode (No Browser)
+
+```javascript
+const TestDriver = require('testdriverai');
+
+const client = new TestDriver(process.env.TD_API_KEY, {
+  logging: true
+});
+
+await client.auth();
+await client.connect({ headless: true }); // No browser
+
+await client.hoverText('Submit');
+await client.click();
+```
+
+### CI/CD Mode
+
+When `CI` environment variable is set or `config.CI` is true, the SDK will:
+- Print the view-only URL instead of opening a browser
+- Allow monitoring without interrupting the test flow
+
+## Benefits
+
+1. **Visual Feedback**: Developers can watch tests execute in real-time
+2. **Debugging**: Easier to understand test failures by seeing what's happening
+3. **Consistency**: Matches the behavior of the CLI tool
+4. **Flexibility**: Can be disabled for CI/CD with `headless: true`
+5. **No Code Changes**: Existing SDK code continues to work (default behavior adds browser)
+
+## Compatibility
+
+- Works on macOS, Linux, and Windows
+- Requires the `open` npm package (already a dependency)
+- Debugger server starts automatically when needed
+- Falls back gracefully if browser can't be opened (prints URL)
+
+## Testing
+
+Run the test to verify functionality:
+
+```bash
+TD_API_KEY=your_key npx vitest run testdriver/acceptance-sdk/sandbox-render.test.mjs
+```
+
+Or try the examples:
+
+```bash
+# With browser rendering
+TD_API_KEY=your_key node examples/sdk-with-browser.js
+
+# Headless mode
+TD_API_KEY=your_key node examples/sdk-headless.js
+```
+
+## Future Enhancements
+
+Potential improvements:
+- Allow custom debugger port configuration
+- Support for multiple concurrent sandbox windows
+- Option to disable debugger server entirely
+- Custom browser selection
+- Headless mode detection based on environment