Move troubleshooting and implementation docs to docs/
Relocate 30 non-essential .md files (investigation notes, fix summaries, implementation details, status reports) from the project root into docs/ to reduce clutter. Core operational docs (README, quickstart guides, configuration references) remain in the root. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cottongin
298
docs/JACKBOX_TESTING.md
Normal file
298
docs/JACKBOX_TESTING.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user