sveltekit-test-playbook

What I do

• Provide testing guidance for SvelteKit frontend code
• Manual testing procedures for Svelte 5 runes-based code
• Testing checklists for stores, components, and WebSocket integration
• Debugging tips for common frontend issues

When to use me

• Before committing frontend changes
• When debugging runes-related issues
• Testing new features or bug fixes
• Verifying store functionality

Testing Philosophy

This project focuses on manual testing rather than automated test frameworks. The priority is:

1. Type safety via bun run check
2. Manual browser testing
3. Code review for patterns

---

Pre-Commit Testing Checklist

1. Type Checking (REQUIRED)

Always run before committing:

cd frontend
bun run check

Must pass with 0 errors. If there are errors, fix them before committing.

2. Svelte 5 Runes Verification

Check for these common issues:

• Files using $state, $derived, $effect have .svelte.ts extension
• No $derived values are exported directly from modules
• No $state primitives are exported (only objects or via getter functions)
• All imports from stores use $lib/stores.svelte (not $lib/stores)

3. Manual Browser Testing

Critical paths to test:

Landing Page (/)

• Can switch between "Join Room" and "Create Game" tabs
• Form validation works (name length, room code format)
• Error messages display correctly
• Can create a new room
• Can join an existing room with valid code
• Invalid room codes show appropriate errors

Room Page (/room/[code])

• Page loads without errors
• Room code displays correctly
• Player list shows current player
• WebSocket connects (check console for errors)
• Chat messages can be sent and received
• Connection status banner appears when disconnected
• Reconnect button works
• Host controls appear only for host

4. Store Testing

Testing Reactive State

When testing stores, verify:

// In browser console or component:
import { player, setPlayer, room, addPlayerToRoom } from '$lib/stores.svelte';

// 1. Test state updates
setPlayer('test-id', 'Test Player', true);
console.log(player.name); // Should be 'Test Player'

// 2. Test reactivity
player.name = 'Updated Name';
console.log(player.name); // Should be 'Updated Name'

// 3. Test array operations
addPlayerToRoom({ id: 'p2', name: 'Player 2', isHost: false });
console.log(room.players.length); // Should increase

Common Store Issues

Issue: Changes not reflecting in UI

• Cause: Reassigned $state object instead of mutating properties
• Fix: Mutate properties: player.name = 'new' not player = {name: 'new'}

Issue: "Cannot export derived state" error

• Cause: Exported $derived directly
• Fix: Export getter function instead

Issue: "rune_outside_svelte" error

• Cause: Using runes in .ts file
• Fix: Rename to .svelte.ts

---

WebSocket Testing

Testing Connection

1. Open browser dev tools → Network → WS (WebSocket)
2. Create or join a room
3. Look for WebSocket connection to ws://localhost:8080/ws
4. Verify connection opens without errors

Testing Message Flow

Test in two browser windows:

1. Window A: Create room as Host
2. Window B: Join same room
3. Verify both see each other in player list
4. Send chat message from Window A
5. Verify Window B receives it

Expected message types in console:

• player_joined - When a player joins
• player_left - When a player disconnects
• chat_message - Chat messages
• phase_changed - When host advances phase

Common WebSocket Issues

Issue: "WebSocket connection failed"

• Check backend is running on port 8080
• Check CORS configuration in backend
• Verify VITE_WS_BASE env var is set correctly

Issue: Messages not broadcasting

• Check room code matches in both windows
• Verify player IDs are unique
• Check hub is running (see backend logs)

---

Debugging Tips

Using Browser DevTools

Console:

// Access stores directly
const stores = await import('/src/lib/stores.svelte');
console.log(stores.player);
console.log(stores.room);

React Debugger:

• Use Svelte DevTools extension
• Inspect component state
• Track $state changes

Common Debug Patterns

Check if state is reactive:

<script>
  import { player } from '$lib/stores.svelte';
  
  // Add this to see updates
  $effect(() => {
    console.log('Player changed:', player);
  });
</script>

Verify store exports:

// In browser console:
import * as stores from '$lib/stores.svelte';
console.log(Object.keys(stores));
// Should see: player, room, connection, messages, getIsHost, setPlayer, etc.

---

Code Review Checklist

When reviewing frontend PRs, check:

Svelte 5 Compliance

• Runes used only in .svelte.ts or .svelte files
• No exported $derived values
• State mutations use property assignment, not reassignment
• Getter functions used for computed values

Code Quality

• Proper TypeScript types on all functions
• Error handling in async functions
• No console.log statements in production code
• Proper cleanup in onDestroy (disconnect WebSocket, clear timers)

UI/UX

• Loading states for async actions
• Error messages are user-friendly
• Responsive design works on mobile
• Accessible (ARIA labels, keyboard navigation)

---

Resources

• Svelte DevTools: Browser extension for debugging
• Project AGENTS.md: Svelte 5 patterns and conventions
• sveltekit-ui-patterns skill: UI implementation patterns
• Context7 MCP: Query official Svelte docs for specific errors