@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/docs/docs.json

@@ -20,7 +20,6 @@
             "group": "Overview",
             "pages": [
               "/v7/quickstart",
-              "/v7/what-is-testdriver",
               {
                 "group": "Examples",
                 "icon": "code",
@@ -29,27 +28,20 @@
                   "/v7/examples/assert",
                   "/v7/examples/chrome-extension",
                   "/v7/examples/element-not-found",
-                  "/v7/examples/exec-output",
-                  "/v7/examples/exec-pwsh",
                   "/v7/examples/findall-coffee-icons",
-                  "/v7/examples/focus-window",
-                  "/v7/examples/formatted-logging",
                   "/v7/examples/hover-image",
                   "/v7/examples/hover-text-with-description",
                   "/v7/examples/hover-text",
                   "/v7/examples/installer",
                   "/v7/examples/launch-vscode-linux",
-                  "/v7/examples/match-image",
                   "/v7/examples/parse",
                   "/v7/examples/press-keys",
-                  "/v7/examples/prompt",
                   "/v7/examples/scroll-keyboard",
-                  "/v7/examples/scroll-until-image",
                   "/v7/examples/scroll",
-                  "/v7/examples/type",
-                  "/v7/examples/windows-installer"
+                  "/v7/examples/type"
                 ]
               },
+              "/v7/what-is-testdriver",
               {
                 "group": "Deployment",
                 "icon": "server",
@@ -61,32 +53,16 @@
               "/changelog"
             ]
           },
-          {
-            "group": "GitHub Copilot",
-            "pages": [
-              "/v7/copilot/setup",
-              "/v7/copilot/creating-tests",
-              "/v7/copilot/running-tests",
-              "/v7/copilot/github",
-              "/v7/copilot/auto-healing"
-            ]
-          },
           {
             "group": "Guide",
             "pages": [
               "/v7/generating-tests",
-              "/v7/device-config",
-              "/v7/locating-elements",
-              "/v7/waiting-for-elements",
-              "/v7/performing-actions",
-              "/v7/making-assertions"
-            ]
-          },
-          {
-            "group": "Running Tests",
-            "pages": [
-              "/v7/running-tests",
               "/v7/caching",
+              "/v7/copilot/running-tests",
+              "/v7/making-assertions",
+              "/v7/performing-actions",
+              "/v7/debugging-with-screenshots",
+              "/v7/copilot/auto-healing",
               "/v7/ci-cd",
               "/v7/test-results-json"
             ]
@@ -98,7 +74,7 @@
               "/v7/secrets",
               "/v7/reusable-code",
               {
-                "group": "Self-Hosting Setup",
+                "group": "Self-Hosting",
                 "icon": "server",
                 "pages": [
                   "/v7/aws-setup"
@@ -109,7 +85,6 @@
           {
             "group": "Actions",
             "pages": [
-              "/v7/ai",
               "/v7/assert",
               "/v7/captcha",
               "/v7/click",
@@ -358,6 +333,14 @@
     }
   },
   "redirects": [
+    {
+      "source": "/v7/ai",
+      "destination": "/v7/quickstart"
+    },
+    {
+      "source": "/v7/ai/:slug*",
+      "destination": "/v7/quickstart"
+    },
     {
       "source": "/guides/github-actions",
       "destination": "/v6/action/setup"

package/docs/snippets/tests/scroll-yaml.mdx

@@ -14,7 +14,7 @@ steps:
       - command: press-keys
         keys:
           - enter
-  - prompt: scroll down with the mouse 1000 pixels
+  - prompt: scroll down with the mouse 10 clicks
     commands:
       - command: hover-text
         text: "HTML: HyperText Markup Language"
@@ -22,7 +22,7 @@ steps:
         action: click
       - command: scroll
         direction: down
-        amount: 1000
+        amount: 10
   - prompt: assert the page is scrolled
     commands:
       - command: assert

package/docs/v6/commands/scroll-until-image.mdx

@@ -22,7 +22,7 @@ The `scroll-until-image` command is used to scroll the screen in a specified dir
 | :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
 | `description` | `string`  | A description of the image and what it represents.                                                                      |
 |  `direction`  | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
-|  `distance`   | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+|  `distance`   | `number`  | (Optional) The maximum number of scroll clicks before giving up. Default is `100`.                                 |
 |   `method`    | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
 |    `path`     | `string`  | (Optional) The relative path to the image file that needs to be matched on the screen.                                  |
 |   `invert`    | `boolean` | (Optional) If set to `true`, the command will scroll until the specified image is NOT detected. Default is `false`.     |

package/docs/v6/commands/scroll-until-text.mdx

@@ -23,7 +23,7 @@ The `scroll-until-text` command is used to scroll the screen in a specified dire
 |   `text`    | `string`  | The text to find on the screen. Longer and unique are better. Note this is **case sensitive**                           |
 | `direction` | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
 |  `method`   | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
-| `distance`  | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+| `distance`  | `number`  | (Optional) The maximum number of scroll clicks before giving up. Default is `100`.                                 |
 |  `invert`   | `boolean` | (Optional) If set to `true`, the command will scroll until the specified text is NOT detected. Default is `false`.      |
 
 <Note>
@@ -47,7 +47,7 @@ distance: 1000
 
 - Use unique and specific text to improve detection accuracy.
 - Adjust the `distance` value to control how far the command scrolls before giving up.
-- If you don't specify a `distance`, the command will scroll 300 pixels at a time, giving up after 5 attempts.
+- If you don't specify a `distance`, the command will scroll 5 clicks at a time, giving up after reaching 100 clicks.
 
 ## Gotchas
 

package/docs/v6/commands/scroll.mdx

@@ -22,7 +22,7 @@ The `scroll` command is used to scroll the screen in a specified direction using
 | :---------: | :------: | :------------------------------------------------------------------------------------ |
 | `direction` | `string` | The direction to scroll. Available directions are: `up`, `down`, `left`, `right`.     |
 |  `method`   | `string` | The method to scroll. Available methods are: `mouse`, `keyboard`. Defaults to `mouse` |
-|  `amount`   | `number` | (Optional) Pixels to scroll. If not specified, a default amount of 300 is used.       |
+|  `amount`   | `number` | (Optional) Clicks (scroll wheel units) to scroll. If not specified, a default of 3 is used. |
 
 <Warning>
   The `amount` should only be used when the `method` is mouse. If the `method`
@@ -36,7 +36,7 @@ The `scroll` command is used to scroll the screen in a specified direction using
 - command: scroll
   direction: down
   method: mouse
-  amount: 100
+  amount: 3
 ```
 
 ## Protips

package/docs/v7/_drafts/agents.mdx

@@ -364,10 +364,6 @@ await testdriver.scroll('left', 300);
 // Scroll methods
 await testdriver.scroll('down', 300, 'mouse');    // Mouse wheel (smooth)
 await testdriver.scroll('down', 300, 'keyboard'); // Page Down key
-
-// Scroll until text appears
-await testdriver.scrollUntilText('Contact Us');
-await testdriver.scrollUntilText('Footer', 'down', 5000);
 ```
 
 ### exec(language, code, timeout, silent) - Execute Code

package/docs/v7/_drafts/best-practices.mdx

@@ -117,18 +117,6 @@ await button.click();
 
 ## Actions
 
-### Use Descriptive Prompts
-
-```javascript
-// ❌ Generic
-await testdriver.ai('login');
-
-// ✅ Specific steps
-await testdriver.ai('click the username field and type user@example.com');
-await testdriver.ai('click the password field and type password123');
-await testdriver.ai('click the blue submit button');
-```
-
 ### Chain Actions
 
 ```javascript

package/docs/v7/_drafts/commands/scroll-until-image.mdx

@@ -22,7 +22,7 @@ The `scroll-until-image` command is used to scroll the screen in a specified dir
 | :-----------: | :-------: | :---------------------------------------------------------------------------------------------------------------------- |
 | `description` | `string`  | A description of the image and what it represents.                                                                      |
 |  `direction`  | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
-|  `distance`   | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+|  `distance`   | `number`  | (Optional) The maximum number of scroll clicks before giving up. Default is `100`.                                 |
 |   `method`    | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
 |    `path`     | `string`  | (Optional) The relative path to the image file that needs to be matched on the screen.                                  |
 |   `invert`    | `boolean` | (Optional) If set to `true`, the command will scroll until the specified image is NOT detected. Default is `false`.     |

package/docs/v7/_drafts/commands/scroll-until-text.mdx

@@ -23,7 +23,7 @@ The `scroll-until-text` command is used to scroll the screen in a specified dire
 |   `text`    | `string`  | The text to find on the screen. Longer and unique are better. Note this is **case sensitive**                           |
 | `direction` | `string`  | (Optional) The direction to scroll. Available directions are: `up`, `down`, `left`, `right`. Defaults to `down`.        |
 |  `method`   | `string`  | (Optional) The method to use to scroll the page. Available methods are: `mouse` and `keyboard`. Defaults to `keyboard`. |
-| `distance`  | `number`  | (Optional) The maximum number of pixels to scroll before giving up. Default is `10000`.                                 |
+| `distance`  | `number`  | (Optional) The maximum number of scroll clicks before giving up. Default is `100`.                                 |
 |  `invert`   | `boolean` | (Optional) If set to `true`, the command will scroll until the specified text is NOT detected. Default is `false`.      |
 
 <Note>
@@ -47,7 +47,7 @@ distance: 1000
 
 - Use unique and specific text to improve detection accuracy.
 - Adjust the `distance` value to control how far the command scrolls before giving up.
-- If you don't specify a `distance`, the command will scroll 300 pixels at a time, giving up after 5 attempts.
+- If you don't specify a `distance`, the command will scroll 5 clicks at a time, giving up after reaching 100 clicks.
 
 ## Gotchas
 

package/docs/v7/_drafts/commands/scroll.mdx

@@ -22,7 +22,7 @@ The `scroll` command is used to scroll the screen in a specified direction using
 | :---------: | :------: | :------------------------------------------------------------------------------------ |
 | `direction` | `string` | The direction to scroll. Available directions are: `up`, `down`, `left`, `right`.     |
 |  `method`   | `string` | The method to scroll. Available methods are: `mouse`, `keyboard`. Defaults to `mouse` |
-|  `amount`   | `number` | (Optional) Pixels to scroll. If not specified, a default amount of 300 is used.       |
+|  `amount`   | `number` | (Optional) Scroll clicks (wheel units). If not specified, a default amount of 3 is used.       |
 
 <Warning>
   The `amount` should only be used when the `method` is mouse. If the `method`

package/docs/v7/_drafts/configuration.mdx

@@ -205,18 +205,6 @@ const { testdriver, dashcam } = await electron(context, {
 
 ## Cache Configuration
 
-### Prompt Cache
-
-Configure AI prompt caching:
-
-```javascript
-// Disable prompt cache globally
-process.env.TD_NO_PROMPT_CACHE = 'true';
-
-// Per call
-await testdriver.ai('click button', false); // bypass cache
-```
-
 ### Selector Cache
 
 Configure element location caching:

package/docs/v7/_drafts/faq.mdx

@@ -116,21 +116,13 @@ Features:
 
 ### How does caching work?
 
-Two types of caching:
-
-**1. Prompt Cache** - Caches AI-generated commands locally
-```javascript
-await testdriver.ai('click button'); // AI call
-await testdriver.ai('click button'); // Uses cache
-```
-
-**2. Selector Cache** - Caches element locations on server
+**Selector Cache** - Caches element locations on server
 ```javascript
 await testdriver.find('button'); // AI vision
 await testdriver.find('button'); // Cache hit (95%+ similar UI)
 ```
 
-See [caching guide](/v7/guides/caching-ai) for details.
+See [caching guide](/v7/caching) for details.
 
 ### Can I test responsive designs?
 

package/docs/v7/_drafts/readme.mdx

@@ -67,7 +67,6 @@ v7/
 - `pressKeys()` - Keyboard shortcuts and special keys
 - `click()` / `hover()` - Coordinate-based mouse actions
 - `scroll()` - Page scrolling
-- `scrollUntilText()` / `scrollUntilImage()` - Scroll until found
 - Keyboard key reference
 
 #### Assertions (`/v7/api/assertions.mdx`)

package/docs/v7/_drafts/troubleshooting.mdx

@@ -331,11 +331,8 @@ test('slow test', async () => {
 
 **2. Optimize test:**
 ```javascript
-// Use faster actions
+// Use explicit actions
 await testdriver.find('button').then(el => el.click());
-
-// Instead of
-await testdriver.ai('click the button');
 ```
 
 ### Tests Fail in CI

package/docs/v7/assert.mdx

@@ -313,4 +313,3 @@ describe('Assertions', () => {
 
 - [`extract()`](/v7/extract) - Extract information for detailed assertions
 - [`find()`](/v7/find) - Locate elements to verify
-- [`ai()`](/v7/ai) - Complex AI-driven tasks

package/docs/v7/aws-setup.mdx

@@ -193,7 +193,7 @@ Tests should use `context.ip || process.env.TD_IP` for the IP configuration:
 
 ```javascript
 import { describe, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("My Test", () => {
   it("should run on self-hosted instance", async (context) => {

package/docs/v7/caching.mdx

@@ -1,11 +1,13 @@
 ---
-title: "Caching Prompts"
-description: "1.7x faster test execution with intelligent caching and optimization"
-icon: "bolt"
+title: "Learn"
+sidebarTitle: "Learn"
+description: "How TestDriver learns your app and caches what it discovers for instant, deterministic replays"
+icon: "brain"
 ---
 
-TestDriver is engineered for performance with intelligent caching that delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis.
+Once the agent has [explored your app](/v7/generating-tests), TestDriver remembers what it found. Every element the AI vision agent discovers is cached with a vision fingerprint—a perceptual hash of the screen state where it was located. On the next run, TestDriver matches against that cache instead of calling the AI again. Passing tests replay instantly, deterministically, and cheaply.
 
+This learning is what makes TestDriver fast. Intelligent caching delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis—the agent only thinks when it sees something new.
 
 ```javascript
 // First run: builds cache
@@ -17,7 +19,7 @@ await testdriver.find('submit button');
 
 ## Automatic Caching
 
-Caching is enabled automatically with zero configuration. The cache key is computed from:
+Learning is enabled automatically with zero configuration. The cache key—the fingerprint TestDriver uses to recognize what it already knows—is computed from:
 
 - **File hash**: SHA-256 hash of the test file contents
 - **Selector prompt**: The exact text description passed to `find()`
@@ -53,7 +55,7 @@ You can clear the cache within the TestDriver console. There, you'll also find p
 
 ## Debugging Cache Hits and Misses
 
-You can track cache performance in your tests:
+You can track what TestDriver has learned by inspecting cache performance in your tests:
 
 ```javascript
 test('monitor cache performance', async (context) => {
@@ -75,7 +77,7 @@ test('monitor cache performance', async (context) => {
 
 ## Configuring the Cache
 
-You can configure cache behavior globally when initializing TestDriver:
+You can configure how TestDriver learns globally when initializing TestDriver:
 
 ```javascript
 import { TestDriver } from 'testdriverai';
@@ -103,7 +105,7 @@ await testdriver.find('submit button', {
 
 ## Caching with Variables
 
-Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates.
+Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates—so TestDriver reuses what it learned even when your data changes.
 
 ```javascript
 // ❌ Without cache key - creates new cache for each variable value
@@ -123,6 +125,8 @@ await testdriver.find(`order ${orderId} status`, {
 });
 ```
 
+## Next
 
-
-
+<Card href="/v7/copilot/running-tests" title="Run" icon="play">
+  Now that TestDriver has learned your app, run your tests in CI and locally—replaying the cache for fast, deterministic results.
+</Card>

package/docs/v7/ci-cd.mdx

@@ -7,29 +7,72 @@ icon: "code-branch"
 
 TestDriver integrates seamlessly with popular CI providers, enabling automated end-to-end testing on every push and pull request.
 
-## Adding Your API Key
+## Authentication
 
-TestDriver requires an API key to authenticate with the TestDriver cloud. Store this securely as a secret in your CI provider.
+On **GitHub Actions, prefer OIDC** via the published `testdriverai/action` —
+there's no `TD_API_KEY` secret to store, copy, or rotate. The action proves the
+workflow is running inside your org and TestDriver exchanges that proof for your
+team's key at run time. See the GitHub Actions tab below.
 
-<Steps>
-  <Step title="Get Your API Key">
-    Go to [console.testdriver.ai/team](https://console.testdriver.ai/team) and copy your team's API key
-  </Step>
-  <Step title="Add Secret to Your CI Provider">
-    Add `TD_API_KEY` as a secret environment variable in your CI provider's settings.
-  </Step>
-</Steps>
+For other CI providers (or self-hosted runners without OIDC), fall back to a
+stored API key from [console.testdriver.ai/team](https://console.testdriver.ai/team),
+added as a `TD_API_KEY` secret in your CI provider's settings.
 
 <Note>
-  Never commit your API key directly in code. Always use your CI provider's secrets management.
+  Never commit your API key directly in code. Always use OIDC or your CI provider's secrets management.
 </Note>
 
 ## CI Provider Examples
 
 <Tabs>
   <Tab title="GitHub Actions">
-    ### Adding Secrets
-    
+    ### Authenticate with OIDC via `testdriverai/action` (recommended)
+
+    Use the published [`testdriverai/action`](https://github.com/testdriverai/action) — it mints the OIDC token, exchanges it for your team's API key, and exports `TD_API_KEY` for the steps that follow. **No `TD_API_KEY` secret to store or rotate.**
+
+    <Note>
+      One-time setup: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org so the org → team binding exists. If your org authorized the App before OIDC support shipped, re-authorize once. If the App isn't authorized, the action fails with a console link (or falls back to the `api-key` secret if you provide one).
+    </Note>
+
+    ```yaml .github/workflows/testdriver.yml
+    name: TestDriver Tests
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+        branches: [main]
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        permissions:
+          id-token: write   # REQUIRED to mint an OIDC token
+          contents: read
+
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+              cache: 'npm'
+
+          - run: npm ci
+
+          - name: Authenticate to TestDriver
+            uses: testdriverai/action@stable   # pin @stable / @canary / @test to your SDK channel
+            with:
+              api-key: ${{ secrets.TD_API_KEY }}   # optional fallback if OIDC isn't set up
+
+          - name: Run TestDriver tests
+            run: npx vitest run
+    ```
+
+    ### Stored-key fallback
+
+    Only if you can't use OIDC (e.g. self-hosted runners without an OIDC provider). Add the key as a secret and pass it via `env`:
+
     1. Navigate to your GitHub repository
     2. Go to **Settings** → **Secrets and variables** → **Actions**
     3. Click **New repository secret**
@@ -572,7 +615,7 @@ When using multi-platform testing, read the `TD_OS` environment variable in your
 
 ```javascript tests/cross-platform.test.mjs
 import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { TestDriver } from "testdriverai/vitest/hooks";
 
 describe("Cross-platform tests", () => {
   it("should work on both Linux and Windows", async (context) => {
@@ -592,6 +635,47 @@ describe("Cross-platform tests", () => {
 });
 ```
 
+## Concurrency limits
+
+Your plan allows a fixed number of sandboxes running at once. When a test asks for
+a sandbox and you're already at that limit, the request is **queued** rather than
+failed immediately: the SDK waits for a slot to free up, retrying every 10 seconds,
+then proceeds automatically once one opens. This is what lets a parallel CI matrix
+(many jobs starting at once) work on a plan with fewer slots than jobs — the extra
+jobs simply wait their turn instead of erroring.
+
+By default the SDK waits up to **60 seconds** for a slot before giving up with a
+concurrency-limit error. Control that ceiling with `TD_CONCURRENCY_MAX_WAIT`:
+
+| Value | Behavior |
+| ----- | -------- |
+| _unset_ | Wait up to **60 seconds** (the default). |
+| `TD_CONCURRENCY_MAX_WAIT=300` | Wait up to **300 seconds** (5 minutes) before giving up. |
+| `TD_CONCURRENCY_MAX_WAIT=0` | **Don't queue** — fail on the first denial. |
+
+The value is **in seconds** (fractional values are allowed and rounded to the
+nearest millisecond). Any invalid or negative value falls back to the 60-second
+default. The wait applies per sandbox request, across both the initial allocation
+and the realtime slot-approval handshake.
+
+```yaml
+# Example: a large parallel matrix that may queue for a while.
+# Give each job up to 5 minutes to acquire a slot before failing.
+- name: Run TestDriver tests
+  env:
+    TD_API_KEY: ${{ secrets.TD_API_KEY }}
+    TD_CONCURRENCY_MAX_WAIT: "300"
+  run: npx vitest run
+```
+
+<Tip>
+Raise `TD_CONCURRENCY_MAX_WAIT` when you run more parallel jobs than your plan has
+slots and would rather they queue than fail. Set it to `0` when you'd prefer a job
+to **fail fast** on a busy account (e.g. a quick smoke test that shouldn't sit
+waiting). When jobs routinely give up waiting, that's the signal to
+[add more slots](https://console.testdriver.ai/checkout/pro).
+</Tip>
+
 ## Viewing Results
 
 All test runs are automatically recorded and visible in your TestDriver dashboard at [console.testdriver.ai](https://console.testdriver.ai):

package/docs/v7/client.mdx

@@ -30,7 +30,7 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="resolution" type="string" default="1366x768">
-      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
+      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`). Custom resolutions are only available on Enterprise plans.
     </ParamField>
     
     <ParamField path="apiRoot" type="string">
@@ -45,7 +45,7 @@ const testdriver = new TestDriver(apiKey, options)
       Enable or disable console logging
     </ParamField>
     
-    <ParamField path="autoScreenshots" type="boolean" default="true">
+    <ParamField path="autoScreenshots" type="boolean" default="false">
       Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
     </ParamField>
     
@@ -54,11 +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 [Run guide](/v7/copilot/running-tests#keeping-machines-alive-between-runs).
     </ParamField>
-    
-    <ParamField path="keepAlive" type="number" default="60000">
-      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+
+    <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">
@@ -275,6 +275,10 @@ await testdriver.connect(options)
     <ParamField path="headless" type="boolean" default="false">
       **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
     </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
   </Expandable>
 </ParamField>