@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/wait.mdx

@@ -1,52 +1,54 @@
 ---
-title: "wait"
+title: "wait()"
 sidebarTitle: "wait"
-description: "Pause the execution of the script for a specified duration."
+description: "Pause the test for a fixed number of milliseconds."
 icon: "clock"
-"mode": "wide"
+mode: "wide"
 ---
 
-## Description
+Pause the test for a fixed time, for example while an animation finishes:
 
-The `wait` method stops the test for a number of milliseconds. Then it continues. Use this to add delays between actions, to wait for animations to complete, or to let state changes become stable.
+```javascript
+await testdriver.find('Menu toggle').click();
+await testdriver.wait(1000);
+```
 
-## Syntax
+To wait for an element to appear, don't use `wait()`. Use [`find()`](/find) with a `timeout`, which continues as soon as the element shows up:
 
 ```javascript
-await testdriver.wait(timeout);
+await testdriver.find('Order confirmation message', { timeout: 30000 });
+```
+
+## Signature
+
+```typescript
+testdriver.wait(timeout?: number): Promise<void>
 ```
 
-## Arguments
+## Parameters
 
-| Argument  | Type     | Default | Description                           |
-| --------- | -------- | ------- | ------------------------------------- |
-| `timeout` | `number` | `3000`  | The duration in milliseconds to wait. |
+<ParamField path="timeout" type="number" default="3000">
+  How long to pause, in milliseconds.
+</ParamField>
 
 ## Examples
 
+### Let a transition finish
+
 ```javascript
-// Wait 2 seconds for an animation to complete
-await testdriver.find('submit button').click();
-await testdriver.wait(2000);
+await testdriver.find('Settings tab').click();
+await testdriver.wait(500);
+await testdriver.assert('the Settings panel is fully open');
+```
 
-// Wait 5 seconds
-await testdriver.wait(5000);
+### Pause for the default time
 
-// Wait with default timeout (3 seconds)
-await testdriver.wait();
+```javascript
+await testdriver.wait(); // 3 seconds
 ```
 
-## Best Practices
-
-- **Use it for simple delays**. Wait for animations, transitions, or state changes after an action.
-- **Do not use it to wait for an element**. If you wait for a specific element to show, use `find()` with a `timeout` option:
-  ```javascript
-  // ✅ Better for waiting for elements
-  const element = await testdriver.find('success message', { timeout: 30000 });
+## Related
 
-  // ❌ Don't do this for element waiting
-  await testdriver.wait(5000);
-  const element = await testdriver.find('success message');
-  ```
-- Do not use very long timeouts. This keeps the tests efficient.
-- Use it only when necessary. The TestDriver [redraw detection](/performing-actions#waiting-for-dynamic-content) waits automatically for the screen and the network to become stable after each action.
+- [find()](/find): wait for an element with a `timeout`
+- [Wait for a changing UI](/performing-actions#wait-for-a-changing-ui): choose the right way to wait
+- [Redraw detection](/redraw): wait for the screen to settle after each action

package/docs/what-is-testdriver.mdx

@@ -1,54 +1,102 @@
 ---
 title: "What is TestDriver?"
-description: "Reliably test your most difficult user flows"
+description: "TestDriver tests apps by seeing the screen and controlling a real machine, without selectors."
 icon: "circle-info"
 ---
 
-## The problem with usual test tools
+TestDriver is an end-to-end testing platform that tests your app the way a person uses it.
 
-Usual test tools such as Playwright test one web application. They use one browser tab and they use selectors.
+- It looks at the screen.
+- It finds elements from plain-language descriptions.
+- It controls a real machine with the mouse and keyboard.
 
-But selectors are frequently not reliable, or they are not available. This makes tests weak and not stable:
+It doesn't rely on CSS or XPath selectors. So it can test flows that selector-based tools can't reach, such as desktop apps, browser extensions, and content that changes every time it renders.
 
-| Challenge | Problem | Examples |
-|-----------|---------|----------|
-| **Teams that move quickly** | They change the UI structure frequently. This breaks the CSS and XPath selectors. | Agile teams, startups, vibe-coders |
-| **Dynamic content** | You cannot select it with selectors. | AI chatbots, PDFs, images, videos |
-| **Software that you do not own** | It can have no correct accessibility attributes. | Other websites, extensions, third-party applications |
-| **Workflows with more than one application** | You cannot test them with web-only tools. | Desktop apps, browser extensions, IDEs |
-| **Visual states** | You cannot make a check of them with code selectors. | Charts, graphs, videos, images, spelling errors, UI layout |
+## Where selector-based tests fall short
 
-## The TestDriver solution
+Tools such as Playwright and Cypress drive a single web page through its DOM. They locate elements with selectors.
 
-TestDriver is a complete test platform. It handles these conditions. It has a Javascript SDK, hosted infrastructure, and debug tools. These tools make it easy to write, run, and keep tests for your most difficult user flows.
+That works until a test needs something the DOM can't describe reliably:
 
-### Javascript SDK
+| Situation | Why selectors break down | Examples |
+| --- | --- | --- |
+| **A fast-changing UI** | Each redesign changes the markup and breaks CSS and XPath selectors. | Startups, teams shipping AI-generated code |
+| **Dynamic content** | Generated content has no stable structure to select. | AI chat responses, PDFs, images, video |
+| **Software you don't own** | Third-party markup often lacks stable IDs or accessibility attributes. | Other websites, embedded widgets, third-party apps |
+| **More than one application** | Web-only tools can't leave the browser tab. | Desktop apps, browser extensions, IDEs, installers |
+| **Visual state** | Whether something *looks* right isn't in the DOM. | Charts, layout, spelling, rendered media |
 
-This is an example of a TestDriver test. The test installs a production Chrome extension from the Chrome Web Store. Then it makes sure that the extension is in the extensions menu:
+## How TestDriver works
 
-```javascript Installing Loom from the Chrome Web Store
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+A TestDriver test is a [Vitest](https://vitest.dev) test. It runs against a cloud sandbox, a fresh Linux machine, or Windows on [Enterprise](https://testdriver.ai/enterprise/) plans.
 
-describe("Chrome Extension Test", () => {
-  const testdriver = TestDriver(context);
+Each step describes what a user would see or do:
 
-  // Launch Chrome with Loom loaded by its Chrome Web Store ID
-  await testdriver.provision.chromeExtension({
-    extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
-  });
+1. **[Provision](/provision)** launches the app under test in the sandbox, such as Chrome at a URL, a Chrome extension, VS Code, an Electron app, or a downloaded installer.
+2. **[Find](/locating-elements)** takes a description like `'Sign in button'` and uses AI vision to locate the matching element on screen.
+3. **[Act](/performing-actions)** clicks, types, scrolls, and presses keys on the real machine. The app receives the same input a person would produce.
+4. **[Assert](/making-assertions)** checks a plain-language statement about the screen, such as `'the cart shows one item'`.
+
+This test installs the Loom extension from the Chrome Web Store. It checks that Loom appears in Chrome's extensions menu, a flow that a DOM-only tool can't drive:
+
+```javascript tests/loom-extension.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Loom extension', () => {
+  it('appears in the Chrome extensions menu', async (context) => {
+    const testdriver = TestDriver(context);
 
-  // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-  const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
-  await extensionsButton.click();
+    // Launch Chrome with Loom installed by its Chrome Web Store ID
+    await testdriver.provision.chromeExtension({
+      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb',
+    });
 
-  // Look for Loom in the extensions menu
-  const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
-  expect(loomExtension.found()).toBeTruthy();
+    const extensionsButton = await testdriver.find('puzzle-piece extensions icon in the Chrome toolbar');
+    await extensionsButton.click();
+
+    const loomExtension = await testdriver.find('Loom in the extensions dropdown');
+    expect(loomExtension.found()).toBe(true);
+  });
 });
 ```
 
+To run this yourself, follow the [Quickstart](/quickstart).
+
+## What's included
+
+- **The SDK**, the `testdriverai` npm package. Use it in Vitest tests to provision apps, find elements, act, and assert.
+- **Cloud sandboxes** that run your tests on fresh Linux machines, or Windows on Enterprise plans. Enterprise customers can also [self-host](/self-hosted) them.
+- **Debugging tools**: screen recordings of every run, [screenshots](/debugging-with-screenshots), and [element caching](/caching) for faster, more stable repeat runs.
+- **[The TestDriver agent](/agent)**, which reviews your pull requests and writes and maintains tests from GitHub.
+
+## When to use TestDriver
+
+TestDriver is built for flows that are hard to cover any other way:
+
+- Multi-application workflows
+- Desktop software
+- Browser extensions
+- Third-party UIs
+- Visual checks
+
+Each step runs on a real machine and uses AI vision. So a TestDriver test takes longer per step than a test that talks to the DOM directly.
+
+If stable, selector-based tests already cover a flow, keep them. Use TestDriver for the parts they can't reach.
 
-<Tip>[vitest](https://vitest.dev/) is the preferred test runner for TestDriver.</Tip>
+## Related
 
-,
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Install TestDriver and run your first test.
+  </Card>
+  <Card title="Locate elements" icon="crosshairs" href="/locating-elements">
+    Write descriptions that find the right element reliably.
+  </Card>
+  <Card title="The TestDriver agent" icon="hand-horns" href="/agent">
+    Let the agent review pull requests and build tests from GitHub.
+  </Card>
+  <Card title="Hosted sandboxes" icon="cloud" href="/hosted">
+    Run tests on TestDriver's cloud infrastructure.
+  </Card>
+</CardGroup>

package/examples/{hover-text-with-description.test.mjs → add-to-cart.test.mjs}

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Hover Text With Description Test (Vitest)
- * Converted from: testdriver/acceptance/hover-text-with-description.yaml
+ * Logs in to the demo store, adds the TestDriver Hat to the cart, and
+ * asserts that the cart has an item.
  */
 
 import { describe, expect, it } from "vitest";
@@ -8,8 +8,8 @@ import { TestDriver } from "../lib/vitest/hooks.mjs";
 import { getDefaults } from "./config.mjs";
 
 /**
- * Perform login flow for SauceLabs demo app
- * @param {TestDriver} client - TestDriver client
+ * Log in to the TestDriver sandbox demo store.
+ * @param {object} client - TestDriver instance
  * @param {string} username - Username (default: 'standard_user')
  */
 async function performLogin(client, username = "standard_user") {
@@ -34,7 +34,6 @@ describe("Hover Text With Description Test", () => {
       url: "http://testdriver-sandbox.vercel.app/login",
     });
 
-    //
     // Perform login first
     await performLogin(testdriver);
 

package/examples/assert.test.mjs

@@ -1,6 +1,5 @@
 /**
- * TestDriver SDK - Assert Test (Vitest)
- * Converted from: testdriver/acceptance/assert.yaml
+ * Opens the TestDriver sandbox login page and asserts that it loaded.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,13 +11,12 @@ describe("Assert Test", () => {
     const testdriver = TestDriver(context, {
       ...getDefaults(context),
     });
-    
-    // provision.chrome() automatically calls ready() and starts dashcam
+
     await testdriver.provision.chrome({
       url: 'http://testdriver-sandbox.vercel.app/login',
     });
 
-    // Take a screenshot
+    // Save a screenshot to .testdriver/screenshots for debugging
     await testdriver.screenshot();
 
     // Assert the TestDriver.ai Sandbox login page is displayed
@@ -28,20 +26,5 @@ describe("Assert Test", () => {
 
     expect(result).toBeTruthy();
   });
-  // it("should assert the testdriver login page shows 2", async (context) => {
-  //   const testdriver = TestDriver(context);
-    
-  //   // provision.chrome() automatically calls ready() and starts dashcam
-  //   await testdriver.provision.chrome({
-  //     url: 'http://testdriver-sandbox.vercel.app/login',
-  //   });
-
-  //   // Assert the TestDriver.ai Sandbox login page is displayed
-  //   const result = await testdriver.assert(
-  //     "the TestDriver.ai Sandbox login page is displayed",
-  //   );
-
-  //   expect(result).toBeTruthy();
-  // });
 });
 

package/examples/{hover-text.test.mjs → click-button.test.mjs}

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Hover Text Test (Vitest)
- * Converted from: testdriver/acceptance/hover-text.yaml
+ * Clicks Sign In on an empty login form and asserts that a
+ * required-fields error appears.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,8 +12,7 @@ describe("Hover Text Test", () => {
     const testdriver = TestDriver(context, { ...getDefaults(context) });
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-    // Click on Sign In button using new find() API
-
+    // Submit the login form without filling it in
     const signInButton = await testdriver.find(
       "Sign In, black button below the password field",
     );

package/examples/{hover-image.test.mjs → click-icon.test.mjs}

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Hover Image Test (Vitest)
- * Converted from: testdriver/acceptance/hover-image.yaml
+ * Logs in to the demo store, clicks the shopping cart icon, and asserts
+ * that the cart is empty.
  */
 
 import { describe, expect, it } from "vitest";
@@ -8,8 +8,8 @@ import { TestDriver } from "../lib/vitest/hooks.mjs";
 import { getDefaults } from "./config.mjs";
 
 /**
- * Perform login flow for SauceLabs demo app
- * @param {import('../../sdk.js').default} client - TestDriver client instance
+ * Log in to the TestDriver sandbox demo store.
+ * @param {object} client - TestDriver instance
  * @param {string} username - Username (default: 'standard_user')
  */
 async function performLogin(client, username = "standard_user") {
@@ -29,8 +29,7 @@ async function performLogin(client, username = "standard_user") {
 describe("Hover Image Test", () => {
   it("should click on shopping cart icon and verify empty cart", async (context) => {
     const testdriver = TestDriver(context, { ...getDefaults(context) });
-    
-    // provision.chrome() automatically calls ready() and starts dashcam
+
     await testdriver.provision.chrome({
       url: 'http://testdriver-sandbox.vercel.app/login'
     });

package/examples/element-not-found.test.mjs

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Element Not Found Test
- * Tests that finding a non-existent element returns properly without timing out
+ * Searches for an element that isn't on screen and checks that find()
+ * returns an unfound element instead of throwing.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,8 +12,6 @@ describe("Element Not Found Test", () => {
     const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-    //
-
     // Try to find an element that definitely doesn't exist
     const element = await testdriver.find(
       "a purple unicorn dancing on the moon",
@@ -22,6 +20,6 @@ describe("Element Not Found Test", () => {
     // Should return an element that is not found
     expect(element.found()).toBe(false);
     expect(element.coordinates).toBeNull();
-  }); // 90 second timeout for the test (should complete much faster)
+  });
 });
 

package/examples/findall-coffee-icons.test.mjs

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - FindAll Coffee Icons Test
- * Loads a random icon grid and uses findAll() to locate and click all 4 coffee cup icons
+ * Loads a random icon grid and uses findAll() to locate and click every
+ * coffee cup icon on it.
  */
 
 import { describe, expect, it } from "vitest";
@@ -27,7 +27,7 @@ describe("FindAll Coffee Icons", () => {
       console.log(`  Icon ${i + 1}: (${icon.x}, ${icon.y}) center=(${icon.centerX}, ${icon.centerY})`);
     });
 
-    // Verify we found 3 or 4 coffee icons
+    // The grid has 4 coffee cups; allow one miss, matching the assertion below
     expect(coffeeIcons.length).toBeGreaterThanOrEqual(3);
     expect(coffeeIcons.length).toBeLessThanOrEqual(4);
 

package/examples/installer.test.mjs

@@ -62,7 +62,7 @@ describe("Provision Installer", () => {
       // Download a shell script (nvm installer)
       const filePath = await testdriver.provision.installer({
         url: 'https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh',
-        launch: false, // Don't auto-run the script
+        launch: false, // Download the script without running it
       });
 
       // Verify the file was downloaded

package/examples/launch-vscode-linux.test.mjs

@@ -1,3 +1,7 @@
+/**
+ * Launches VS Code in a Linux sandbox and checks that its window opens.
+ */
+
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "../lib/vitest/hooks.mjs";
 import { getDefaults } from "./config.mjs";
@@ -9,11 +13,10 @@ describe("Launch VS Code on Linux", () => {
     "should launch VS Code on Debian/Ubuntu",
     async (context) => {
       const testdriver = TestDriver(context, { ...getDefaults(context) });
-      
-      // provision.vscode() automatically calls ready() and starts dashcam
+
       await testdriver.provision.vscode();
 
-      // Wait for VS Code to launch (polls every 5s until found or timeout)
+      // Poll for up to 60 seconds while VS Code starts
       const vsCodeWindow = await testdriver.find(
         "Visual Studio Code window",
         { timeout: 60000 }
@@ -22,34 +25,4 @@ describe("Launch VS Code on Linux", () => {
     },
   );
 
-  // it.skipIf(!isLinux)(
-  //   "should install and use a VS Code extension",
-  //   async (context) => {
-  //     const testdriver = TestDriver(context, { ...getDefaults(context) });
-      
-  //     // Launch VS Code with the Prettier extension installed
-  //     await testdriver.provision.vscode({
-  //       extensions: ["esbenp.prettier-vscode"],
-  //     });
-
-  //     const vsCodeWindow = await testdriver.find(
-  //       "Visual Studio Code window",
-  //       { timeout: 60000 }
-  //     );
-
-  //     expect(vsCodeWindow.found()).toBeTruthy();
-
-  //     // Open the extensions panel to verify Prettier is installed
-  //     await testdriver.pressKeys(["ctrl", "shift", "x"]);
-      
-  //     // Wait for extensions panel to open
-  //     await new Promise((resolve) => setTimeout(resolve, 2000));
-
-  //     // Assert that Prettier extension is visible in the installed extensions
-  //     const prettierVisible = await testdriver.assert(
-  //       "Prettier extension is visible in the extensions panel or sidebar",
-  //     );
-  //     expect(prettierVisible).toBeTruthy();
-  //   },
-  // );
 });

package/examples/{scroll-keyboard.test.mjs → navigate-and-scroll.test.mjs}

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Scroll Keyboard Test (Vitest)
- * Converted from: testdriver/acceptance/scroll-keyboard.yaml
+ * Navigates to a page by typing in Chrome's address bar, then scrolls
+ * down and asserts that the heading has scrolled out of view.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,8 +12,7 @@ describe("Scroll Keyboard Test", () => {
     const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-    //
-    // Navigate to https://www.webhamster.com/
+    // Navigate to https://www.webhamster.com/ through the address bar
     await testdriver.focusApplication("Google Chrome");
     const urlBar = await testdriver.find(
       "the URL in the omnibox", {zoom: true}
@@ -23,7 +22,7 @@ describe("Scroll Keyboard Test", () => {
     await testdriver.type("https://www.webhamster.com/");
     await testdriver.pressKeys(["enter"]);
 
-    // Scroll down with keyboard 1000 pixels
+    // Click the page so it has focus, then scroll down
     const heading = await testdriver.find(
       "The Hamster Dance, large heading at top of page",
     );

package/examples/parse.test.mjs

@@ -1,6 +1,5 @@
 /**
- * TestDriver SDK - Parse Test (Vitest)
- * Opens Airbnb and runs the .parse() SDK command to analyze the screen.
+ * Opens Airbnb and runs parse() to list the UI elements on screen.
  */
 
 import { describe, it } from "vitest";

package/examples/press-keys.test.mjs

@@ -1,6 +1,6 @@
 /**
- * TestDriver SDK - Press Keys Test (Vitest)
- * Converted from: testdriver/acceptance/press-keys.yaml
+ * Uses keyboard shortcuts to open a new tab, open DevTools, and navigate
+ * to a URL.
  */
 
 import { describe, expect, it } from "vitest";
@@ -20,7 +20,7 @@ describe("Press Keys Test", () => {
     // Open new tab
     await testdriver.pressKeys(["ctrl", "t"]);
 
-    // Poll for "Learn more" to appear
+    // Wait for the new tab page to load
     let imagesLink = await testdriver.find("Images", {timeout: 5000});
 
     expect(imagesLink.found()).toBeTruthy();
@@ -28,7 +28,7 @@ describe("Press Keys Test", () => {
     // Open DevTools
     await testdriver.pressKeys(["ctrl", "shift", "i"]);
 
-    // Poll for "Elements" to appear
+    // Wait for the DevTools Elements panel
     let elements = await testdriver.find("Elements", {timeout: 5000});
     expect(elements.found()).toBeTruthy();
 

package/examples/scroll.test.mjs

@@ -1,8 +1,6 @@
 /**
- * TestDriver SDK - Scroll Test (Vitest)
- * Converted from: testdriver/acceptance/scroll.yaml
- * 
- * UPDATED: Now using chrome preset for automatic setup
+ * Opens a page, scrolls down, and asserts that the heading has scrolled
+ * out of view.
  */
 
 import { describe, expect, it } from "vitest";
@@ -14,8 +12,7 @@ describe("Scroll Test", () => {
     const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
     await testdriver.provision.chrome({ url: 'https://www.webhamster.com/' });
 
-
-    // Wait for page to load and click heading
+    // Click the page so it has focus before scrolling
     const heading = await testdriver.find(
       "The Hamster Dance, large heading at top of page",
     );

package/examples/type.test.mjs

@@ -1,3 +1,8 @@
+/**
+ * Types into the login form and asserts on the result, including the
+ * browser's validation message for a missing password.
+ */
+
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "../lib/vitest/hooks.mjs";
 import { getDefaults } from "./config.mjs";
@@ -7,7 +12,6 @@ describe("Type Test", () => {
     const testdriver = TestDriver(context, { ...getDefaults(context), headless: true });
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-    //
     const usernameField = await testdriver.find(
       "Username, input field for username",
     );
@@ -31,7 +35,6 @@ describe("Type Test", () => {
     await usernameField.click();
     await testdriver.type("standard_user");
 
-    //
     const signInButton = await testdriver.find(
       "Sign in, black button below the password field",
     );

package/lib/provision.js

@@ -482,7 +482,8 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
      * @param {boolean} [options.launch=true] - Whether to launch the app after installation.
      *   For a .deb on Linux this starts the app from its `.desktop` entry (or, when
      *   `appName` is set and there is no `.desktop` entry, its first `/usr/bin` binary),
-     *   then focuses `appName`. On other platforms it only focuses `appName`.
+     *   then focuses `appName`. A downloaded .sh script is only run when this is true.
+     *   On other platforms it only focuses `appName`.
      * @returns {Promise<string>} Path to the downloaded file
      * @example
      * // Install a .deb package on Linux (auto-detected). Missing dependencies
@@ -620,7 +621,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         } else if (ext === "appimage") {
           installCommand = `chmod +x "${actualFilePath}"`;
         } else if (ext === "sh") {
-          installCommand = `chmod +x "${actualFilePath}" && "${actualFilePath}"`;
+          // Running a script is launching it, so `launch: false` only makes it executable
+          installCommand = launch
+            ? `chmod +x "${actualFilePath}" && "${actualFilePath}"`
+            : `chmod +x "${actualFilePath}"`;
         }
       } else if (self.os === "darwin") {
         if (ext === "dmg") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testdriverai/agent",
-  "version": "7.11.229-canary",
+  "version": "7.11.231-test",
   "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

@@ -281,6 +281,8 @@ export interface TestDriverOptions {
   reconnect?: boolean;
   /** Explicit sandbox id to reconnect to. Implies `newSandbox: false` unless explicitly overridden. */
   sandboxId?: string;
+  /** Keep the sandbox running for this many milliseconds after disconnect, so you can reconnect to it (default: 60000). Capped at 30 minutes. 0 uses the default; there is no immediate-termination value. */
+  keepAlive?: number;
   /** Enable/disable Dashcam video recording (default: true) */
   dashcam?: boolean;
   /**
@@ -359,7 +361,7 @@ export interface ConnectOptions {
   headless?: boolean;
   /** Reuse recent connection if available (default: true) */
   reuseConnection?: boolean;
-  /** Keep sandbox alive for specified milliseconds after disconnect (default: 60000). Set to 0 to terminate immediately on disconnect. */
+  /** Keep the sandbox running for this many milliseconds after disconnect, so you can reconnect to it (default: 60000). Capped at 30 minutes. 0 uses the default; there is no immediate-termination value. */
   keepAlive?: number;
 }
 
@@ -903,7 +905,7 @@ export interface ProvisionInstallerOptions {
   filename?: string;
   /** Application name to focus after install */
   appName?: string;
-  /** Whether to launch the app after installation (default: true). For a .deb on Linux this starts the app from its .desktop entry, then focuses appName. */
+  /** Whether to launch the app after installation (default: true). For a .deb on Linux this starts the app from its .desktop entry, then focuses appName. A downloaded .sh script only runs when this is true. Elsewhere it only focuses appName. */
   launch?: boolean;
 }
 

package/sdk.js

@@ -443,7 +443,7 @@ class Element {
    * @returns {Promise<Element>} This element instance
    */
   async find(newDescription, options) {
-    // Handle timeout/polling option (default: 30s)
+    // Handle timeout/polling option (default: 10s, polling every 5s)
     const timeout = typeof options === "object" && options?.timeout !== undefined
       ? options.timeout
       : 10000;