testdriverai 7.9.70-test → 7.9.71-test

package/docs/_data/examples-manifest.schema.json

@@ -14,8 +14,18 @@
         "properties": {
           "url": {
             "type": "string",
-            "description": "Full URL to the test run (without ?embed=true)",
-            "pattern": "^https://console\\.testdriver\\.ai/runs/.+"
+            "description": "Full URL to the test run (legacy source for testcase ID)",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/runs/.+"
+          },
+          "replayUrl": {
+            "type": "string",
+            "description": "Public replay URL with share key",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/replay/.+"
+          },
+          "embedUrl": {
+            "type": "string",
+            "description": "Public replay embed URL used by docs iframes",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/replay/.+"
           },
           "lastUpdated": {
             "type": "string",

package/docs/_scripts/extract-example-urls.js

@@ -15,6 +15,19 @@ const path = require("path");
 
 const MANIFEST_PATH = path.join(__dirname, "../_data/examples-manifest.json");
 
+function deriveEmbedUrlFromReplayUrl(replayUrl) {
+  if (!replayUrl) return null;
+  try {
+    const url = new URL(replayUrl);
+    if (!url.pathname.includes("/replay/")) return null;
+    if (!url.searchParams.get("share")) return null;
+    url.searchParams.set("embed", "true");
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
 // Parse command line arguments
 function parseArgs() {
   const args = process.argv.slice(2);
@@ -81,12 +94,16 @@ function processResultsDir(resultsDir) {
         const result = JSON.parse(content);
         const testFileName = path.basename(result.test?.file || result.testFile || entry.name);
         const url = result.urls?.testRun || result.testRunLink;
+        const replayUrl = result.replay?.url || result.replayUrl || null;
+        const embedUrl = result.replay?.embedUrl || deriveEmbedUrlFromReplayUrl(replayUrl);
 
-        if (!url) continue;
+        if (!url && !embedUrl) continue;
 
         const isNew = !manifest.examples[testFileName];
         manifest.examples[testFileName] = {
-          url: url,
+          url: url || manifest.examples[testFileName]?.url || null,
+          ...(replayUrl ? { replayUrl } : {}),
+          ...(embedUrl ? { embedUrl } : {}),
           lastUpdated: result.date || new Date().toISOString(),
         };
 
@@ -96,7 +113,8 @@ function processResultsDir(resultsDir) {
           stats.updated++;
         }
 
-        console.log(`${isNew ? "➕" : "🔄"} ${testFileName}: ${url}`);
+        const displayUrl = embedUrl || url || "(no URL)";
+        console.log(`${isNew ? "➕" : "🔄"} ${testFileName}: ${displayUrl}`);
       } catch (err) {
         console.warn(`⚠️  Failed to read ${jsonFile}: ${err.message}`);
       }

package/docs/_scripts/generate-examples.js

@@ -302,23 +302,48 @@ function apiRootFromConsoleUrl(sourceUrl) {
   }
 }
 
-// Generate replay URL from testcase ID
-// sourceUrl is the manifest URL used to infer the correct API environment
-function generateReplayUrl(testcaseId, sourceUrl) {
-  // Use the API replay endpoint which handles the redirect with embed=true
-  const apiRoot = apiRootFromConsoleUrl(sourceUrl) || process.env.TD_API_ROOT || 'https://api.testdriver.ai';
+function normalizeEmbedUrl(rawUrl) {
+  if (!rawUrl) return null;
+  try {
+    const url = new URL(rawUrl);
+    if (!url.pathname.includes('/replay/')) return null;
+    if (!url.searchParams.get('share')) return null;
+    url.searchParams.set('embed', 'true');
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the best embed URL for docs:
+// 1) explicit embedUrl from manifest (preferred)
+// 2) replayUrl in manifest (converted to embed=true)
+// 3) legacy run URL via testcase replay redirect endpoint
+function resolveReplayEmbedUrl(manifestEntry) {
+  const directEmbed = normalizeEmbedUrl(manifestEntry?.embedUrl);
+  if (directEmbed) return directEmbed;
+
+  const replayEmbed = normalizeEmbedUrl(manifestEntry?.replayUrl);
+  if (replayEmbed) return replayEmbed;
+
+  const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
+  if (!testcaseId) return null;
+
+  const apiRoot = apiRootFromConsoleUrl(manifestEntry?.url) || process.env.TD_API_ROOT || 'https://api.testdriver.ai';
   return `${apiRoot}/api/v1/testdriver/testcase/${testcaseId}/replay`;
 }
 
 // Update existing MDX file by finding the marker comment and replacing the iframe
-function updateExistingMDX(existingContent, filename, testcaseId, sourceUrl) {
+function updateExistingMDX(existingContent, filename, replayEmbedUrl) {
   const marker = `{/* ${filename} output */}`;
   
   if (!existingContent.includes(marker)) {
     return null; // Marker not found, can't update
   }
   
-  const replayUrl = generateReplayUrl(testcaseId, sourceUrl);
+  if (!replayEmbedUrl) {
+    return null;
+  }
   
   // Pattern to match the marker followed by the iframe tag
   const escapedFilename = filename.replace(/\./g, '\\.');
@@ -327,7 +352,7 @@ function updateExistingMDX(existingContent, filename, testcaseId, sourceUrl) {
     's'
   );
   
-  const replacement = `$1<iframe \n  src="${replayUrl}"$2/>`;
+  const replacement = `$1<iframe \n  src="${replayEmbedUrl}"$2/>`;
   const updated = existingContent.replace(pattern, replacement);
   
   if (updated === existingContent) {
@@ -363,7 +388,7 @@ function generateMDX(testMeta, manifest, description) {
   const sidebarTitle = generateSidebarTitle(testMeta.filename);
   const shortDescription = generateShortDescription(testMeta);
   const manifestEntry = manifest.examples[testMeta.filename];
-  const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
+  const replayEmbedUrl = resolveReplayEmbedUrl(manifestEntry);
 
   let mdx = `---
 title: "${title}"
@@ -379,15 +404,14 @@ ${description}
 `;
 
   // Add Live Test Run section if URL exists
-  if (testcaseId) {
-    const replayUrl = generateReplayUrl(testcaseId, manifestEntry?.url);
+  if (replayEmbedUrl) {
     mdx += `## Live Test Run
 
 Watch this test execute in a real sandbox environment:
 
 {/* ${testMeta.filename} output */}
 <iframe 
-  src="${replayUrl}" 
+  src="${replayEmbedUrl}" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}
@@ -584,9 +608,9 @@ async function main() {
 
         // Update iframe URL if manifest entry exists
         const manifestEntry = manifest.examples[testMeta.filename];
-        const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
-        if (testcaseId) {
-          const iframeUpdated = updateExistingMDX(content, testMeta.filename, testcaseId, manifestEntry.url);
+        const replayEmbedUrl = resolveReplayEmbedUrl(manifestEntry);
+        if (replayEmbedUrl) {
+          const iframeUpdated = updateExistingMDX(content, testMeta.filename, replayEmbedUrl);
           if (iframeUpdated && iframeUpdated !== content) {
             content = iframeUpdated;
             changed = true;

package/docs/v7/customizing-devices.mdx

@@ -283,9 +283,9 @@ const testdriver = TestDriver(context, {
 });
 ```
 
-### Reconnecting to Existing Sandbox
+### Connecting to an Existing Sandbox
 
-Speed up test development by reconnecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
+Speed up test development by connecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
 
 Split your test into two files: one for known-good steps that set up the desired state, and another for work-in-progress steps you want to debug.
 
@@ -298,8 +298,10 @@ const testdriver = TestDriver(context, {
 ```javascript work-in-progress.test.mjs
 // Second test file: experiment.test.mjs (run within keepAlive window)
 const testdriver = TestDriver(context, {
-  reconnect: true,  // Reconnect to existing sandbox
+  keepAlive: 60000,
 });
+
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
 ```
 
 Then, you can run both tests in sequence:
@@ -315,5 +317,5 @@ vitest run work-in-progress.test.mjs
 ```
 
 <Warning>
-  Reconnect only works if run within the `keepAlive` window of the previous test.
+  Connecting to the same machine only works if run within the `keepAlive` window of the previous test.
 </Warning>

package/docs/v7/machine-setup.mdx

@@ -102,23 +102,25 @@ await testdriver.provision.chrome({ url: "https://example.com" });
 
 When this test finishes, the sandbox stays running for 30 minutes instead of being terminated immediately.
 
-### Step 2 — Reconnect in subsequent runs
+### Step 2 — Connect in subsequent runs
 
 ```javascript
 // second.test.mjs
 const testdriver = TestDriver(context, {
   os: "windows",
-  reconnect: true, // reads last sandbox ID from disk, skips provisioning
+  keepAlive: 30 * 60 * 1000,
 });
 
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
+
 // provision.chrome() is automatically skipped — Chrome is already open
 await testdriver.find("Sign In button").click();
 ```
 
-When `reconnect: true` is set:
-- The SDK reads the last sandbox ID from a local file via `getLastSandboxId()`
-- All `provision.*` calls are silently skipped since the application is already running
-- An error is thrown if no previous sandbox ID is found
+When connecting to an existing sandbox ID:
+- You reuse a specific running machine directly
+- You can continue from the app state created in an earlier test run
+- You should run within the previous test's `keepAlive` window
 
 <Tip>
   You can also supply a sandbox ID directly: `await testdriver.connect({ sandboxId: "sandbox-abc123" })`. Use `testdriver.getLastSandboxId()` to retrieve the ID of the last sandbox for scripting purposes.

package/docs/v7/provision.mdx

@@ -16,10 +16,6 @@ Access provision methods via `testdriver.provision.*`:
 await testdriver.provision.chrome({ url: 'https://example.com' });
 ```
 
-<Note>
-  When `reconnect: true` is set on the client, **all provision methods are skipped** since the application is assumed to already be running.
-</Note>
-
 ## Methods
 
 ### chrome()
@@ -236,22 +232,6 @@ await testdriver.provision.dashcam({
 });
 ```
 
-## Reconnect Behavior
-
-When `reconnect: true` is set on the client, all provision methods are wrapped in a Proxy that intercepts calls and skips them silently. This is because when reconnecting to an existing sandbox, the applications are already running.
-
-```javascript
-const testdriver = new TestDriver({
-  reconnect: true,
-});
-
-await testdriver.ready();
-
-// These calls are silently skipped:
-await testdriver.provision.chrome({ url: 'https://example.com' });
-await testdriver.provision.dashcam();
-```
-
 ## Types
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.9.70-test",
+  "version": "7.9.71-test",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",