# Jackbox Integration Testing Guide

This document provides a comprehensive testing guide for the Jackbox Game Picker API integration.

## Prerequisites

Before testing, ensure:

1. **Jackbox Game Picker API is running**
   - API should be accessible at the configured URL (e.g., `http://localhost:5000`)
   - You have the admin password for authentication

2. **Relay is configured**
   - `matterbridge.toml` has the `[jackbox]` section configured
   - `Enabled=true`
   - `APIURL`, `AdminPassword`, and `WebhookSecret` are set correctly

3. **Webhook is registered**
   - Follow the setup steps in `JACKBOX_INTEGRATION.md` to register the webhook

## Test Plan

### Test 1: Build and Startup

**Objective:** Verify the relay builds and starts successfully with Jackbox integration enabled.

**Steps:**
1. Build the relay: `docker-compose build`
2. Start the relay: `docker-compose up -d`
3. Check logs: `docker logs kosmi-irc-relay`

**Expected Results:**
```
[jackbox] Initializing Jackbox integration...
[jackbox] Successfully authenticated with Jackbox API
[jackbox] Starting Jackbox webhook server on port 3001
[jackbox] Jackbox client injected into Kosmi bridge
[jackbox] Jackbox client injected into IRC bridge
```

**Status:** ✅ PASS / ❌ FAIL

---

### Test 2: Vote Detection from Kosmi

**Objective:** Verify votes from Kosmi chat are detected and sent to the API.

**Prerequisites:**
- Active session in Jackbox API with at least one game played

**Steps:**
1. Send message in Kosmi chat: `thisgame++`
2. Check relay logs for vote detection
3. Verify vote was recorded in API

**Expected Results:**
- Relay logs show: `[kosmi] Detected vote from <username>: up`
- Relay logs show: `[jackbox] Vote recorded for <game>: <username> - X👍 Y👎`
- API shows the vote was recorded

**Status:** ✅ PASS / ❌ FAIL

---

### Test 3: Vote Detection from IRC

**Objective:** Verify votes from IRC chat are detected and sent to the API.

**Prerequisites:**
- Active session in Jackbox API with at least one game played

**Steps:**
1. Send message in IRC chat: `thisgame--`
2. Check relay logs for vote detection
3. Verify vote was recorded in API

**Expected Results:**
- Relay logs show: `[irc] Detected vote from <username>: down`
- Relay logs show: `[jackbox] Vote recorded for <game>: <username> - X👍 Y👎`
- API shows the vote was recorded

**Status:** ✅ PASS / ❌ FAIL

---

### Test 4: Case-Insensitive Vote Detection

**Objective:** Verify votes work with different case variations.

**Steps:**
1. Send in Kosmi: `THISGAME++`
2. Send in IRC: `ThIsGaMe--`
3. Send in Kosmi: `thisgame++`

**Expected Results:**
- All three votes are detected and sent to API
- Relay logs show vote detection for each message

**Status:** ✅ PASS / ❌ FAIL

---

### Test 5: Relayed Message Filtering (Kosmi)

**Objective:** Verify relayed messages from IRC are NOT sent as votes from Kosmi.

**Steps:**
1. Send message in IRC: `thisgame++`
2. Observe the relayed message in Kosmi chat (should have `[irc]` prefix)
3. Check relay logs

**Expected Results:**
- Message appears in Kosmi as: `[irc] <username> thisgame++`
- Relay logs show vote detected from IRC user
- Relay logs do NOT show a second vote from Kosmi
- Only ONE vote is recorded in the API

**Status:** ✅ PASS / ❌ FAIL

---

### Test 6: Relayed Message Filtering (IRC)

**Objective:** Verify relayed messages from Kosmi are NOT sent as votes from IRC.

**Steps:**
1. Send message in Kosmi: `thisgame--`
2. Observe the relayed message in IRC chat (should have `[kosmi]` prefix)
3. Check relay logs

**Expected Results:**
- Message appears in IRC as: `[kosmi] <username> thisgame--`
- Relay logs show vote detected from Kosmi user
- Relay logs do NOT show a second vote from IRC
- Only ONE vote is recorded in the API

**Status:** ✅ PASS / ❌ FAIL

---

### Test 7: Game Notification Webhook

**Objective:** Verify game notifications are received and broadcast to both chats.

**Steps:**
1. Add a game to the active session via the Jackbox API
2. Check relay logs for webhook receipt
3. Verify notification appears in both Kosmi and IRC chats

**Expected Results:**
- Relay logs show: `[jackbox] Broadcasting Jackbox message: 🎮 Coming up next: <game>!`
- Both Kosmi and IRC chats receive the notification
- Message appears as: `🎮 Coming up next: <game>!`

**Status:** ✅ PASS / ❌ FAIL

---

### Test 8: Webhook Signature Verification

**Objective:** Verify webhooks with invalid signatures are rejected.

**Steps:**
1. Send a manual webhook POST to `http://localhost:3001/webhook/jackbox` with an invalid signature
2. Check relay logs

**Expected Results:**
- Relay logs show: `[jackbox] Webhook signature verification failed`
- HTTP response is 401 Unauthorized
- No game notification is broadcast

**Test Command:**
```bash
curl -X POST "http://localhost:3001/webhook/jackbox" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=invalid" \
  -d '{"event":"game.added","data":{"game":{"title":"Test Game"}}}'
```

**Status:** ✅ PASS / ❌ FAIL

---

### Test 9: Duplicate Vote Prevention

**Objective:** Verify the API prevents duplicate votes within 1 second.

**Steps:**
1. Send `thisgame++` in Kosmi
2. Immediately send `thisgame++` again (within 1 second)
3. Check relay logs and API

**Expected Results:**
- First vote is recorded successfully
- Second vote is rejected by API with 409 Conflict
- Relay logs show: `[jackbox] Duplicate vote from <username> (within 1 second)`

**Status:** ✅ PASS / ❌ FAIL

---

### Test 10: No Active Session Handling

**Objective:** Verify graceful handling when no active session exists.

**Steps:**
1. End the active session in the Jackbox API
2. Send `thisgame++` in Kosmi or IRC
3. Check relay logs

**Expected Results:**
- Relay logs show: `[jackbox] Vote rejected: no active session or timestamp doesn't match any game`
- No error is thrown
- Relay continues to function normally

**Status:** ✅ PASS / ❌ FAIL

---

### Test 11: Disabled Integration

**Objective:** Verify relay works normally when Jackbox integration is disabled.

**Steps:**
1. Set `Enabled=false` in `[jackbox]` section
2. Restart relay: `docker-compose restart`
3. Send messages with `thisgame++` in both chats
4. Check relay logs

**Expected Results:**
- Relay logs show: `[jackbox] Jackbox integration is disabled`
- No vote detection occurs
- Messages are relayed normally between Kosmi and IRC
- No Jackbox client injection messages

**Status:** ✅ PASS / ❌ FAIL

---

### Test 12: Authentication Token Refresh

**Objective:** Verify the relay re-authenticates when the JWT token expires.

**Steps:**
1. Wait for token to expire (or manually invalidate it in the API)
2. Send a vote: `thisgame++`
3. Check relay logs

**Expected Results:**
- Relay logs show: `[jackbox] Token expired, re-authenticating...`
- Relay logs show: `[jackbox] Successfully authenticated with Jackbox API`
- Vote is sent successfully after re-authentication

**Status:** ✅ PASS / ❌ FAIL

---

## Manual Testing Checklist

- [ ] Test 1: Build and Startup
- [ ] Test 2: Vote Detection from Kosmi
- [ ] Test 3: Vote Detection from IRC
- [ ] Test 4: Case-Insensitive Vote Detection
- [ ] Test 5: Relayed Message Filtering (Kosmi)
- [ ] Test 6: Relayed Message Filtering (IRC)
- [ ] Test 7: Game Notification Webhook
- [ ] Test 8: Webhook Signature Verification
- [ ] Test 9: Duplicate Vote Prevention
- [ ] Test 10: No Active Session Handling
- [ ] Test 11: Disabled Integration
- [ ] Test 12: Authentication Token Refresh

## Test Results Summary

**Date:** _________________

**Tester:** _________________

**Total Tests:** 12

**Passed:** ___ / 12

**Failed:** ___ / 12

**Notes:**
_______________________________________________________________________
_______________________________________________________________________
_______________________________________________________________________

## Known Issues

(Document any issues found during testing)

## Recommendations

(Document any improvements or changes needed)