testdriverai 7.3.11 → 7.3.13

package/.github/skills/testdriver:cloud/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: testdriver:cloud
+description: The fastest way to get started with TestDriver. Just set your API key and start testing.
+---
+<!-- Generated from cloud.mdx. DO NOT EDIT. -->
+
+Cloud pricing is based on **device-seconds**: the amount of time your tests run on **our infrastructure**.
+
+- **Zero Setup** — Start testing immediately. No DevOps required.
+- **Free Tier** — Get started with a limited preview at no cost.
+- **Pay As You Go** — Only pay for the device-seconds you use.
+
+## Get Started
+Cloud is the default when you follow the Quickstart guide. 
+<Card
+  title="Try the Quickstart"  
+  icon="play"
+  href="/v7/quickstart"
+>
+  Set your API key and start testing in minutes.
+</Card>
+
+## Parallel Testing Limits
+
+Your account has a set number of **license slots** that determine how many devices can run simultaneously. You can view your available slots in the [TestDriver Dashboard](https://console.testdriver.ai).
+
+<Info>
+  **When is a slot in use?** A license slot is occupied when a test client is connected. As soon as your device is destroyed the slot becomes available immediately.
+</Info>
+
+## Avoiding Slot Conflicts
+
+To prevent tests from failing due to exceeding your license slot limit, we recommend two key configurations:
+
+<AccordionGroup>
+  <Accordion title="Set Maximum Concurrency in Vitest">
+    Limit concurrent tests to match your available license slots:
+
+    ```javascript vitest.config.mjs
+    import { defineConfig } from 'vitest/config';
+    import { TestDriver } from 'testdriverai/vitest';
+
+    export default defineConfig({
+      test: {
+        testTimeout: 900000,
+        hookTimeout: 900000,
+        maxConcurrency: 5, // Set to your license slot limit
+        reporters: ['default', TestDriver()],
+        setupFiles: ['testdriverai/vitest/setup'],
+      },
+    });
+    ```
+
+    <Tip>
+      Check your slot count at [console.testdriver.ai](https://console.testdriver.ai) and set `maxConcurrency` to that number or lower.
+    </Tip>
+  </Accordion>
+
+  <Accordion title="Use GitHub Concurrency Keys">
+    Prevent multiple workflow runs from competing for the same slots by using [GitHub's concurrency controls](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs):
+
+    ```yaml .github/workflows/test.yml
+    name: Tests
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+
+    # Prevent concurrent runs from competing for license slots
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          
+          - name: Setup Node.js
+            uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+          
+          - name: Install dependencies
+            run: npm install
+          
+          - name: Run tests
+            run: vitest run
+            env:
+              TD_API_KEY: ${{ secrets.TD_API_KEY }}
+    ```
+
+    The `concurrency` block ensures:
+    - Only one workflow run per branch runs at a time
+    - New pushes cancel in-progress runs on the same branch
+    - Different branches/PRs can run in parallel (up to your slot limit)
+  </Accordion>
+</AccordionGroup>
+
+## When to Consider Self-Hosted
+
+Cloud is perfect for getting started and for teams that want zero infrastructure management. However, you might consider [Self-Hosted](/v7/self-hosted) if you:
+
+- Want to escape per-second billing with a flat license fee
+- Require greater concurrency than offered in Cloud plans
+- Need full control over your infrastructure and privacy
+- Want to use your own AI API keys
+- Require custom hardware configurations
+- Have high test volumes that make self-hosting more economical
+
+<Card
+  title="Explore Self-Hosted"
+  icon="server"
+  href="/v7/self-hosted"
+>
+  Learn about self-hosting for unlimited test execution at a flat rate.
+</Card>

package/.github/skills/testdriver:customizing-devices/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: testdriver:customizing-devices
+description: Configure TestDriver sandbox options and environment settings
+---
+<!-- Generated from customizing-devices.mdx. DO NOT EDIT. -->
+
+## TestDriver Options
+
+Configure TestDriver behavior with options passed to the `TestDriver()` function:
+
+```javascript
+const testdriver = TestDriver(context, {
+  reconnect: false,
+});
+```
+
+### Preview Mode
+
+Control how test execution is visualized. The `preview` option determines where the live debugger view opens:
+
+```javascript
+const testdriver = TestDriver(context, {
+  preview: "browser",  // Opens in default browser (default)
+});
+```
+
+| Value | Description |
+|-------|-------------|
+| `"browser"` | Opens debugger in default browser (default) |
+| `"ide"` | Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension) |
+| `"none"` | Headless mode, no visual preview |
+
+**IDE Preview**
+
+For the best development experience, use `preview: "ide"` with the TestDriver extension for VSCode or Cursor:
+
+```javascript
+const testdriver = TestDriver(context, {
+  preview: "ide",  // Opens preview in IDE panel
+});
+```
+
+**Headless Mode**
+
+Run tests without any visual preview. Useful for CI/CD pipelines:
+
+```javascript
+const testdriver = TestDriver(context, {
+  preview: "none",  // No visual preview (headless)
+});
+```
+
+<Note>
+  The legacy `headless: true` option still works for backward compatibility and maps to `preview: "none"`.
+</Note>
+
+### IP Target
+
+If self-hosting TestDriver, use `ip` to specify the device IP. See [Self-Hosting TestDriver](../self-hosting.md) for details.
+
+```javascript
+const testdriver = TestDriver(context, {
+  ip: "203.0.113.42",  // Your allowlisted IP
+});
+```
+
+### Operating System
+
+Set the `os` property to run tests on a specific operating system. Available options are `linux` (default) and `windows`.
+
+```javascript
+const testdriver = TestDriver(context, {
+  os: "windows",  // Run on Windows sandbox
+});
+```
+
+#### Using Environment Variables
+
+You can make the operating system configurable via environment variables. This requires adding code to read from `process.env` in your test:
+
+```javascript
+const testdriver = TestDriver(context, {
+  os: process.env.TD_OS || "linux",  // Read from env, default to Linux
+});
+```
+
+Then pass the variable when running tests:
+
+```bash
+# Run tests on Windows
+TD_OS=windows vitest run
+
+# Run tests on Linux (default)
+TD_OS=linux vitest run
+```
+
+This pattern is useful for running the same test suite across multiple operating systems in CI/CD:
+
+```yaml
+# Example GitHub Actions matrix
+strategy:
+  matrix:
+    os: [linux, windows]
+steps:
+  - run: TD_OS=${{ matrix.os }} vitest run
+```
+
+## Keepalive
+
+By default, sandboxes terminate immediately when the test finishes. Set this value to keep the sandbox alive for reconnection.
+
+The `keepAlive` param enables you to keep the sandbox running after the test completes for debugging or reconnection.  This will allow you to use the debugger to inspect the state of the device after the test has finished.
+
+```javascript
+const testdriver = TestDriver(context, {
+  keepAlive: 300000,  // Keep sandbox alive for 5 minutes after test
+});
+```
+
+### Reconnecting to Existing Sandbox
+
+Speed up test development by reconnecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
+
+Split your test into two files: one for known-good steps that set up the desired state, and another for work-in-progress steps you want to debug.
+
+```javascript known-good.test.mjs
+const testdriver = TestDriver(context, {
+  keepAlive: 60000,  // Keep sandbox alive for 60 seconds after test
+});
+```
+
+```javascript work-in-progress.test.mjs
+// Second test file: experiment.test.mjs (run within keepAlive window)
+const testdriver = TestDriver(context, {
+  reconnect: true,  // Reconnect to existing sandbox
+});
+```
+
+Then, you can run both tests in sequence:
+
+```bash
+vitest run -t known-good.test.mjs -t work-in-progress.test.mjs
+```
+
+And as you make changes to `work-in-progress.test.mjs`, you can re-run just that file to quickly iterate on the failing steps.
+
+```bash
+vitest run work-in-progress.test.mjs
+```
+
+<Warning>
+  Reconnect only works if run within the `keepAlive` window of the previous test.
+</Warning>

package/.github/skills/testdriver:dashcam/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: testdriver:dashcam
+description: Record test execution with video and logs
+---
+<!-- Generated from dashcam.mdx. DO NOT EDIT. -->
+
+## Overview
+
+Dashcam provides automatic video recording and log aggregation for your tests. It captures screen recordings, application logs, and test execution details that can be reviewed later.
+
+## Basic Usage
+
+### With Presets
+
+Most presets automatically include Dashcam:
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { testdriver, dashcam } = await chrome(context, {
+    url: 'https://example.com'
+  });
+  
+  // Test executes with recording automatically
+  await testdriver.find('login button').then(el => el.click());
+  
+  // Dashcam URL available after test
+  console.log('Replay:', dashcam.url);
+});
+```
+
+### Manual Setup
+
+For more control, create a Dashcam instance directly:
+
+```javascript
+import TestDriver from 'testdriverai';
+import Dashcam from 'testdriverai/lib/core/Dashcam.js';
+
+const client = await TestDriver.create({ os: 'linux' });
+const dashcam = new Dashcam(client, {
+  apiKey: process.env.DASHCAM_API_KEY
+});
+
+await dashcam.auth();
+await dashcam.start();
+
+// Run your tests
+
+const url = await dashcam.stop();
+console.log('Replay URL:', url);
+```
+
+## Constructor
+
+Create a new Dashcam instance:
+
+```javascript
+new Dashcam(client, options)
+```
+
+### Parameters
+
+<ParamField path="client" type="TestDriver" required>
+  TestDriver client instance
+</ParamField>
+
+<ParamField path="options" type="object">
+  Configuration options
+
+  <Expandable title="options properties">
+    <ParamField path="apiKey" type="string" default="4e93d8bf-3886-4d26-a144-116c4063522d">
+      Dashcam API key for authentication
+    </ParamField>
+
+    <ParamField path="autoStart" type="boolean" default={false}>
+      Automatically start recording after authentication
+    </ParamField>
+
+    <ParamField path="logs" type="array" default={[]}>
+      Log configurations to add automatically
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Methods
+
+### auth()
+
+Authenticate with Dashcam service:
+
+```javascript
+await dashcam.auth(apiKey)
+```
+
+<ParamField path="apiKey" type="string" optional>
+  Override the API key set in constructor
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await dashcam.auth('your-api-key');
+```
+
+### start()
+
+Start recording:
+
+```javascript
+await dashcam.start()
+```
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await dashcam.start();
+console.log('Recording started');
+```
+
+### stop()
+
+Stop recording and retrieve replay URL:
+
+```javascript
+await dashcam.stop()
+```
+
+**Returns:** `Promise<string|null>` - Replay URL if available
+
+**Example:**
+```javascript
+const url = await dashcam.stop();
+if (url) {
+  console.log('Watch replay:', url);
+} else {
+  console.log('No replay URL available');
+}
+```
+
+### addFileLog()
+
+Track a log file in the recording:
+
+```javascript
+await dashcam.addFileLog(path, name)
+```
+
+<ParamField path="path" type="string" required>
+  Path to the log file
+</ParamField>
+
+<ParamField path="name" type="string" required>
+  Display name for the log in Dashcam
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+// Linux/Mac
+await dashcam.addFileLog('/tmp/app.log', 'Application Log');
+
+// Windows
+await dashcam.addFileLog('C:\\logs\\app.log', 'Application Log');
+```
+
+### addApplicationLog()
+
+Track application-specific logs:
+
+```javascript
+await dashcam.addApplicationLog(application, name)
+```
+
+<ParamField path="application" type="string" required>
+  Application name to track
+</ParamField>
+
+<ParamField path="name" type="string" required>
+  Display name for the log
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await dashcam.addApplicationLog('Google Chrome', 'Browser Logs');
+```
+
+### addLog()
+
+Generic method to add any type of log:
+
+```javascript
+await dashcam.addLog(config)
+```
+
+<ParamField path="config" type="object" required>
+  Log configuration
+
+  <Expandable title="config properties">
+    <ParamField path="name" type="string" required>
+      Display name for the log
+    </ParamField>
+
+    <ParamField path="type" type="string" required>
+      Log type: `'file'`, `'stdout'`, or `'application'`
+    </ParamField>
+
+    <ParamField path="path" type="string">
+      File path (required for type='file')
+    </ParamField>
+
+    <ParamField path="application" type="string">
+      Application name (required for type='application')
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await dashcam.addLog({
+  name: 'Test Output',
+  type: 'file',
+  path: '/tmp/test.log'
+});
+
+await dashcam.addLog({
+  name: 'Chrome Logs',
+  type: 'application',
+  application: 'Google Chrome'
+});
+```
+
+### isRecording()
+
+Check if currently recording:
+
+```javascript
+await dashcam.isRecording()
+```
+
+**Returns:** `Promise<boolean>` - True if recording is active
+
+**Example:**
+```javascript
+if (await dashcam.isRecording()) {
+  console.log('Recording in progress');
+}
+```
+
+## Properties
+
+### recording
+
+Current recording state:
+
+```javascript
+dashcam.recording // boolean
+```
+
+### apiKey
+
+Configured API key:
+
+```javascript
+dashcam.apiKey // string
+```
+
+### client
+
+Associated TestDriver client:
+
+```javascript
+dashcam.client // TestDriver instance
+```
+
+## Complete Examples
+
+### Basic Recording
+
+```javascript
+import { test } from 'vitest';
+import TestDriver from 'testdriverai';
+import Dashcam from 'testdriverai/lib/core/Dashcam.js';
+
+test('record test execution', async () => {
+  const client = await TestDriver.create({ os: 'linux' });
+  const dashcam = new Dashcam(client);
+  
+  await dashcam.auth();
+  await dashcam.start();
+  
+  // Run your test
+  await client.find('button').then(el => el.click());
+  
+  const url = await dashcam.stop();
+  console.log('Replay:', url);
+  
+  await client.cleanup();
+});
+```
+
+### With Log Tracking
+
+```javascript
+test('record with logs', async () => {
+  const client = await TestDriver.create({ os: 'linux' });
+  const dashcam = new Dashcam(client);
+  
+  await dashcam.auth();
+  
+  // Add log files before starting
+  await dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
+  await dashcam.addFileLog('/tmp/app.log', 'Application Log');
+  
+  await dashcam.start();
+  
+  // Test execution
+  await client.find('login button').then(el => el.click());
+  
+  const url = await dashcam.stop();
+  console.log('Replay with logs:', url);
+  
+  await client.cleanup();
+});
+```
+
+### Auto-start Configuration
+
+```javascript
+test('auto-start recording', async () => {
+  const client = await TestDriver.create({ os: 'linux' });
+  const dashcam = new Dashcam(client, {
+    autoStart: true,
+    logs: [
+      {
+        name: 'App Log',
+        type: 'file',
+        path: '/tmp/app.log'
+      }
+    ]
+  });
+  
+  await dashcam.auth(); // Automatically starts recording
+  
+  // Test execution
+  await client.find('submit button').then(el => el.click());
+  
+  const url = await dashcam.stop();
+  console.log('Replay:', url);
+  
+  await client.cleanup();
+});
+```
+
+### Using with Presets
+
+```javascript
+import { chrome } from 'testdriverai/presets';
+
+test('preset with dashcam', async (context) => {
+  const { testdriver, dashcam } = await chrome(context, {
+    url: 'https://example.com',
+    dashcam: true // Enabled by default
+  });
+  
+  // Test runs with automatic recording
+  await testdriver.find('button').then(el => el.click());
+  
+  // URL automatically available
+  console.log('Replay:', dashcam.url);
+});
+```
+
+### Disabling Dashcam in Presets
+
+```javascript
+test('without dashcam', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com',
+    dashcam: false // Disable recording
+  });
+  
+  // Test runs without recording (faster)
+  await testdriver.find('button').then(el => el.click());
+});
+```
+
+## Platform Differences
+
+### Windows
+
+On Windows, Dashcam uses PowerShell commands and installs via npm:
+
+```javascript
+// Windows-specific paths
+await dashcam.addFileLog(
+  'C:\\Users\\testdriver\\Documents\\testdriver.log',
+  'TestDriver Log'
+);
+```
+
+### Linux/Mac
+
+On Linux/Mac, Dashcam uses shell commands:
+
+```javascript
+// Unix-specific paths
+await dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
+```