jackboxpartypack-gamepicker/scripts/TESTING.md

# 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