storyteller/docs/development/TESTING_GUIDE.md

🧪 Testing Guide - New Features

Quick test scenarios for the enhanced message system and AI suggestions

---

🚀 Quick Start

Both servers are running:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

---

Test Scenario 1: AI-Assisted Responses ✨

Time: 2 minutes

1. Open http://localhost:3000
2. Click "Create New Session"
3. Enter session name: "Test Game"
4. Click "Create Session"
5. Copy the Session ID
6. Open new browser tab (incognito/private)
7. Paste Session ID and join as character:
   • Name: "Thorin"
   • Description: "A brave dwarf warrior"
   • Personality: "Serious and gruff"
8. As Thorin, send a message: "I examine the dark cave entrance carefully"
9. Switch back to Storyteller tab
10. Click on Thorin in the character list
11. Click "✨ AI Suggest" button
12. Watch as AI generates a response
13. Edit if needed and click "Send Private Response"

Expected Results:

• ✅ AI Suggest button appears
• ✅ Shows "⏳ Generating..." while processing
• ✅ Populates textarea with AI suggestion
• ✅ Can edit before sending
• ✅ Character receives the response

---

Test Scenario 2: Private Messages 🔒

Time: 3 minutes

Using the same session from above:

1. As Thorin (character window):
   • Ensure message type is "🔒 Private"
   • Send: "I try to sneak past the guard"
2. Open another incognito window
3. Join same session as new character:
   • Name: "Elara"
   • Description: "An elven archer"
4. As Elara, check if you see Thorin's message

Expected Results:

• ✅ Thorin's private message appears in storyteller view
• ✅ Elara DOES NOT see Thorin's private message
• ✅ Only Thorin and Storyteller see the private message

---

Test Scenario 3: Public Messages 📢

Time: 3 minutes

Using characters from above:

1. As Thorin:
   • Select "📢 Public" from message type dropdown
   • Send: "I draw my axe and step forward boldly!"
2. Check Storyteller view
3. Check Elara's view

Expected Results:

• ✅ Message appears in "📢 Public Actions" section
• ✅ Storyteller sees it in public feed
• ✅ Elara sees it in her public feed
• ✅ Message is visible to ALL characters

---

Test Scenario 4: Mixed Messages 🔀

Time: 4 minutes

This is the most interesting feature!

1. As Thorin:
   • Select "🔀 Mixed" from message type dropdown
   • Public textarea: "I approach the merchant and start haggling loudly"
   • Private textarea: "While arguing, I signal to Elara to check the back room"
   • Click "Send Mixed Message"
2. Check what each player sees:
   • As Elara: Look at public feed
   • As Storyteller: Look at both public feed and Thorin's private conversation

Expected Results:

• ✅ Elara sees in public feed: "I approach the merchant and start haggling loudly"
• ✅ Elara DOES NOT see the private signal
• ✅ Storyteller sees BOTH parts
• ✅ Public action broadcast to all
• ✅ Secret signal only to storyteller

---

Test Scenario 5: Multiple Characters Interaction 👥

Time: 5 minutes

Goal: Test that the public/private system works with multiple players

1. Keep Thorin and Elara connected
2. Have both send public messages:
   • Thorin (public): "I stand guard at the door"
   • Elara (public): "I scout ahead quietly"
3. Have both send private messages:
   • Thorin (private): "I'm really tired and might fall asleep"
   • Elara (private): "I don't trust Thorin, something seems off"
4. Check each view:
   • Thorin's view
   • Elara's view
   • Storyteller's view

Expected Results:

• ✅ Both characters see all public messages
• ✅ Thorin only sees his own private messages
• ✅ Elara only sees her own private messages
• ✅ Storyteller sees ALL messages from both
• ✅ Each character has isolated private conversation with storyteller

---

Test Scenario 6: Storyteller Responses with AI 🎲

Time: 5 minutes

1. As Storyteller, select Thorin
2. Review his private message about being tired
3. Click "✨ AI Suggest"
4. Review the AI-generated response
5. Edit to add personal touch
6. Send to Thorin
7. Select Elara
8. Use AI Suggest for her as well
9. Send different response to Elara

Expected Results:

• ✅ AI generates contextual responses based on character's LLM model
• ✅ Each response is private (other character doesn't see it)
• ✅ Can edit AI suggestions before sending
• ✅ Each character receives personalized response

---

🐛 Known Issues to Test For

Minor Issues

• Do public messages show character names clearly?
• Does mixed message format look good in all views?
• Are timestamps readable?
• Does page refresh lose messages? (Yes - needs DB)

Edge Cases

• What happens if character disconnects during message?
• Can storyteller respond to character with no messages?
• What if AI Suggest fails (API error)?
• How does UI handle very long messages?

---

🎯 Feature Validation Checklist

Enhanced Message System

• Private messages stay private
• Public messages broadcast correctly
• Mixed messages split properly
• Message type selector works
• UI distinguishes message types visually

AI Suggestions

• Button appears in storyteller view
• Loading state shows during generation
• Suggestion populates textarea
• Can edit before sending
• Works with all character LLM models

Real-time Updates

• Messages appear instantly
• Character list updates when players join
• Pending indicators work
• Connection status accurate

---

📊 Performance Tests

Load Testing (Optional)

1. Open 5+ character windows
2. Send public messages rapidly
3. Check if all see updates
4. Monitor for lag or missed messages

Expected: Should handle 5-10 concurrent users smoothly

---

🔍 Visual Inspection

Character View

• Public feed is clearly distinguished
• Private conversation is obvious
• Message type selector is intuitive
• Mixed message form is clear
• Current scene displays properly

Storyteller View

• Character cards show correctly
• Pending indicators visible
• Public feed displays recent actions
• AI Suggest button prominent
• Conversation switching smooth

---

💡 Testing Tips

1. Use Incognito Windows: Easy way to test multiple characters
2. Keep DevTools Open: Check console for errors
3. Test on Mobile: Responsive design important
4. Try Different LLMs: Each character can use different model
5. Test Disconnect/Reconnect: Close tab and rejoin

---

🎬 Demo Script

For showing off the features:

1. Create session as Storyteller
2. Join as 2 characters in separate windows
3. Character 1 sends public: "I greet everyone cheerfully"
4. Character 2 sees it and responds public: "I nod silently"
5. Character 1 sends mixed:
   • Public: "I offer to share my food"
   • Private: "I'm watching Character 2, they seem suspicious"
6. Character 2 only sees the public offer
7. Storyteller clicks Character 1, uses AI Suggest
8. Sends personalized response to Character 1
9. Storyteller responds to Character 2 differently

This demonstrates:

• Public broadcast
• Private isolation
• Mixed message splitting
• AI-assisted responses
• Personalized storytelling

---

✅ Sign-Off Checklist

Before considering Phase 1 complete:

• All 6 test scenarios pass
• No console errors
• UI looks good
• Messages route correctly
• AI suggestions work
• Real-time updates function
• Multiple characters tested
• Storyteller view functional

---

Happy Testing! 🎉

If you find any issues, note them in docs/development/MVP_PROGRESS.md under "Known Issues"