initial actual player count implementation

scripts/TESTING.md

@@ -0,0 +1,184 @@
+# Testing the Jackbox Player Count Script
+
+## Prerequisites
+
+1. Go 1.21+ installed
+2. Chrome or Chromium browser installed
+3. Active Jackbox lobby with a valid room code
+
+## Running the Script
+
+### Basic Usage
+
+```bash
+cd scripts
+go run get-player-count.go JYET
+```
+
+Replace `JYET` with your actual room code.
+
+### Debug Mode
+
+If the script isn't capturing data, run with debug output:
+
+```bash
+DEBUG=true go run get-player-count.go JYET
+```
+
+This will show:
+- Each WebSocket frame received
+- Parsed opcodes
+- Detailed connection info
+
+## Expected Output
+
+### Success
+
+```
+🎮 Jackbox Player Count Fetcher
+Room Code: JYET
+
+⏳ Navigating to jackbox.tv...
+✓ Loaded jackbox.tv
+⏳ Joining room JYET...
+✓ Clicked Play button, waiting for WebSocket data...
+✓ Captured lobby data from WebSocket
+
+═══════════════════════════════════════════
+  Jackbox Room Status
+═══════════════════════════════════════════
+
+Room Code:      JYET
+Game:           triviadeath
+Game State:     Lobby
+Lobby State:    CanStart
+Locked:         false
+Full:           false
+
+Players:        3 / 8
+Audience:       0
+
+Current Players:
+  1. Host (host)
+  2. E (player)
+  3. F (player)
+
+═══════════════════════════════════════════
+```
+
+### If No WebSocket Messages Captured
+
+```
+Error: no WebSocket messages captured - connection may have failed
+Try running with DEBUG=true for more details
+```
+
+**Possible causes:**
+- Room code is invalid
+- Game lobby is closed
+- Network connectivity issues
+
+### If Messages Captured but No Player Data
+
+```
+⚠️  Captured 15 WebSocket messages but couldn't find 'client/welcome'
+
+Message types found:
+  - room/update: 5
+  - audience/count: 3
+  - ping: 7
+
+Error: could not find player count data in WebSocket messages
+Room may be invalid, closed, or not in lobby state
+```
+
+**Possible causes:**
+- Game has already started (not in lobby)
+- Room code exists but game is in different state
+- WebSocket connected but welcome message not sent
+
+## Troubleshooting
+
+### Cookie Errors (Harmless)
+
+You may see errors like:
+```
+ERROR: could not unmarshal event: parse error: expected string near offset 1247 of 'cookiePart...'
+```
+
+**These are harmless** and are suppressed in the output. They're chromedp trying to parse cookie data that doesn't follow expected format.
+
+### "Failed to load jackbox.tv"
+
+- Check your internet connection
+- Verify https://jackbox.tv loads in a regular browser
+- Try running without `headless` mode (edit the Go file)
+
+### "Failed to enter room code"
+
+- Verify the room code is valid
+- Check that the lobby is actually open
+- Try running with DEBUG=true to see what's happening
+
+### "Failed to click Play button"
+
+- The button may still be disabled
+- Room code validation may have failed
+- Name field may not be filled
+
+### No WebSocket Messages at All
+
+This means the browser never connected to the game's WebSocket server:
+- Verify the room code is correct
+- Check that the game lobby is actually open and accepting players
+- The game may have a full lobby
+- The room may have expired
+
+## Testing with Different Game States
+
+### Lobby (Should Work)
+When the game is in the lobby waiting for players to join.
+
+### During Game (May Not Work)
+Once the game starts, the WebSocket messages change. The `client/welcome` message may not be sent.
+
+### After Game (Won't Work)
+Room codes expire after the game session ends.
+
+## Manual Verification
+
+You can verify the data by:
+
+1. Open https://jackbox.tv in a regular browser
+2. Open Developer Tools (F12)
+3. Go to Network tab
+4. Filter by "WS" (WebSocket)
+5. Join the room with the same code
+6. Look for `client/welcome` message in WebSocket frames
+7. Compare the data with what the script outputs
+
+## Common Room States
+
+| State | `client/welcome` | Player Count Available |
+|-------|------------------|------------------------|
+| Lobby - Waiting | ✅ Yes | ✅ Yes |
+| Lobby - Full | ✅ Yes | ✅ Yes |
+| Game Starting | ⚠️ Maybe | ⚠️ Maybe |
+| Game In Progress | ❌ No | ❌ No |
+| Game Ended | ❌ No | ❌ No |
+
+## Performance Notes
+
+- Takes ~5-10 seconds to complete
+- Most time is waiting for WebSocket connection
+- Headless Chrome startup adds ~1-2 seconds
+- Network latency affects timing
+
+## Next Steps
+
+If the script works:
+1. Extract the function into a library package
+2. Integrate with your bot
+3. Set up cron jobs or periodic polling
+4. Add result caching to reduce load
+