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"