testdriverai 6.2.1 → 7.0.0

package/docs/AWESOME_LOGS_QUICK_REF.md

@@ -0,0 +1,100 @@
+# AWESOME Logs - Quick Reference 🎨
+
+## At a Glance
+
+Your TestDriver SDK now has **beautiful, emoji-rich logs** with great DX!
+
+### What You'll See
+
+```
+[2.34s] 🔍 Found "submit button" · 📍 (682, 189) · ⏱️ 167ms · ⚡ cached
+[2.51s] 👆 Click "submit button"
+[2.67s] 👉 Hover "menu item"
+[2.89s] ⌨️ Type → hello world
+[3.12s] ✅ Assert "page title correct" · ✓ PASSED · ⏱️ 45ms
+```
+
+## Quick Emoji Guide
+
+| Emoji | Meaning |
+|-------|---------|
+| 🔍 | Finding element |
+| 👆 | Click |
+| 👉 | Hover |
+| ⌨️ | Type |
+| 📜 | Scroll |
+| ✅ | Success/Passed |
+| ❌ | Error/Failed |
+| ⚡ | Cache hit |
+| 💤 | Cache miss |
+| 📍 | Coordinates |
+| ⏱️ | Duration |
+| 🔌 | Connect/Disconnect |
+| 📸 | Screenshot |
+
+## Performance Colors
+
+Duration times are color-coded:
+
+- **🟢 < 100ms** - Fast
+- **🟡 100-500ms** - Acceptable  
+- **🔴 > 500ms** - Slow
+
+## Enable/Disable
+
+```javascript
+// Enabled by default
+const client = new TestDriver(apiKey, {
+  logging: true
+});
+
+// Disable if needed
+client.setLogging(false);
+```
+
+## Debug Mode
+
+For detailed cache information:
+
+```bash
+VERBOSE=true node your-test.js
+```
+
+You'll see:
+- Cache strategy (image/text)
+- Similarity scores
+- Pixel diff percentages
+- Cache age
+
+## Examples
+
+Try these:
+
+```bash
+# Simple example
+TD_API_KEY=your_key node examples/sdk-simple-example.js
+
+# Full demo
+TD_API_KEY=your_key node examples/sdk-awesome-logs-demo.js
+
+# Cache demo with debug info
+TD_API_KEY=your_key VERBOSE=true node examples/sdk-cache-thresholds.js
+```
+
+## Custom Formatting
+
+```javascript
+const { formatter } = require('testdriverai/sdk-log-formatter');
+
+console.log(formatter.formatHeader('My Test', '🧪'));
+console.log(formatter.formatAction('click', 'button'));
+console.log(formatter.formatProgress(3, 10, 'Processing'));
+```
+
+## Full Documentation
+
+See [SDK_AWESOME_LOGS.md](./SDK_AWESOME_LOGS.md) for complete documentation.
+
+---
+
+**Enjoy your AWESOME logs! 🎨✨**

package/docs/QUICK_START_TEST_RECORDING.md

@@ -0,0 +1,215 @@
+# 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://testdriver-api.onrender.com',
+    }),
+  ],
+});
+```
+
+### 2. Set API Key
+
+```bash
+export TD_API_KEY="your-api-key-here"
+```
+
+Get your API key from: https://app.testdriver.ai/settings/api-keys
+
+### 3. Run Tests
+
+```bash
+npx vitest run
+```
+
+That's it! Your tests are now being recorded. View results at:
+https://app.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: npx vitest run
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+test:
+  script:
+    - npm install
+    - npx 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/models/TdSandbox.js` - Sandbox tracking 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 `npx 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://app.testdriver.ai
+- API Reference: /cli/docs/TEST_RECORDING.md