@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/dashcam.mdx

@@ -1,452 +1,119 @@
 ---
-title: "Dashcam"
+title: "Record tests with Dashcam"
 sidebarTitle: "Dashcam"
-description: "Record test execution with video and logs"
+description: "Every test is recorded as a video replay with logs, linked when the test ends."
 icon: "video"
 ---
 
-## Overview
+Dashcam records the sandbox screen while your test runs and saves it as a replay you can watch in the TestDriver console.
 
-Dashcam makes automatic video recordings. It also collects the logs for your tests. It captures screen recordings, application logs, and test details. You can review them later.
+- Recording is on by default. You don't need to configure anything.
+- The replay includes the console output from your test and, for websites, the page's network traffic.
+- When the test ends, TestDriver prints a link to the replay.
 
-## Basic Usage
+## How recording works
 
-### With Presets
+1. **A provision method starts it.** Every [provision method](/provision) starts Dashcam after it launches your app: `chrome()`, `chromeExtension()`, `vscode()`, `installer()`, `electron()`, and `dashcam()`.
+2. **The test runs.** Everything on the sandbox screen is recorded.
+3. **The test ends.** The [Vitest hook](/client#testdriver-context-options) stops the recording, uploads your test's console output to the replay, and prints the link:
 
-Most presets include Dashcam automatically:
-
-```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, make 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)
+```text
+🎥 Dashcam URL: https://console.testdriver.ai/replay/6789abcdef0123456789abcd
 ```
 
-### 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">
-      Dashcam API key for authentication. Set via `TD_API_KEY` environment variable.
-    </ParamField>
+`chrome()` also records the network traffic for the domain of the URL it opens.
 
-    <ParamField path="autoStart" type="boolean" default={false}>
-      Automatically start recording after authentication
-    </ParamField>
+When Vitest retries a failed test, each attempt gets its own recording and link.
 
-    <ParamField path="logs" type="array" default={[]}>
-      Log configurations to add automatically
-    </ParamField>
-  </Expandable>
-</ParamField>
+## Add a log file to the replay
 
-## Methods
+Call `provision.dashcam()` to show a log file from the sandbox next to the video. Call it before the method that launches your app, so the log is set up before recording starts:
 
-### auth()
+```javascript tests/checkout.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-Authenticate with Dashcam service:
+describe('Checkout', () => {
+  it('records the app log', async (context) => {
+    const testdriver = TestDriver(context);
 
-```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()
-```
+    await testdriver.provision.dashcam({
+      title: 'Checkout flow',
+      logPath: '/tmp/my-app.log',
+      logName: 'App log',
+    });
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-**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)
+    const result = await testdriver.assert('the login form is visible');
+    expect(result).toBe(true);
+  });
+});
 ```
 
-<ParamField path="application" type="string" required>
-  Application name to track
-</ParamField>
+TestDriver creates the file if it doesn't exist. Anything your app writes to it appears in the replay.
 
-<ParamField path="name" type="string" required>
-  Display name for the log
+<ParamField path="logPath" type="string">
+  The log file in the sandbox. Defaults to `/tmp/testdriver.log` on Linux, or `C:\Users\testdriver\testdriver.log` on Windows.
 </ParamField>
 
-**Returns:** `Promise<void>`
-
-**Example:**
-```javascript
-await dashcam.addApplicationLog('Google Chrome', 'Browser Logs');
-```
-
-### addWebLog()
-
-Track web request logs by URL pattern:
-
-```javascript
-await dashcam.addWebLog(pattern, name)
-```
-
-<ParamField path="pattern" type="string" required>
-  URL pattern to match (e.g., `"*example.com*"`)
+<ParamField path="logName" type="string" default="TestDriver Log">
+  The log's name in the replay.
 </ParamField>
 
-<ParamField path="name" type="string" required>
-  Display name for the log
+<ParamField path="webLogs" type="boolean" default="true">
+  Also record network traffic. It covers the domain opened with `chrome()` if that ran first, or all traffic otherwise.
 </ParamField>
 
-**Returns:** `Promise<void>`
-
-**Example:**
-```javascript
-await dashcam.addWebLog('*example.com*', 'Web 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'`, `'application'`, or `'web'`
-    </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>
-
-    <ParamField path="pattern" type="string">
-      URL pattern to match (required for type='web', e.g., `"*example.com*"`)
-    </ParamField>
-  </Expandable>
+<ParamField path="title" type="string">
+  The recording's title. Defaults to the test file's name and the test's name, such as `checkout - records the app log`.
 </ParamField>
 
-**Returns:** `Promise<void>`
+## Turn recording off
 
-**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'
-});
-
-await dashcam.addLog({
-  name: 'Web Logs',
-  type: 'web',
-  pattern: '*example.com*'
-});
-```
-
-### isRecording()
-
-Check if currently recording:
+Pass `dashcam: false` when you create the client:
 
 ```javascript
-await dashcam.isRecording()
+const testdriver = TestDriver(context, { dashcam: false });
 ```
 
-**Returns:** `Promise<boolean>` - True if recording is active
+Provision methods then skip recording, and the test prints no replay link.
 
-**Example:**
-```javascript
-if (await dashcam.isRecording()) {
-  console.log('Recording in progress');
-}
-```
-
-## Properties
-
-### recording
+## Control the recording yourself
 
-Current recording state:
+`testdriver.dashcam` gives you direct control of the recorder. Most tests don't need it, because the provision methods and the Vitest hook handle recording for you.
 
 ```javascript
-dashcam.recording // boolean
-```
-
-### apiKey
+await testdriver.dashcam.addApplicationLog('Google Chrome', 'Browser logs');
+await testdriver.dashcam.start();
 
-Configured API key:
+// ...test steps...
 
-```javascript
-dashcam.apiKey // string
+const replayUrl = await testdriver.dashcam.stop();
+console.log(replayUrl);
 ```
 
-### client
+| Method | What it does |
+| --- | --- |
+| `start()` | Starts recording. Does nothing if it's already recording. |
+| `stop()` | Stops recording and resolves to the replay URL, or `null` if there isn't one. |
+| `isRecording()` | Resolves to `true` while recording. |
+| `setTitle(title)` | Sets the title. Call it before `start()`. |
+| `addFileLog(path, name)` | Adds a log file from the sandbox to the replay. |
+| `addApplicationLog(application, name)` | Adds an application's logs to the replay. |
+| `addWebLog(pattern, name)` | Records network traffic for URLs matching `pattern`, such as `'*example.com*'`. |
+| `getElapsedTime()` | Milliseconds since recording started, or `null` when not recording. |
 
-Associated TestDriver client:
+Add logs before you call `start()`. If you call `stop()` yourself, the Vitest hook doesn't print the link, so log it as shown above.
 
-```javascript
-dashcam.client // TestDriver instance
-```
+With `dashcam: false`, these methods do nothing and `stop()` resolves to `null`.
 
-## Complete Examples
+<Note>
+  Older tests may use `chrome()` from `testdriverai/presets` to get a `dashcam` object. Presets are deprecated. Use `TestDriver(context)` and a provision method instead.
+</Note>
 
-### Basic Recording
+## Related
 
-```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');
-```
+- [Launch apps](/provision): the provision methods that start recording
+- [Debug a failing test](/debugging-with-screenshots): use the replay to find out why a test failed
+- [Test result JSON](/test-results-json): read the replay URL from a file after the run
+- [Options](/options#preview-and-recording): every client option