# GitHub Comment Integration

TestDriver can automatically post beautiful, formatted comments to your GitHub pull requests and commits with test results, including dashcam replays, exceptions, and detailed statistics.

## Features

- 📊 **Test Results Summary** - Pass/fail statistics and duration
- 🎥 **Dashcam GIF Replays** - Embedded GIF previews with links to full replays
- ❌ **Exception Details** - Error messages and stack traces for failed tests
- 📋 **Detailed Test Table** - Status, file, duration, and replay link for each test
- 🔄 **Auto-update** - Updates existing comment instead of creating duplicates
- 🎨 **Beautiful Formatting** - Professional markdown with emojis and badges

## Setup

### 1. Enable in CI Environment

Set the required environment variables in your CI workflow:

#### GitHub Actions

```yaml
name: TestDriver Tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run TestDriver tests
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
        run: npm run test:sdk
```

**Important:** For pull request events, `GITHUB_PR_NUMBER` must be explicitly set from `github.event.pull_request.number`.

### 2. Environment Variables

| Variable | Description | Required | Example |
|----------|-------------|----------|---------|
| `TD_API_KEY` | TestDriver API key | ✅ Yes | Get from [console.testdriver.ai](https://console.testdriver.ai/team) |
| `GITHUB_TOKEN` | GitHub token with PR write permissions | ✅ Yes | Automatically available in GitHub Actions |
| `GITHUB_PR_NUMBER` | Pull request number | For PR comments | `123` |
| `GITHUB_SHA` | Commit SHA | For commit comments | Automatically set in GitHub Actions |

**Token Alternatives:**
- `GITHUB_TOKEN` (preferred)
- `GH_TOKEN` (alternative)

### 3. Comment Destinations

TestDriver will post comments based on available context:

- **Pull Request Comment** - If `GITHUB_PR_NUMBER` is set (recommended)
- **Commit Comment** - If only `GITHUB_SHA` is available (fallback)

## Example Comment

Here's what a TestDriver GitHub comment looks like:

---

# 🟢 TestDriver Test Results

**Status:** ✅ PASSED  
**Duration:** 2m 34s  
**Platform:** linux  
**Branch:** `feature/new-test`  
**Commit:** `a1b2c3d`

## 📊 Test Summary

```
Total:   5
Passed:  4 ✅
Failed:  1 ❌
Skipped: 0 ⏭️
```

### [📋 View Full Test Run](https://console.testdriver.ai/runs/123)

## 📝 Test Results

| Status | Test | File | Duration | Replay |
|--------|------|------|----------|--------|
| ✅ | should login successfully | `tests/auth.test.mjs` | 12.5s | [🎥 View](https://console.testdriver.ai/replay/abc123) |
| ✅ | should add item to cart | `tests/cart.test.mjs` | 8.2s | [🎥 View](https://console.testdriver.ai/replay/def456) |
| ❌ | should complete checkout | `tests/checkout.test.mjs` | 15.3s | [🎥 View](https://console.testdriver.ai/replay/ghi789) |

## 🎥 Dashcam Replays

### should login successfully

[![should login successfully](https://console.testdriver.ai/api/replay/abc123/gif)](https://console.testdriver.ai/replay/abc123)

[🎬 View Full Replay](https://console.testdriver.ai/replay/abc123)

## 🔴 Failures

### should complete checkout

**File:** `tests/checkout.test.mjs`

**📹 [Watch Replay](https://console.testdriver.ai/replay/ghi789)**

```
AssertionError: expected false to be truthy
```

<details>
<summary>Stack Trace</summary>

```
AssertionError: expected false to be truthy
    at /workspace/tests/checkout.test.mjs:45:7
    ...
```
</details>

---
<sub>Generated by [TestDriver](https://testdriver.ai) • Run ID: `1234567890-abc123`</sub>

---

## Configuration

### Customizing Comment Behavior

You can control GitHub comment posting with environment variables:

```bash
# Disable GitHub comments entirely
TESTDRIVER_SKIP_GITHUB_COMMENT=true npm run test

# Use custom GitHub token
GH_TOKEN=ghp_yourtoken npm run test
```

### GitLab / Other CI Systems

While the integration is optimized for GitHub, you can use the comment generator programmatically:

```javascript
import { generateGitHubComment } from 'testdriverai/lib/github-comment.mjs';

const testRunData = {
  runId: '1234567890-abc',
  status: 'passed',
  totalTests: 5,
  passedTests: 4,
  failedTests: 1,
  skippedTests: 0,
  duration: 154000,
  testRunUrl: 'https://console.testdriver.ai/runs/123',
  platform: 'linux',
  branch: 'main',
  commit: 'a1b2c3d',
};

const testCases = [
  {
    testName: 'should work',
    testFile: 'test.test.mjs',
    status: 'passed',
    duration: 5000,
    replayUrl: 'https://console.testdriver.ai/replay/abc',
  },
  // ... more tests
];

const markdown = generateGitHubComment(testRunData, testCases);
console.log(markdown);
```

## Troubleshooting

### Comment not posting

1. **Check environment variables:**
   ```bash
   echo $GITHUB_TOKEN
   echo $GITHUB_PR_NUMBER
   ```

2. **Check CI logs:**
   Look for log messages:
   - `"GitHub token not found, skipping comment posting"`
   - `"Repository info not available"`
   - `"Posted GitHub comment"`

3. **Verify token permissions:**
   - GitHub Actions: `GITHUB_TOKEN` should have `write` permissions for `pull-requests` or `contents`
   - Personal tokens: Needs `repo` scope

### Comment not updating

If you see duplicate comments instead of updates:
- Ensure the bot/user posting comments is consistent across runs
- The update mechanism looks for existing comments with "Generated by [TestDriver]" signature

### Replays not showing

If dashcam replays aren't included:
- Verify dashcam is starting correctly (check for `🎥 Dashcam URL:` in logs)
- Ensure tests are calling `await testdriver.provision.*()` which auto-starts dashcam
- Check that dashcam stops successfully (look for replay URLs in output)

### GIF embeds not loading

The GIF embeds are generated dynamically by the TestDriver API:
- URL format: `https://console.testdriver.ai/api/replay/{replayId}/gif`
- If GIFs don't load, the API endpoint may be unavailable
- Fallback: Users can still click the "View Full Replay" link

## API Reference

### `generateGitHubComment(testRunData, testCases)`

Generates markdown for a GitHub comment.

**Parameters:**
- `testRunData` (Object): Test run summary data
  - `runId` (string): Unique test run ID
  - `status` (string): Overall status ('passed', 'failed', 'cancelled')
  - `totalTests` (number): Total number of tests
  - `passedTests` (number): Number of passed tests
  - `failedTests` (number): Number of failed tests
  - `skippedTests` (number): Number of skipped tests
  - `duration` (number): Total duration in milliseconds
  - `testRunUrl` (string): URL to full test run
  - `platform` (string): Test platform ('linux', 'windows', 'mac')
  - `branch` (string): Git branch name
  - `commit` (string): Git commit SHA
- `testCases` (Array): Array of test case objects
  - `testName` (string): Test name
  - `testFile` (string): Test file path
  - `status` (string): Test status
  - `duration` (number): Test duration in ms
  - `replayUrl` (string): Dashcam replay URL (optional)
  - `errorMessage` (string): Error message if failed (optional)
  - `errorStack` (string): Stack trace if failed (optional)

**Returns:** String (markdown)

### `postOrUpdateTestResults(testRunData, testCases, githubOptions)`

Posts or updates a GitHub comment with test results.

**Parameters:**
- `testRunData` (Object): Same as `generateGitHubComment`
- `testCases` (Array): Same as `generateGitHubComment`
- `githubOptions` (Object): GitHub API configuration
  - `token` (string): GitHub token
  - `owner` (string): Repository owner
  - `repo` (string): Repository name
  - `prNumber` (number): PR number (optional)
  - `commitSha` (string): Commit SHA (optional)

**Returns:** `Promise<Object>` - GitHub API response

## Examples

### Manual Comment Posting

```javascript
import { postOrUpdateTestResults } from 'testdriverai/lib/github-comment.mjs';

await postOrUpdateTestResults(
  {
    runId: '123',
    status: 'passed',
    totalTests: 10,
    passedTests: 10,
    failedTests: 0,
    skippedTests: 0,
    duration: 60000,
    testRunUrl: 'https://console.testdriver.ai/runs/123',
    platform: 'linux',
    branch: 'main',
    commit: 'abc123',
  },
  testCases,
  {
    token: process.env.GITHUB_TOKEN,
    owner: 'myorg',
    repo: 'myrepo',
    prNumber: 456,
  }
);
```

### Custom Formatting

```javascript
import { generateGitHubComment } from 'testdriverai/lib/github-comment.mjs';

const markdown = generateGitHubComment(testRunData, testCases);

// Customize markdown
const customMarkdown = markdown.replace(
  '# 🟢 TestDriver Test Results',
  '# 🟢 My Custom Test Report'
);

// Post using GitHub API directly
// ... your posting logic
```

## Support

- **Documentation:** [testdriver.ai/docs](https://testdriver.ai/docs)
- **Issues:** [github.com/testdriverai/testdriverai/issues](https://github.com/testdriverai/testdriverai/issues)
- **Discord:** Join our [community Discord](https://discord.gg/testdriver)
