Skip to main content

Manual Testing Guide

Guide for manually testing the Character & Guild System features.

Testing the Character & Guild System​

The system now automatically syncs your WoW characters from Battle.net when you log in!

Step 1: Login via Battle.net​

  1. Visit http://localhost:5173
  2. Click "Login"
  3. Click "Login with Battle.net"
  4. Complete Battle.net OAuth flow
  5. Your characters AND guilds are automatically synced!

Step 2: View Your Characters​

  1. After login, click "Characters" in the nav
  2. You'll see all your WoW characters from Battle.net
  3. Each card shows:
    • Character name
    • Level, race, and class
    • Realm and faction
    • Last sync timestamp
  4. Click "🔄 Sync from Battle.net" to refresh character data

Step 3: View Imported Guilds​

  1. Click "Guilds" in the nav (or just go to the home page)
  2. If any of your characters are in a WoW guild, those guilds are automatically imported!
  3. Each guild card shows:
    • Guild name
    • Realm and faction
    • Background color based on faction (blue for Alliance, red for Horde)

Step 4: View Guild Details​

Click on any guild to see:

  • Full guild roster imported from Battle.net
  • Correct roles mapped from WoW ranks:
    • Rank 0 (Guild Master) → Guild Master role
    • Ranks 1-2 → Officer role
    • Ranks 3-4 → Raider role
    • Ranks 5+ → Member role
  • Member details (character name, class, level, player name)
  • All guild roles

Alternative: Manual Guild Creation​

If you want to create a guild that doesn't exist in WoW yet:

  1. Click "Guilds" → "+ Create Guild"
  2. Select one of your characters
  3. Guild name and realm/faction auto-fill from character
  4. Click "Create Guild"
  5. You'll be set as Guild Master with 5 default roles created

What Works Now​

✅ Battle.net OAuth with token persistence ✅ Auto-sync characters on login ✅ Auto-import guilds from Battle.net ✅ Auto-import guild rosters with correct ranks ✅ WoW rank → Role mapping (Guild Master, Officer, Raider, Member) ✅ Manual character sync button ✅ Manual guild creation (for guilds not in WoW) ✅ View guild members with full character info ✅ View guild roles

What's Coming​

🔜 Invite other users' characters to guild 🔜 Assign/change member roles 🔜 Event scheduling 🔜 Attendance tracking 🔜 Battle.net token refresh (auto-refresh expired tokens)

API Endpoints​

Characters​

# Get user's characters
GET /api/v1/characters
Authorization: Bearer <jwt>

# Sync characters from Battle.net
POST /api/v1/characters/sync
Authorization: Bearer <jwt>
# Returns: { "message": "Synced N characters from Battle.net", "count": N }

Guilds​

# Get all guilds
GET /api/v1/guilds

# Get guild details (includes members & roles)
GET /api/v1/guilds/:id

# Create guild
POST /api/v1/guilds
Authorization: Bearer <jwt>
{
  "characterId": "uuid-of-character",
  "name": "My Guild",
  "realm": "area-52",
  "faction": "horde"
}

Database Schema​

Core Tables​

  • users: OAuth identities (Battle.net, Discord) + Battle.net access tokens
  • characters: WoW characters synced from Battle.net (linked to users)
  • guilds: Guild entities
  • roles: Guild ranks/permissions
  • memberships: Characters in guilds (with roles)
  • events: Scheduled activities
  • participations: Event attendance

Key Relationships​

User → has many Characters
Character → has many Memberships (one active per guild)
Guild → has many Memberships
Guild → has many Roles
Membership → belongs to Character, Guild, Role

How Character Sync Works​

  1. Login Flow:

    • User completes Battle.net OAuth
    • System receives access token & refresh token
    • Tokens are stored in users table with expiry timestamp
    • Auto-sync is triggered in background

  2. Sync Process:

    • Calls Battle.net Profile API: GET /profile/user/wow
    • Fetches all WoW characters across all accounts
    • Upserts characters (creates new, updates existing by Battle.net ID + realm)
    • Updates character level and last sync timestamp

  3. Manual Sync:

    • User clicks "Sync" button on /characters page
    • Uses stored access token from database
    • Same sync process as auto-sync
    • Shows success message with character count

Troubleshooting​

"Battle.net token expired"​

  • Re-login via Battle.net to refresh tokens
  • Token refresh flow coming soon

"No characters found"​

  • Make sure you have WoW characters on your Battle.net account
  • Click "Sync from Battle.net" to trigger manual sync
  • Check Battle.net API scope includes wow.profile

"Failed to sync characters"​

  • Check BATTLENET_REGION in .env matches your region (us/eu/kr/tw)
  • Verify Battle.net API credentials are correct
  • Check terminal logs for detailed error messages