testdriver:machine-setup

<!-- Generated from machine-setup.mdx. DO NOT EDIT. -->

TestDriver provisions a fresh cloud VM for every test by default. This guide covers how to configure Linux and Windows machines, reduce startup time by keeping machines alive between runs, use provision scripts for repeatable setup, and install custom software on the fly.

---

## Linux Machines

Linux is the default operating system. No extra configuration is required.

```javascript
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("My Test", () => {
  it("runs on Linux", async (context) => {
    const testdriver = TestDriver(context);

    await testdriver.provision.chrome({ url: "https://example.com" });

    const result = await testdriver.assert("the page loaded successfully");
    expect(result).toBeTruthy();
  });
});
```

### Common Linux Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `os` | string | `"linux"` | Operating system |
| `resolution` | string | `"1366x768"` | Screen resolution (Enterprise only) |
| `e2bTemplateId` | string | — | Custom E2B template ID (see [Self-Hosted](/v7/self-hosted)) |
| `keepAlive` | number | `60000` | Ms to keep VM alive after disconnect |
| `reconnect` | boolean | `false` | Reconnect to last used sandbox |

```javascript
const testdriver = TestDriver(context, {
  os: "linux",
  resolution: "1920x1080",
  keepAlive: 5 * 60 * 1000, // keep alive 5 minutes
});
```

---

## Windows Machines

Set `os: "windows"` to provision a Windows VM instead. Everything else works the same way.

```javascript
const testdriver = TestDriver(context, {
  os: "windows",
});

await testdriver.provision.chrome({ url: "https://example.com" });
```

Windows sandboxes use EC2 instances and take longer to boot than Linux (E2B) sandboxes — typically 1–3 minutes for a cold start. See [Keeping Machines Alive](#keeping-machines-alive-between-runs) below to avoid this cost on repeated runs.

### Common Windows Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `os` | string | — | Set to `"windows"` |
| `resolution` | string | `"1366x768"` | Screen resolution (Enterprise only) |
| `sandboxAmi` | string | — | Custom AMI ID (self-hosted) |
| `sandboxInstance` | string | — | EC2 instance type (self-hosted) |
| `keepAlive` | number | `60000` | Ms to keep VM alive after disconnect |
| `reconnect` | boolean | `false` | Reconnect to last used sandbox |

```javascript
const testdriver = TestDriver(context, {
  os: "windows",
  resolution: "1920x1080",
  keepAlive: 10 * 60 * 1000, // keep alive 10 minutes
});
```

---

## Keeping Machines Alive Between Runs

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
// first.test.mjs
const testdriver = TestDriver(context, {
  os: "windows",
  keepAlive: 30 * 60 * 1000, // keep alive 30 minutes after this test ends
});

await testdriver.provision.chrome({ url: "https://example.com" });
// ... your test steps
```

When this test finishes, the sandbox stays running for 30 minutes instead of being terminated immediately.

### 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,
});

// No provision call — Chrome is already open from the previous run.
await testdriver.find("Sign In button").click();
```

### 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 continue from the app state created in the earlier run
- You must run within the previous test's `keepAlive` window

<Tip>
  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,