@testdriverai/mcp 7.9.96-canary → 7.9.97-canary

package/docs/v7/client.mdx

@@ -54,7 +54,11 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="reconnect" type="boolean" default="false">
-      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Machine Setup guide](/v7/machine-setup#keeping-machines-alive-between-runs).
+    </ParamField>
+
+    <ParamField path="sandboxId" type="string">
+      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
     </ParamField>
     
     <ParamField path="preview" type="string" default="browser">

package/docs/v7/machine-setup.mdx

@@ -87,6 +87,16 @@ const testdriver = TestDriver(context, {
 
 Windows (and Linux) cold starts can be expensive if you're iterating quickly. Use `keepAlive` + `reconnect` to reuse the same VM across multiple test runs.
 
+### How it works
+
+Every time the SDK successfully connects to a sandbox, it records the sandbox id in `.testdriver/last-sandbox` inside your project directory. The next test that opts in with `reconnect: true` reads that file and reattaches automatically — no manual id tracking required.
+
+Provision calls (`testdriver.provision.chrome(...)`, `vscode(...)`, etc.) are **skipped** when reconnecting, because the application is already running inside the sandbox from the previous run.
+
+<Note>
+  `.testdriver/last-sandbox` is already covered by the default TestDriver `.gitignore`. Don't commit it.
+</Note>
+
 ### Step 1 — Start the machine with a long `keepAlive`
 
 ```javascript
@@ -102,30 +112,87 @@ 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 — Connect in subsequent runs
+### Step 2 — Reattach automatically with `reconnect: true`
 
 ```javascript
 // second.test.mjs
 const testdriver = TestDriver(context, {
   os: "windows",
+  reconnect: true,            // ← reads .testdriver/last-sandbox
   keepAlive: 30 * 60 * 1000,
 });
 
-await testdriver.connect({ sandboxId: "sandbox-abc123" });
-
-// provision.chrome() is automatically skipped — Chrome is already open
+// No provision call — Chrome is already open from the previous run.
 await testdriver.find("Sign In button").click();
 ```
 
-When connecting to an existing sandbox ID:
+### Step 2 (alternative) — Reattach to an explicit id
+
+If you need to pin to a specific sandbox (CI matrix, multiple chains in parallel, etc.) pass the id directly:
+
+```javascript
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
+```
+
+When reattaching to a sandbox:
 - 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
+- You continue from the app state created in the earlier run
+- You must 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.
+  Use `testdriver.getLastSandboxId()` to read the recorded sandbox id (and optional metadata) for scripting purposes.
 </Tip>
 
+### Chaining describe blocks within one test file
+
+A common pattern is to break a long flow into focused `describe` blocks that share one sandbox — the first block provisions and signs in, later blocks reconnect and continue:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+const KEEP_ALIVE_MS = 5 * 60 * 1000;
+
+describe("step 1 — log in", () => {
+  it("signs in and lands on the dashboard", async (context) => {
+    const testdriver = TestDriver(context, { keepAlive: KEEP_ALIVE_MS });
+    await testdriver.provision.chrome({ url: "https://example.com/login" });
+    await testdriver.find("username input").click();
+    await testdriver.type("standard_user");
+    await testdriver.pressKeys(["tab"]);
+    await testdriver.type("secret_sauce", { secret: true });
+    await testdriver.pressKeys(["enter"]);
+    expect(await testdriver.assert("the dashboard is visible")).toBeTruthy();
+  });
+});
+
+describe("step 2 — add to cart", () => {
+  it("reuses the logged-in sandbox", async (context) => {
+    const testdriver = TestDriver(context, {
+      reconnect: true,           // ← skip provisioning, reattach
+      keepAlive: KEEP_ALIVE_MS,
+    });
+    await testdriver.find("Add to cart").click();
+    await testdriver.find("cart icon").click();
+    expect(await testdriver.assert("the cart has an item")).toBeTruthy();
+  });
+});
+
+describe("step 3 — check out", () => {
+  it("continues from the cart state", async (context) => {
+    const testdriver = TestDriver(context, { reconnect: true, keepAlive: 30_000 });
+    await testdriver.find("Checkout").click();
+    expect(await testdriver.assert("the checkout form is visible")).toBeTruthy();
+  });
+});
+```
+
+A runnable copy of this pattern lives at [`examples/reconnect-sequential.test.mjs`](https://github.com/testdriverai/mono/blob/main/sdk/examples/reconnect-sequential.test.mjs).
+
+<Warning>
+  Vitest runs **test files** in parallel by default. Within a single file, `describe`/`it` blocks run in source order, so reconnect chaining works as written. To chain across multiple files, run them sequentially (e.g. `vitest run --sequence.concurrent=false` or place them in a single project pool with workers set to 1).
+</Warning>
+
 ### How `keepAlive` works
 
 `keepAlive` is a duration in milliseconds. After the SDK disconnects, the server keeps the VM running for that long before terminating it. The default is `60000` (1 minute). Note: `keepAlive: 0` currently falls back to the default disconnect grace period rather than terminating immediately, so use a positive duration when you want to control the grace window explicitly.

package/examples/config.mjs

@@ -1,4 +1,5 @@
 export const getDefaults = (context) => ({
   ip: context.ip || process.env.TD_IP,
   preview: 'web',
+  cache: 'false'
 });

package/lib/core/Dashcam.js

@@ -150,6 +150,34 @@ class Dashcam {
 
   }
 
+  /**
+   * Workaround for dashcam <1.5.0: webLogsDaemon.js writes its state to a
+   * `.dashcam` directory relative to process.cwd(). When launched by the
+   * runner, cwd is /usr/lib/node_modules/@testdriverai/runner (root-owned),
+   * so the daemon can't mkdir its state dir as user `user` and silently
+   * dies — recordings never start (or `dashcam logs --add` fails with EACCES).
+   * Pre-create world-writable .dashcam dirs at both the current cwd and the
+   * known global-install path so the daemon survives regardless of which path
+   * dashcam ends up using. Must run before ANY dashcam invocation, not just
+   * auth(), because addWebLog() is called before start()/auth() in provision.
+   * TODO: remove once dashcam >=1.5.0 (which uses $HOME) is bundled.
+   * @private
+   */
+  async _ensureDashcamStateDirs() {
+    if (this.client.os === "windows") return;
+    if (!this._dashcamDirsReady) {
+      this._dashcamDirsReady = this.client.exec(
+        this._getShell(),
+        `sudo mkdir -p "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
+          `sudo chmod 0777 "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
+          `true`,
+        10000,
+        process.env.TD_DEBUG == "true" ? false : true,
+      );
+    }
+    await this._dashcamDirsReady;
+  }
+
   /**
    * Authenticate dashcam with API key
    * @param {string} [apiKey] - Override API key
@@ -174,23 +202,7 @@ class Dashcam {
       this._log("debug", "Auth output:", authOutput);
     } else {
       // Linux/Mac authentication with TD_API_ROOT
-
-      // Workaround for dashcam <1.5.0: webLogsDaemon.js writes its state to a
-      // `.dashcam` directory relative to process.cwd(). When launched by the
-      // runner, cwd is /usr/lib/node_modules/@testdriverai/runner (root-owned),
-      // so the daemon can't mkdir its state dir as user `user` and silently
-      // dies — recordings never start. Pre-create world-writable .dashcam dirs
-      // at both the current cwd and the known global-install path so the
-      // daemon survives regardless of which path dashcam ends up using.
-      // TODO: remove once dashcam >=1.5.0 (which uses $HOME) is bundled.
-      await this.client.exec(
-        shell,
-        `sudo mkdir -p "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
-          `sudo chmod 0777 "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
-          `true`,
-        10000,
-        process.env.TD_DEBUG == "true" ? false : true,
-      );
+      await this._ensureDashcamStateDirs();
 
       const authOutput = await this.client.exec(
         shell,
@@ -233,6 +245,7 @@ class Dashcam {
       );
       this._log("debug", "Add log tracking output:", addLogOutput);
     } else {
+      await this._ensureDashcamStateDirs();
       // Create log file
       await this.client.exec(
         shell,
@@ -272,6 +285,7 @@ class Dashcam {
       );
       this._log("debug", "Add application log tracking output:", addLogOutput);
     } else {
+      await this._ensureDashcamStateDirs();
       const addLogOutput = await this.client.exec(
         shell,
         `TD_API_ROOT="${apiRoot}" dashcam logs --add --type=application --application="${application}" --name="${name}"`,
@@ -306,6 +320,7 @@ class Dashcam {
         this._log("warn", "Add web log tracking failed:", err.message);
       }
     } else {
+      await this._ensureDashcamStateDirs();
       const addLogOutput = await this.client.exec(
         shell,
         `TD_API_ROOT="${apiRoot}" dashcam logs --add --type=web --pattern="${pattern}" --name="${name}"`,
@@ -386,6 +401,7 @@ class Dashcam {
       this._log("debug", "Dashcam recording started");
     } else {
       // Linux/Mac with TD_API_ROOT
+      await this._ensureDashcamStateDirs();
       this._log("debug", "Starting dashcam recording on Linux/Mac...");
       const dashcamPath = await this._getDashcamPath();
       const titleArg = this.title

package/package.json

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

package/sdk.d.ts

@@ -277,8 +277,10 @@ export interface TestDriverOptions {
   e2bTemplateId?: string;
   /** Cache key for element finding operations. If provided, enables caching tied to this key */
   cacheKey?: string;
-  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */
+  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Looks up the sandbox id from `.testdriver/last-sandbox` if `sandboxId` is not also provided. */
   reconnect?: boolean;
+  /** Explicit sandbox id to reconnect to. Implies `newSandbox: false` unless explicitly overridden. */
+  sandboxId?: string;
   /** Enable/disable Dashcam video recording (default: true) */
   dashcam?: boolean;
   /**
@@ -1042,15 +1044,15 @@ export default class TestDriverSDK {
   disconnect(): Promise<void>;
 
   /**
-   * Get the last sandbox info from the stored file
+   * Get info about the most recently provisioned sandbox (from this SDK instance
+   * if connected, otherwise read from `.testdriver/last-sandbox`).
    * @returns Last sandbox info or null if not found
    */
   getLastSandboxId(): {
-    sandboxId: string | null;
-    os: "windows" | "linux";
-    ami: string | null;
-    instanceType: string | null;
-    timestamp: string | null;
+    sandboxId: string;
+    os?: "windows" | "linux";
+    e2bTemplateId?: string | null;
+    createdAt?: number;
   } | null;
 
   // Element Finding API

package/sdk.js

@@ -1510,6 +1510,21 @@ class TestDriverSDK {
     this.reconnect =
       options.reconnect !== undefined ? options.reconnect : false;
 
+    // Explicit sandbox id to reconnect to (overrides last-sandbox file)
+    this.sandboxId = options.sandboxId || null;
+
+    // When reconnect is requested, an explicit sandboxId implies newSandbox=false.
+    // If reconnect:true but no sandboxId given, try to load from .testdriver/last-sandbox.
+    if (this.reconnect && !this.sandboxId) {
+      const last = TestDriverSDK._readLastSandbox();
+      if (last && last.sandboxId) {
+        this.sandboxId = last.sandboxId;
+      }
+    }
+    if (this.sandboxId && options.newSandbox === undefined) {
+      this.newSandbox = false;
+    }
+
     // Store keepAlive preference from options
     this.keepAlive =
       options.keepAlive !== undefined ? options.keepAlive : undefined;
@@ -2070,6 +2085,9 @@ CAPTCHA_SOLVER_EOF`,
     // Set agent properties for buildEnv to use
     if (connectOptions.sandboxId) {
       this.agent.sandboxId = connectOptions.sandboxId;
+    } else if (this.sandboxId) {
+      // Constructor-provided sandboxId (explicit or loaded from .testdriver/last-sandbox)
+      this.agent.sandboxId = this.sandboxId;
     }
     // Use IP from connectOptions if provided, otherwise fall back to constructor IP
     if (connectOptions.ip !== undefined) {
@@ -2168,6 +2186,20 @@ CAPTCHA_SOLVER_EOF`,
       sandboxId: this.instance?.instanceId,
     });
 
+    // Persist the active sandbox id so a later run with `reconnect: true`
+    // can reattach without the caller having to thread the id through.
+    const activeSandboxId =
+      this.instance?.sandboxId || this.instance?.instanceId || null;
+    if (activeSandboxId) {
+      this.sandboxId = activeSandboxId;
+      TestDriverSDK._writeLastSandbox({
+        sandboxId: activeSandboxId,
+        os: this.os,
+        e2bTemplateId: this.e2bTemplateId || null,
+        createdAt: Date.now(),
+      });
+    }
+
     return this.instance;
   }
 
@@ -3645,6 +3677,52 @@ CAPTCHA_SOLVER_EOF`,
   clearLogs() {
     this._logBuffer = [];
   }
+
+  /**
+   * Return info about the most recently provisioned sandbox (from this process
+   * or persisted from a previous run via .testdriver/last-sandbox).
+   * @returns {{ sandboxId: string, os?: string, e2bTemplateId?: string|null, createdAt?: number } | null}
+   */
+  getLastSandboxId() {
+    if (this.sandboxId) {
+      return {
+        sandboxId: this.sandboxId,
+        os: this.os,
+        e2bTemplateId: this.e2bTemplateId || null,
+      };
+    }
+    return TestDriverSDK._readLastSandbox();
+  }
+
+  /** @private */
+  static _lastSandboxPath() {
+    return path.join(process.cwd(), ".testdriver", "last-sandbox");
+  }
+
+  /** @private */
+  static _readLastSandbox() {
+    try {
+      const p = TestDriverSDK._lastSandboxPath();
+      if (!fs.existsSync(p)) return null;
+      const raw = fs.readFileSync(p, "utf8");
+      const data = JSON.parse(raw);
+      if (!data || !data.sandboxId) return null;
+      return data;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /** @private */
+  static _writeLastSandbox(data) {
+    try {
+      const p = TestDriverSDK._lastSandboxPath();
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.writeFileSync(p, JSON.stringify(data, null, 2));
+    } catch (_) {
+      // Best-effort — don't fail the test if we can't persist.
+    }
+  }
 }
 
 // Expose SDK version as a static property for use by vitest hooks/plugins