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:
- Navigate to the Pending Matches section.
- Manually input scores and select the "Finish Type" (Spin Finish, Burst Finish, etc.).
- Submit the report to force the match into a
completestatus 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
completestatus. If it fails, check the browser console for specific match IDs that are stillpending.
Integration Testing (OpenRouter & Supabase)
OpenRouter (AI Features)
To test the AI integration used for tournament insights:
- Ensure
lib/openrouter.jsis initialized. - The system uses the
OpenAISDK pointing tohttps://openrouter.ai/api/v1. - Check for a
200 OKresponse from the OpenRouter API. If you receive a401, verify yourHTTP-Refererheader matches your local development URL (typicallyhttp://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
matchesandparticipantstables. - 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
startTournamentActionhas been triggered in the Admin Console, which populates the initial match list.