Testing & Debugging

Local Environment Configuration

Before running tests or debug scripts, ensure your environment variables are correctly configured in your .env file. These scripts rely on access to your Supabase instance and specific tournament IDs.

# Required for database access and CLI scripts
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
TEST_TOURNAMENT_ID=your_target_tournament_uuid

# Required for AI-powered features (Match commentary/analysis)
OPENAI_API_KEY=your_openrouter_api_key

CLI Debugging Tools

BBX includes several utility scripts located in the root directory to verify tournament logic without using the web interface.

Verifying Bracket Results

The view_bracket_results.js script allows you to inspect the current state of a tournament's "Top Cut" stage directly from your terminal. It organizes matches by round, identifies winners, and determines if a champion has been crowned.

Usage:

node view_bracket_results.js

What it tests:

• Data Integrity: Ensures match records are correctly associated with the TEST_TOURNAMENT_ID.
• Bracket Flow: Validates that winners are correctly identified based on scores.
• Championship Logic: Verifies if the final match correctly triggers the "CHAMPION" status.

Testing Edge Cases

For simulating complex scenarios like mid-tournament entries or Swiss-to-Top Cut transitions, use specific debug scripts:

• Late Entry Testing (debug_late_entry.js): Run this to verify if the Swiss pairing algorithm correctly handles a participant added after Round 1 has already commenced.
• Manual Scoring: Scripts can be used to bulk-update match statuses to 'complete' to rapidly reach the Finals stage for UI testing.

Admin Console Debugging

The Admin Console (/t/[id]/admin) is the primary interface for real-time debugging of active tournaments.

Match State Overrides

If a match is stuck or recorded incorrectly by a user:

1. Navigate to the Pending Matches section.
2. Manually input scores and select the "Finish Type" (Spin Finish, Burst Finish, etc.).
3. Submit the report to force the match into a complete status and update the bracket.

Bracket Advancement

If the tournament does not automatically progress:

• Use the Advance Bracket to Next Round button in the "Dangerous Zone."
• Note: This requires all current round matches to be in the complete status. If it fails, check the browser console for specific match IDs that are still pending.

Integration Testing (OpenRouter & Supabase)

OpenRouter (AI Features)

To test the AI integration used for tournament insights:

1. Ensure lib/openrouter.js is initialized.
2. The system uses the OpenAI SDK pointing to https://openrouter.ai/api/v1.
3. Check for a 200 OK response from the OpenRouter API. If you receive a 401, verify your HTTP-Referer header matches your local development URL (typically http://localhost:3000).

Supabase Real-time Data

If standings or brackets are not updating:

• Open the browser's Network Tab.
• Filter by WS (WebSockets).
• Verify that the client is successfully subscribing to changes on the matches and participants tables.
• Ensure that Row Level Security (RLS) is either disabled for testing or that your service role key is being used for CLI scripts.

Visual Debugging

The Projector View (/t/[id]/projector) and the Bracket Page (/t/[id]/bracket) use conditional rendering to show the state of the tournament.

• Swiss Mode: Visible when stage === 'swiss'.
• Top Cut Mode: Visible when matches with stage === 'top_cut' exist.
• Empty State: If neither appear, verify that startTournamentAction has been triggered in the Admin Console, which populates the initial match list.