IRC-kosmi-relay/docs/setup/TEST_INSTRUCTIONS.md

# Message Relay Testing Instructions

## Current Configuration

- **Kosmi Room**: Configured via `RoomURL` in `matterbridge.toml`
- **IRC Server**: Configured via `Server` in `matterbridge.toml`
- **IRC Channel**: Configured via gateway `[[gateway.inout]]`

## Test 1: Kosmi --> IRC

### Steps

1. Open your Kosmi room in a browser
2. Type a test message (e.g., "Test message from Kosmi")
3. Press Enter to send

### Expected Logs

```
INFO Received message from Kosmi: [<timestamp>] username: message text
DEBUG Forwarding to Matterbridge channel=main account=kosmi.hyperspaceout
```

### Verification

The message should appear in your IRC channel with the configured `RemoteNickFormat`, typically:
```
[kosmi] <username> Test message from Kosmi
```

## Test 2: IRC --> Kosmi

### Steps

1. Connect to your IRC server and join the configured channel
2. Send a test message (e.g., "Test message from IRC")

### Expected Logs

```
DEBUG <= Sending message from #channel on irc.account to gateway
DEBUG => Sending message to Kosmi
```

### Verification

The message should appear in the Kosmi room with the configured format, typically:
```
[irc] <username> Test message from IRC
```

## Test 3: Jackbox Vote Detection (if enabled)

### Steps

1. In IRC or Kosmi, type: `thisgame++`
2. Check bot logs

### Expected Logs

```
DEBUG Detected vote from username: up (ticker="")
```

## Test 4: IRC Commands

### Steps

1. In IRC, type: `!votes`
2. Check for broadcast response

### Expected Response (if active session)

```
🗳️ Game Title • Today: X👍 Y👎 (Score: Z) • All-time: X👍 Y👎 (Score: Z)
```

## Watching Logs

```bash
# All logs
docker-compose logs -f

# Message-related logs only
docker-compose logs -f | grep -E "(Received|Sending|Forwarding|Detected)"

# Last 50 lines
docker-compose logs --tail=50
```

## Success Criteria

1. Messages sent in Kosmi appear in IRC
2. Messages sent in IRC appear in Kosmi
3. Usernames are displayed correctly with bridge prefix
4. Messages appear within 1-2 seconds
5. No errors in logs during normal relay

## Troubleshooting

### No Messages Appearing

1. Check the container is running: `docker-compose ps`
2. Check for errors: `docker-compose logs --tail=100`
3. Verify both bridges are connected (look for success messages)
4. Restart if needed: `docker-compose restart`

### Messages Only Going One Direction

- **Kosmi --> IRC works, IRC --> Kosmi doesn't**: Check Kosmi WebSocket is connected
- **IRC --> Kosmi works, Kosmi --> IRC doesn't**: Check IRC connection status

### Message Formatting Issues

Message format is controlled by `RemoteNickFormat` in each bridge's config section. Default: `[{PROTOCOL}] <{NICK}> `

## Quick Commands

```bash
docker-compose up -d          # Start
docker-compose logs -f        # Follow logs
docker-compose down           # Stop
docker-compose restart        # Restart
docker-compose ps             # Status
docker stats kosmi-irc-relay  # Resource usage
```