Dashcam

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:

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:

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:

new Dashcam(client, options)

Parameters

client

TestDriver

required

TestDriver client instance

options

object

Configuration options

Show options properties

apiKey

string

default:"4e93d8bf-3886-4d26-a144-116c4063522d"

Dashcam API key for authentication

autoStart

boolean

default:false

Automatically start recording after authentication

logs

array

Log configurations to add automatically

Methods

auth()

Authenticate with Dashcam service:

await dashcam.auth(apiKey)

apiKey

string

Override the API key set in constructor

Returns: Promise<void> Example:

await dashcam.auth('your-api-key');

start()

Start recording:

await dashcam.start()

Returns: Promise<void> Example:

await dashcam.start();
console.log('Recording started');

stop()

Stop recording and retrieve replay URL:

await dashcam.stop()

Returns: Promise<string|null> - Replay URL if available Example:

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:

await dashcam.addFileLog(path, name)

path

string

required

Path to the log file

name

string

required

Display name for the log in Dashcam

Returns: Promise<void> Example:

// 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:

await dashcam.addApplicationLog(application, name)

application

string

required

Application name to track

name

string

required

Display name for the log

Returns: Promise<void> Example:

await dashcam.addApplicationLog('Google Chrome', 'Browser Logs');

addLog()

Generic method to add any type of log:

await dashcam.addLog(config)

config

object

required

Log configuration

Show config properties

name

string

required

Display name for the log

type

string

required

Log type: 'file', 'stdout', or 'application'

path

string

File path (required for type=‘file’)

application

string

Application name (required for type=‘application’)

Returns: Promise<void> Example:

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:

await dashcam.isRecording()

Returns: Promise<boolean> - True if recording is active Example:

if (await dashcam.isRecording()) {
  console.log('Recording in progress');
}

Properties

recording

Current recording state:

dashcam.recording // boolean

apiKey

Configured API key:

dashcam.apiKey // string

client

Associated TestDriver client:

dashcam.client // TestDriver instance

Complete Examples

Basic Recording

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

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

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

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

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:

// Windows-specific paths
await dashcam.addFileLog(
  'C:\\Users\\testdriver\\Documents\\testdriver.log',
  'TestDriver Log'
);

Linux/Mac

On Linux/Mac, Dashcam uses shell commands:

// Unix-specific paths
await dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');

Troubleshooting

No Replay URL Returned

If stop() returns null:

Check that recording was started with start()
Verify authentication succeeded
Ensure dashcam CLI is installed in the environment
Check console output for error messages

Recording Not Starting

If recording doesn’t start:

Verify API key is correct
Check auth() completed successfully
Ensure dashcam CLI is installed globally
Check isRecording() to verify state

Logs Not Appearing

If logs aren’t visible in replay:

Add logs before calling start()
Verify log file paths are correct
Ensure log files exist and are accessible
Check file permissions

Best Practices

Always authenticate before starting

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

Add logs before starting recording

await dashcam.addFileLog('/tmp/app.log', 'App Log');
await dashcam.start();

Always stop recording

Use try/finally to ensure recording stops:

try {
  await dashcam.start();
  // Test code
} finally {
  await dashcam.stop();
}

Check for replay URL

const url = await dashcam.stop();
if (url) {
  console.log('Replay:', url);
} else {
  console.warn('No replay URL available');
}

Overview

Getting Started

Examples

Actions

API Reference

Overview

Basic Usage

With Presets

Manual Setup

Constructor

Parameters

Methods

auth()

start()

stop()

addFileLog()

addApplicationLog()

addLog()

isRecording()

Properties

recording

apiKey

client

Complete Examples

Basic Recording

With Log Tracking

Auto-start Configuration

Using with Presets

Disabling Dashcam in Presets

Platform Differences

Windows

Linux/Mac

Troubleshooting

No Replay URL Returned

Recording Not Starting

Logs Not Appearing

Best Practices

See Also

Overview

Getting Started

Examples

Actions

API Reference

​Overview

​Basic Usage

​With Presets

​Manual Setup

​Constructor

​Parameters

​Methods

​auth()

​start()

​stop()

​addFileLog()

​addApplicationLog()

​addLog()

​isRecording()

​Properties

​recording

​apiKey

​client

​Complete Examples

​Basic Recording

​With Log Tracking

​Auto-start Configuration

​Using with Presets

​Disabling Dashcam in Presets

​Platform Differences

​Windows

​Linux/Mac

​Troubleshooting

​No Replay URL Returned

​Recording Not Starting

​Logs Not Appearing

​Best Practices

​See Also

Overview

Basic Usage

With Presets

Manual Setup

Constructor

Parameters

Methods

auth()

start()

stop()

addFileLog()

addApplicationLog()

addLog()

isRecording()

Properties

recording

apiKey

client

Complete Examples

Basic Recording

With Log Tracking

Auto-start Configuration

Using with Presets

Disabling Dashcam in Presets

Platform Differences

Windows

Linux/Mac

Troubleshooting

No Replay URL Returned

Recording Not Starting

Logs Not Appearing

Best Practices

See Also