testdriver:device-config

<!-- Generated from device-config.mdx. DO NOT EDIT. -->

Provision methods are the starting point for most tests. They launch applications in your sandbox and prepare the environment for testing.

## Chrome Browser

The most common starting point for web testing. Launches Chrome browser and navigates to a URL.

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

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `url` | string | `'http://testdriver-sandbox.vercel.app/'` | URL to navigate to |
| `maximized` | boolean | `true` | Start browser maximized |
| `guest` | boolean | `false` | Use guest mode (no profile) |

### Example: Basic Web Test

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

describe("Login Flow", () => {
  it("should log in successfully", async (context) => {
    const testdriver = TestDriver(context);
    
    await testdriver.provision.chrome({
      url: 'https://myapp.com/login',
    });

    await testdriver.find("Email input").click();
    await testdriver.type("user@example.com");
    
    await testdriver.find("Password input").click();
    await testdriver.type("password123");
    
    await testdriver.find("Sign In button").click();
    
    const result = await testdriver.assert("the dashboard is visible");
    expect(result).toBeTruthy();
  });
});
```

<Info>
  `provision.chrome()` automatically starts Dashcam recording and waits for Chrome to be ready before returning.
</Info>

---

## Chrome Extensions

Launch Chrome with a custom extension loaded. Supports both local extensions and Chrome Web Store extensions.

### Load from Local Path

Clone or create an extension locally, then load it:

```javascript
// First, get the extension onto the sandbox
await testdriver.exec(
  'sh',
  'git clone https://github.com/user/my-extension.git /tmp/my-extension',
  60000
);

// Launch Chrome with the extension
await testdriver.provision.chromeExtension({
  extensionPath: '/tmp/my-extension',
  url: 'https://example.com'
});
```

### Load from Chrome Web Store

Load any published extension by its Chrome Web Store ID:

```javascript
await testdriver.provision.chromeExtension({
  extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
  url: 'https://example.com'
});
```

<Tip>
  Find the extension ID in the Chrome Web Store URL. For example, `https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm` → ID is `cjpalhdlnbpafiamejdnhcphjbkeiagm`
</Tip>

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `extensionPath` | string | - | Local path to unpacked extension directory |
| `extensionId` | string | - | Chrome Web Store extension ID |
| `url` | string | - | URL to navigate to after launch |
| `maximized` | boolean | `true` | Start browser maximized |

<Warning>
  You must provide either `extensionPath` or `extensionId`, but not both.
</Warning>

### Example: Testing a Chrome Extension

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

describe("Chrome Extension Test", () => {
  it("should load and interact with extension", async (context) => {
    const testdriver = TestDriver(context);

    // Clone extension from GitHub
    await testdriver.exec(
      'sh',
      'git clone https://github.com/user/my-extension.git /tmp/my-extension',
      60000,
      true
    );

    // Launch Chrome with extension loaded
    await testdriver.provision.chromeExtension({
      extensionPath: '/tmp/my-extension',
      url: 'https://testdriver.ai'
    });

    // Click extensions puzzle icon
    const extensionsButton = await testdriver.find("puzzle-shaped icon in Chrome toolbar");
    await extensionsButton.click();

    // Interact with your extension
    const myExtension = await testdriver.find("My Extension in the dropdown");
    await myExtension.click();

    const result = await testdriver.assert("extension popup is visible");
    expect(result).toBeTruthy();
  });
});
```

---

## Desktop Apps

Download and install desktop applications. Supports `.deb`, `.rpm`, `.msi`, `.exe`, `.AppImage`, `.dmg`, `.pkg`, and shell scripts.

```javascript
const filePath = await testdriver.provision.installer({
  url: 'https://example.com/app.deb',
  appName: 'MyApp',  // Focus this app after install
  launch: true,      // Auto-launch after install
});
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `url` | string | **required** | URL to download the installer from |
| `filename` | string | auto-detected | Filename to save as |
| `appName` | string | - | Application name to focus after install |
| `launch` | boolean | `true` | Launch the app after installation |

### Supported File Types

| Extension | OS | Install Method |
|-----------|-----|----------------|
| `.deb` | Linux | `dpkg -i` + `apt-get install -f` |
| `.rpm` | Linux | `rpm -i` |
| `.AppImage` | Linux | `chmod +x` |
| `.sh` | Linux | `chmod +x` + execute |
| `.msi` | Windows | `msiexec /i /quiet` |
| `.exe` | Windows | Silent install (`/S`) |
| `.dmg` | macOS | Mount + copy to Applications |
| `.pkg` | macOS | `installer -pkg` |

### Example: Install and Test a Desktop App

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

describe("Desktop App Test", () => {
  it("should install and launch app", async (context) => {
    const testdriver = TestDriver(context);

    // Download and install
    const installerPath = await testdriver.provision.installer({
      url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
    });

    // Verify installation
    const output = await testdriver.exec('sh', 'bat --version', 5000);
    expect(output).toContain('bat');
  });
});
```

##