IRC-kosmi-relay/docs/JACKBOX_TESTING.md

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:

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)