# Quick Start: TestDriver Test Recording

## What You Get

- 📊 Track all test runs in the TestDriver dashboard
- 🎥 Link dashcam screen recordings to specific tests  
- 🔄 Integrate with CI/CD (GitHub Actions, GitLab, etc.)
- 🐛 View exact replay of failed tests
- 📈 Track test performance and flakiness over time

## Setup (5 minutes)

### 1. Add Vitest Plugin

```javascript
// vitest.config.mjs
import { defineConfig } from 'vitest/config';
import testDriverPlugin from './interfaces/vitest-plugin.mjs';

export default defineConfig({
  plugins: [
    testDriverPlugin({
      apiKey: process.env.TD_API_KEY,
      apiRoot: process.env.TD_API_ROOT || 'https://api.testdriver.ai',
    }),
  ],
});
```

### 2. Set API Key

```bash
export TD_API_KEY="your-api-key-here"
```

Get your API key from: https://console.testdriver.ai/settings/api-keys

### 3. Run Tests

```bash
vitest run
```

That's it! Your tests are now being recorded. View results at:
https://console.testdriver.ai/dashboard/test-runs

## With Dashcam (Optional)

To link screen recordings with tests, simply register the dashcam URL after your test completes:

```javascript
import { test } from 'vitest';
import TestDriver from '@testdriverai/sdk';

test('my test', async () => {
  const client = await TestDriver({ apiKey: 'your-api-key' });
  
  // Run your test...
  await client.get('https://example.com');
  
  // Get dashcam URL and register it
  const dashcamUrl = await client.dashcam.publish();
  
  // Register with the plugin - it will automatically associate with this test
  if (globalThis.__testdriverPlugin) {
    globalThis.__testdriverPlugin.registerDashcamUrl(
      'my-test-id', // Or use task.id in Vitest context
      dashcamUrl,
      client.os
    );
  }
  
  await client.disconnect();
});
```

The plugin automatically tracks all dashcam URLs in memory (no temp files needed!) and associates them with test results.

## CI/CD Integration

### GitHub Actions

```yaml
# .github/workflows/test.yml
name: Tests
on: [push]
jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: vitest run
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
```

### GitLab CI

```yaml
# .gitlab-ci.yml
test:
  script:
    - npm install
    - vitest run
  variables:
    TD_API_KEY: $CI_JOB_TOKEN
```

The reporter automatically detects CI environment and records:
- Git repo, branch, commit
- CI provider and run URL
- Test results and timing

## What Gets Recorded

### Test Run
- Suite name and platform
- Total/passed/failed counts
- Duration
- CI/CD metadata
- Git commit info

### Each Test
- Test name and file
- Pass/fail status
- Error messages (if failed)
- Duration
- Dashcam replay link (if available)

## View Results

Dashboard shows:
- All test runs with filters
- Drill down to individual tests
- Embedded dashcam replay player
- Link to CI/CD runs
- Test history and trends

## SDK Methods

Use in your test code:

```javascript
// Create test run
const testRun = await client.createTestRun({
  runId: 'unique-id',
  suiteName: 'My Tests',
  platform: 'windows'
});

// Record test result
await client.recordTestCase({
  runId: 'unique-id',
  testName: 'my test',
  status: 'passed',
  replayUrl: 'https://app.dashcam.io/replay/abc'
});

// Complete run
await client.completeTestRun({
  runId: 'unique-id',
  status: 'passed'
});
```

## Troubleshooting

**Reporter not recording?**
- Check `TD_API_KEY` is set
- Verify network connectivity to TestDriver API
- Look for reporter logs in test output

**No dashcam link?**
- Ensure dashcam publishes and outputs replay URL
- Check test logs for replay URL output
- Manually set `DASHCAM_REPLAY_URL` if needed

**CI metadata missing?**
- CI environment variables must be available
- Supported: GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins

## Files Created

**API (Backend)**
- `api/models/TdTestRun.js` - Test run model
- `api/models/TdTestCase.js` - Test case model
- `api/controllers/testdriver/testdriver-test-run-create.js` - Create test run endpoint
- `api/controllers/testdriver/testdriver-test-run-complete.js` - Complete test run endpoint
- `api/controllers/testdriver/testdriver-test-case-create.js` - Record test case endpoint

**CLI/SDK**
- `cli/interfaces/vitest-plugin.mjs` - Vitest plugin for test recording
- `cli/sdk.js` - Added createTestRun(), recordTestCase(), completeTestRun() methods

**Documentation**
- `cli/docs/TEST_RECORDING.md` - Complete guide
- `cli/docs/ARCHITECTURE.md` - Technical architecture
- `cli/vitest.config.example.js` - Example config
- `cli/examples/test-recording-example.test.js` - Example test
- `cli/examples/run-tests-with-recording.sh` - Example script

## Next Steps

1. **Try it out**: Run `vitest run` and check the dashboard
2. **Add dashcam**: Record your tests with screen capture
3. **Set up CI/CD**: Add to your pipeline for continuous tracking
4. **Build dashboard UI**: Create Vue components to visualize test runs (next phase)

## Support

- Documentation: https://docs.testdriver.ai
- Dashboard: https://console.testdriver.ai
- API Reference: /cli/docs/TEST_RECORDING.md