# 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
[](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
```
Stack Trace
```
AssertionError: expected false to be truthy
at /workspace/tests/checkout.test.mjs:45:7
...
```
---
Generated by [TestDriver](https://testdriver.ai) • Run ID: `1234567890-abc123`
---
## 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