Skip to main content

​
Overview

Dashcam provides automatic video recording and log aggregation for your tests. It captures screen recordings, application logs, and test execution details — then produces a shareable replay URL for debugging failures and reviewing test runs. Dashcam recording is enabled by default when using TestDriver. You can disable it via dashcam: false in the client options.

​
Basic Usage

​
With Provision API

The simplest way to use Dashcam is through the provision API, which handles setup automatically: 
import TestDriver from 'testdriverai';

const testdriver = new TestDriver({ os: 'linux' });
await testdriver.ready();

// Provision automatically starts Dashcam recording
await testdriver.provision.chrome({ url: 'https://example.com' });

// Run your test
await testdriver.find('login button').click();

// Stop and get replay URL
const url = await testdriver.dashcam.stop();
console.log('Replay:', url);

​
With Provision Dashcam

You can explicitly provision Dashcam with additional options: 
await testdriver.provision.dashcam({
  title: 'Login Flow Test',
  logPath: '/tmp/my-app.log',
  logName: 'Application Log',
  webLogs: true,
});

​
Manual Setup

For full control, create a Dashcam instance directly: 
import TestDriver from 'testdriverai';
import Dashcam from 'testdriverai/lib/core/Dashcam.js';

const client = new TestDriver({ os: 'linux' });
await client.ready();

const dashcam = new Dashcam(client, {
  apiKey: process.env.DASHCAM_API_KEY,
  title: 'My Test Recording'
});

await dashcam.auth();
await dashcam.start();

// Run tests...

const url = await dashcam.stop();
console.log('Replay URL:', url);

​
Constructor

new Dashcam(client, options?)
​
client
TestDriver
required
TestDriver client instance that this Dashcam is attached to.
​
options
object
Configuration options.

​
Methods

​
auth()

Authenticate with the Dashcam service. Must be called before start() unless autoStart is true. 
await dashcam.auth(apiKey?)
​
apiKey
string
Override the API key set in the constructor.
Returns: Promise<void> Behavior:
  • Installs the Dashcam CLI via npm if not already present
  • Authenticates using the provided API key
  • If autoStart is true, automatically calls start() after authentication

​
start()

Start recording. Calls auth() automatically if not already authenticated. 
await dashcam.start()
Returns: Promise<void> Behavior:
  • If not yet authenticated, calls auth() first
  • Adds any configured log sources
  • Begins screen recording in the sandbox
  • Sets recording to true and records startTime

​
stop()

Stop recording and retrieve the replay URL. 
const url = await dashcam.stop()
Returns: Promise<string | null> — Replay URL, or null if no URL could be parsed. Behavior:
  • Sends stop command to the Dashcam CLI
  • Parses the CLI output for URLs matching replay/ or dashcam.io/testdriver.ai patterns
  • Sets recording to false
  • Returns the replay URL for sharing
const url = await dashcam.stop();
if (url) {
  console.log('Watch replay:', url);
}

​
setTitle()

Set or update the recording title. 
dashcam.setTitle(title)
​
title
string
required
New title for the recording.
Behavior: If not explicitly set, Dashcam generates a default title:
  1. From Vitest context: "testName - fileName"
  2. Fallback: timestamp-based format

​
addFileLog()

Track a log file in the recording. 
dashcam.addFileLog(path, name)
​
path
string
required
Absolute path to the log file on the sandbox.
​
name
string
required
Display name in the Dashcam replay.
// Linux/Mac
dashcam.addFileLog('/tmp/app.log', 'Application Log');

// Windows
dashcam.addFileLog('C:\\Users\\testdriver\\app.log', 'Application Log');

​
addApplicationLog()

Track application-specific logs (system log sources). 
dashcam.addApplicationLog(application, name)
​
application
string
required
Application name to track.
​
name
string
required
Display name in the replay.
dashcam.addApplicationLog('Google Chrome', 'Browser Logs');

​
addWebLog()

Track web traffic logs by URL pattern. 
dashcam.addWebLog(pattern, name)
​
pattern
string
required
URL pattern to match web requests.
​
name
string
required
Display name in the replay.
dashcam.addWebLog('*.example.com/*', 'API Traffic');

​
addLog()

Generic method to add any type of log source. 
dashcam.addLog(config)
​
config
LogConfig
required
Log configuration object.
dashcam.addLog({
  name: 'Test Output',
  type: 'file',
  path: '/tmp/test.log'
});

dashcam.addLog({
  name: 'Chrome Logs',
  type: 'application',
  application: 'Google Chrome'
});

dashcam.addLog({
  name: 'API Traffic',
  type: 'web',
  pattern: '*.api.example.com/*'
});

​
isRecording()

Check if currently recording. 
dashcam.isRecording() // boolean
Returns: boolean — true if recording is active.

​
getElapsedTime()

Get the elapsed recording time. 
dashcam.getElapsedTime() // number (ms)
Returns: number — Milliseconds since recording started. 
if (dashcam.isRecording()) {
  const elapsed = dashcam.getElapsedTime();
  console.log(`Recording for ${Math.round(elapsed / 1000)}s`);
}

​
Properties

PropertyTypeDefaultDescription
clientTestDriver—Parent SDK client instance
apiKeystring"4e93d8bf-..."Configured API key
autoStartbooleanfalseWhether recording auto-starts after auth
logsLogConfig[][]Configured log sources
recordingbooleanfalseCurrent recording state
startTimenumber | nullnullTimestamp when recording started
titlestring | nullnullRecording title

​
Static Methods

​
Dashcam.getConsoleUrl()

Map an API root URL to the corresponding console URL. 
Dashcam.getConsoleUrl(apiRoot) // string

​
Types

interface DashcamOptions {
  apiKey?: string;
  autoStart?: boolean;
  logs?: LogConfig[];
  title?: string;
}

interface LogConfig {
  name: string;
  type: 'file' | 'stdout' | 'application' | 'web';
  path?: string;           // Required for type: 'file'
  application?: string;    // Required for type: 'application'
  pattern?: string;        // Required for type: 'web'
}

​
Disabling Dashcam

​
In Client Options

const testdriver = new TestDriver({
  dashcam: false  // Disable recording entirely
});

​
In Provision

await testdriver.provision.chrome({
  url: 'https://example.com',
  // Dashcam disabled at client level
});

​
Platform Differences

​
Windows

On Windows, Dashcam uses PowerShell commands and installs via npm: 
dashcam.addFileLog(
  'C:\\Users\\testdriver\\Documents\\testdriver.log',
  'TestDriver Log'
);
The default log path is C:\\Users\\testdriver\\testdriver.log.

​
Linux/Mac

On Linux/Mac, Dashcam uses shell commands: 
dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
The default log path is /tmp/testdriver.log.

​
Examples

​
Recording with Multiple Log Sources

const testdriver = new TestDriver({ os: 'linux' });
await testdriver.ready();

const dashcam = testdriver.dashcam;
await dashcam.auth();

// Add multiple log sources before starting
dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
dashcam.addFileLog('/tmp/app.log', 'Application Log');
dashcam.addApplicationLog('Google Chrome', 'Browser Logs');
dashcam.addWebLog('*.api.example.com/*', 'API Traffic');

await dashcam.start();

// Run tests
await testdriver.provision.chrome({ url: 'https://example.com' });
await testdriver.find('login button').click();

const url = await dashcam.stop();
console.log('Replay with logs:', url);

​
Auto-start Configuration

const dashcam = new Dashcam(client, {
  autoStart: true,
  title: 'Login Flow Test',
  logs: [
    { name: 'App Log', type: 'file', path: '/tmp/app.log' },
    { name: 'Browser', type: 'application', application: 'Google Chrome' }
  ]
});

await dashcam.auth(); // Automatically starts recording

// Run tests
await client.find('submit button').click();

const url = await dashcam.stop();
console.log('Replay:', url);

​
Checking Recording Status

await dashcam.start();
console.log('Recording:', dashcam.isRecording()); // true

// After some test actions...
const elapsed = dashcam.getElapsedTime();
console.log(`Recorded ${Math.round(elapsed / 1000)} seconds`);

const url = await dashcam.stop();
console.log('Recording:', dashcam.isRecording()); // false