Skip to content

TESTING_GUIDE.md

Latest commit

 

History

History
222 lines (181 loc) · 6.05 KB

TESTING_GUIDE.md

File metadata and controls

222 lines (181 loc) · 6.05 KB

EIGHT - Testing Guide 🎱

Quick Start

The dev server is running at: http://localhost:3000/

Test 1: Location Picker

Scenario A: Automatic Geolocation Denied

  1. Open browser to http://localhost:3000/
  2. When browser asks for location permission, click Block or Deny
  3. Location picker should appear automatically
  4. Open browser console (F12) to see debug logs

Scenario B: Manual Location Search

  1. Type a city name in the search box (e.g., "New York", "London", "Tokyo")
  2. Watch console logs: 
    Searching for location: new york
API Key available: true
Response status: 200
Found locations: 5
  3. Select a city from the dropdown or click a popular city button
  4. Verify weather loads: 
    Location selected: {lat: 40.7128, lon: -74.0060, city: "New York", country: "US"}
Fetching weather for location...
Weather data received: {condition: "Clear", temperature: 15, ...}
Location picker closed, weather set

Expected Result:

✅ Location picker appears when geolocation fails ✅ Search autocomplete works ✅ Popular city buttons work ✅ Weather loads after selection ✅ Location picker closes automatically

Test 2: Brave Search Integration

Using Browser Console

  1. Open browser console (F12)
  2. Type: testBrave()
  3. Press Enter
  4. Watch the output: 
    🧪 Testing Brave Search Integration...
📍 Location: Seattle
🌤️  Weather: Rain 8°C
❓ Question: What should I eat?
⏳ Calling oracle...
✅ Response received!
📋 Type: single
🎴 Card: THE_FEAST
💬 Message: Cold bites deep. [Restaurant Name] warms the soul.
🔗 URL: https://...
✨ Brave Search integration working!

Test All Categories

  1. In console, type: testAllCategories()
  2. This will test all 5 categories:
    • Food (THE_FEAST)
    • Music (THE_SOUND)
    • Movies (THE_VISION)
    • Drinks (THE_CHALICE)
    • Places (THE_COMPASS)

Using the UI

  1. Ensure location and weather are loaded
  2. Type a question in the text input:
    • "What should I eat?"
    • "What should I listen to?"
    • "What should I watch?"
    • "What should I drink?"
    • "Where should I go?"
  3. Click or shake the 8-ball
  4. Wait for the response
  5. Check if the response includes a clickable URL

Expected Result:

✅ Brave API is called (check Network tab) ✅ Real search results returned ✅ Mystical message generated ✅ Clickable URL provided ✅ Falls back to deterministic if Brave fails

Test 3: Oracle Personality

Check Message Style

The oracle should speak with:

  • ✅ Weather metaphors: "Cold bites deep", "Rain drums the roof"
  • ✅ Short, poetic phrases
  • ✅ Confident declarations
  • ✅ Actionable guidance

Bad Examples (should NOT appear):

  • ❌ "I recommend..."
  • ❌ "Based on current conditions..."
  • ❌ "Maybe you should..."
  • ❌ Long explanations

Good Examples (should appear):

  • ✅ "Cold bites deep. [Name] warms the soul."
  • ✅ "Rain whispers secrets. [Name] harmonizes."
  • ✅ "Thunder demands power. [Name] rises."

Test 4: Caching

  1. Ask the same question twice within 5 minutes
  2. Check Network tab in browser DevTools
  3. First request: Should see Brave API call
  4. Second request: Should NOT see Brave API call (cached)
  5. Wait 5+ minutes and ask again
  6. Should see new Brave API call (cache expired)

Expected Result:

✅ First request hits Brave API ✅ Subsequent requests use cache (5 min) ✅ Cache expires after 5 minutes ✅ Different weather/location bypasses cache

Test 5: Fallback Behavior

Simulate Brave API Failure

  1. Temporarily change VITE_BRAVE_API_KEY in .env to invalid key
  2. Restart dev server
  3. Ask a question
  4. Check console: "Brave search failed, falling back to deterministic:"
  5. Verify deterministic algorithm still works

Expected Result:

✅ Graceful fallback to deterministic ✅ No app crash ✅ Still get oracle response ✅ Error logged to console only

Test 6: Different Weather Conditions

Test Scenarios:

  1. Cold + Rain (< 10°C + Rain):

    • Food: Should suggest hot soup, ramen
    • Message: "Cold bites deep" or "Rain drums the roof"

  2. Hot + Clear (> 25°C + Clear):

    • Food: Should suggest fresh, light meals
    • Message: "Heat demands freshness" or "Sun blazes"

  3. Mild + Cloudy (15-25°C + Clouds):

    • Food: Should suggest balanced options
    • Message: Moderate weather references

How to Test:

  1. Use location picker to select different cities
  2. Different cities have different weather
  3. Ask same question in different locations
  4. Compare responses

Debugging Tips

Location Picker Issues:

  • Check: VITE_OPENWEATHER_API_KEY in .env
  • Check: Browser console for API errors
  • Check: Network tab for geocoding API calls
  • Verify: API key is valid at openweathermap.org

Brave Search Issues:

  • Check: VITE_BRAVE_API_KEY in .env
  • Check: Console for "Brave API error" messages
  • Check: Network tab for search API calls
  • Verify: API key is valid and has credits

No Response Issues:

  • Check: Weather and location are loaded
  • Check: Question matches category keywords
  • Check: Console for any error messages
  • Try: Different question phrasings

Console Commands

Available in browser console:

// Test Brave integration
testBrave()

// Test all categories
testAllCategories()

Success Checklist

Before marking complete, verify:

  • Location picker appears when geolocation denied
  • Search autocomplete works
  • Popular city buttons work
  • Weather loads after location selection
  • Brave API returns real results
  • Mystical messages follow personality guide
  • URLs are clickable and valid
  • Caching works (5 min TTL)
  • Fallback to deterministic works
  • No TypeScript errors
  • No console errors (except expected fallback logs)

Known Issues

None currently! 🎉

Next Steps

After testing, you can:

  1. Deploy to production
  2. Add more search refinements
  3. Implement user preferences
  4. Add analytics tracking
  5. Create more card types
  6. Enhance mystical messages

Ready to test! Open http://localhost:3000/ and start exploring! 🎱✨