testdriverai 7.1.4 → 7.2.2

package/docs/v7/features/managed-sandboxes.mdx

@@ -0,0 +1,384 @@
+---
+title: "Managed Sandboxes"
+description: "Isolated cloud environments automatically provisioned for every test"
+icon: "box"
+---
+
+TestDriver automatically provisions isolated cloud sandboxes for every test run, eliminating the need to manage browsers, VMs, or infrastructure.
+
+## Automatic Provisioning
+
+Every test gets its own fresh sandbox environment:
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('automatic sandbox', async (context) => {
+  // TestDriver automatically provisions a sandbox with Chrome
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+
+  // Test runs in an isolated cloud environment
+  await testdriver.find('button').click();
+  await testdriver.assert('page loaded');
+  
+  // Sandbox automatically cleaned up after test
+});
+```
+
+<Check>
+  No setup required - sandboxes are created on-demand and destroyed after each test.
+</Check>
+
+## What's Included
+
+Each sandbox comes pre-configured with everything you need:
+
+<CardGroup cols={2}>
+  <Card title="Operating Systems" icon="desktop">
+    - Ubuntu Linux (default)
+    - Windows 10/11
+    - macOS (coming soon)
+  </Card>
+
+  <Card title="Browsers" icon="globe">
+    - Google Chrome
+    - Chromium
+    - Firefox (beta)
+    - Edge (beta)
+  </Card>
+
+  <Card title="Desktop Apps" icon="window">
+    - Any Linux application
+    - Windows applications
+    - Electron apps
+  </Card>
+
+  <Card title="Development Tools" icon="code">
+    - VS Code
+    - Node.js
+    - Python
+    - Common dev dependencies
+  </Card>
+</CardGroup>
+
+## Sandbox Configuration
+
+Customize sandbox settings per test:
+
+<Tabs>
+  <Tab title="Operating System">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    test('choose OS', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://example.com',
+        os: 'windows' // 'linux', 'windows', or 'mac'
+      });
+
+      // Test runs on Windows sandbox
+    });
+    ```
+  </Tab>
+
+  <Tab title="Screen Size">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    test('custom resolution', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://example.com',
+        width: 1920,
+        height: 1080,
+        maximized: true
+      });
+
+      // Browser opens at 1920x1080 resolution
+    });
+    ```
+  </Tab>
+
+  <Tab title="Browser Options">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    test('browser settings', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://example.com',
+        guest: true,        // Incognito/private mode
+        headless: false,    // Show browser UI
+        locale: 'en-US',    // Browser language
+        timezone: 'America/New_York'
+      });
+    });
+    ```
+  </Tab>
+
+  <Tab title="Timeout Settings">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    test('longer timeout', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://example.com',
+        timeout: 180000  // 3 minutes (default: 120s)
+      });
+
+      // Sandbox stays alive for up to 3 minutes
+    });
+    ```
+  </Tab>
+</Tabs>
+
+## Persistent Sandboxes
+
+Keep a sandbox alive across multiple tests for faster execution:
+
+```javascript
+import { test, beforeAll, afterAll } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+let testdriver;
+
+beforeAll(async () => {
+  // Create persistent sandbox
+  const result = await chrome({
+    url: 'https://example.com',
+    timeout: 600000  // 10 minutes
+  });
+  testdriver = result.testdriver;
+});
+
+test('first test', async () => {
+  // Reuses existing sandbox
+  await testdriver.find('login button').click();
+});
+
+test('second test', async () => {
+  // Same sandbox, faster execution
+  await testdriver.find('dashboard').click();
+});
+
+afterAll(async () => {
+  // Clean up sandbox
+  await testdriver.close();
+});
+```
+
+<Tip>
+  Persistent sandboxes are faster for test suites but share state between tests. Use fresh sandboxes when test isolation is critical.
+</Tip>
+
+## Sandbox Lifecycle
+
+Understanding how sandboxes are managed:
+
+<Steps>
+  <Step title="Provisioning">
+    When you call a preset (e.g., `chrome()`), TestDriver:
+    - Allocates a cloud VM
+    - Installs the OS and browser
+    - Configures network and display
+    - Returns ready-to-use testdriver instance
+    
+    **Time:** 5-15 seconds
+  </Step>
+
+  <Step title="Active Testing">
+    Your test runs in the isolated environment:
+    - Full browser/desktop control
+    - Network access
+    - File system access
+    - Video recording (Dashcam)
+    
+    **Time:** Duration of your test
+  </Step>
+
+  <Step title="Cleanup">
+    After the test completes:
+    - Dashcam replay saved
+    - Screenshots captured
+    - Sandbox terminated
+    - Resources released
+    
+    **Time:** Automatic
+  </Step>
+</Steps>
+
+## Reconnect to Sandboxes
+
+Debug failed tests by reconnecting to existing sandboxes:
+
+```javascript
+import { test } from 'vitest';
+import { TestDriver } from 'testdriverai';
+
+test('reconnectable sandbox', async () => {
+  const testdriver = new TestDriver({
+    apiKey: process.env.TD_API_KEY
+  });
+
+  const instance = await testdriver.connect();
+  console.log('Sandbox ID:', instance.instanceId);
+  
+  // Save this ID for debugging
+  // export TESTDRIVER_SANDBOX_ID=i-0abc123def
+  
+  await testdriver.find('button').click();
+});
+```
+
+Then reconnect later:
+
+```bash
+# Set sandbox ID
+export TESTDRIVER_SANDBOX_ID=i-0abc123def
+
+# Run debugging session
+node debug-script.js
+```
+
+<Card title="Debugging Guide" icon="bug" href="/v7/guides/debugging">
+  Complete guide to debugging with sandbox reconnection
+</Card>
+
+## Network Isolation
+
+Each sandbox is network-isolated by default:
+
+```javascript
+import { chrome } from 'testdriverai/presets';
+
+test('isolated network', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+
+  // Sandbox has its own IP address
+  // No shared cookies or cache with other tests
+  // Clean slate for every test run
+});
+```
+
+<Check>
+  Network isolation prevents test interference and ensures consistent results across runs.
+</Check>
+
+## Resource Limits
+
+Understanding sandbox constraints:
+
+<AccordionGroup>
+  <Accordion title="CPU & Memory">
+    - **CPU:** 2 vCPUs per sandbox
+    - **Memory:** 4GB RAM
+    - **Disk:** 20GB storage
+    
+    Sufficient for most testing scenarios including heavy web apps and desktop applications.
+  </Accordion>
+
+  <Accordion title="Network Bandwidth">
+    - **Speed:** 100 Mbps connection
+    - **Timeout:** 30s per network request
+    - **Proxies:** Supported via environment variables
+    
+    Fast enough for realistic load times and asset downloads.
+  </Accordion>
+
+  <Accordion title="Time Limits">
+    - **Default:** 2 minutes per test
+    - **Maximum:** 30 minutes (configurable)
+    - **Idle timeout:** 5 minutes of inactivity
+    
+    Customize with the `timeout` option in preset configuration.
+  </Accordion>
+
+  <Accordion title="Concurrent Sandboxes">
+    - **Free tier:** 2 concurrent sandboxes
+    - **Pro tier:** 10 concurrent sandboxes
+    - **Enterprise:** Unlimited concurrent sandboxes
+    
+    Run tests in parallel for faster CI/CD pipelines.
+  </Accordion>
+</AccordionGroup>
+
+## Cost & Billing
+
+Sandboxes are billed based on usage:
+
+<Card title="Pricing Model" icon="dollar-sign">
+  **Sandbox time:** Charged per minute of VM runtime
+  
+  - **Provisioning:** ~10 seconds (included)
+  - **Active testing:** Pay per minute
+  - **Cleanup:** Automatic (included)
+  
+  **Example costs:**
+  - 1-minute test: $0.02
+  - 5-minute test: $0.10
+  - 100 tests @ 2min each: $4.00
+  
+  **Optimization tips:**
+  - Use persistent sandboxes for test suites
+  - Enable caching to reduce test duration
+  - Run tests in parallel to maximize efficiency
+</Card>
+
+## Self-Hosted Sandboxes
+
+For enterprise customers who need on-premise infrastructure:
+
+```yaml docker-compose.yml
+version: '3'
+services:
+  testdriver-runner:
+    image: testdriver/runner:latest
+    environment:
+      - TD_API_KEY=${TD_API_KEY}
+      - TD_RUNNER_MODE=self-hosted
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+<Card title="Self-Hosting Guide" icon="server" href="/v7/guides/self-hosting">
+  Complete guide to running TestDriver on your own infrastructure
+</Card>
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card
+    title="Debugging Guide"
+    icon="bug"
+    href="/v7/guides/debugging"
+  >
+    Debug tests with sandbox reconnection
+  </Card>
+
+  <Card
+    title="Self-Hosting"
+    icon="server"
+    href="/v7/guides/self-hosting"
+  >
+    Run sandboxes on your infrastructure
+  </Card>
+
+  <Card
+    title="Performance Optimization"
+    icon="gauge-high"
+    href="/v7/guides/performance"
+  >
+    Optimize sandbox usage and costs
+  </Card>
+
+  <Card
+    title="Enterprise Features"
+    icon="building"
+    href="/v7/features/enterprise"
+  >
+    Enterprise sandbox capabilities
+  </Card>
+</CardGroup>