Lantern

Appearance

Wave Integration Testing Guide ​

Overview ​

Waves are now fully integrated with Firebase! This guide helps you test the complete wave flow with real Firestore data.

Prerequisites ​

  1. Two test accounts (or two devices/browsers)
  2. Firestore rules deployed: Run npm run deploy:rules (see DEPLOY_FIREBASE_RULES.md)
  3. Firestore indexes created (see below)

Required Firestore Indexes ​

The wave system requires composite indexes for efficient querying. Create these in the Firebase Console:

Waves Collection ​

Index 1: Incoming waves query

  • Collection: waves
  • Fields:
    • recipientUserId (Ascending)
    • status (Ascending)
    • sentAt (Descending)

Index 2: Check existing waves

  • Collection: waves
  • Fields:
    • senderUserId (Ascending)
    • recipientUserId (Ascending)
    • status (Ascending)

Connections Collection ​

Index 1: User 1 connections

  • Collection: connections
  • Fields:
    • user1Id (Ascending)
    • status (Ascending)

Index 2: User 2 connections

  • Collection: connections
  • Fields:
    • user2Id (Ascending)
    • status (Ascending)

Lanterns Collection ​

Index 1: Venue lanterns

  • Collection: lanterns
  • Fields:
    • venueId (Ascending)
    • status (Ascending)
    • litAt (Descending)

Index 2: User lanterns at venue

  • Collection: lanterns
  • Fields:
    • userId (Ascending)
    • venueId (Ascending)
    • status (Ascending)

How to create indexes:

  1. Go to Firebase Console
  2. Select your project
  3. Go to Firestore Database > Indexes
  4. Click "Add Index"
  5. Add each index above

Or run the app and Firebase will show you the exact index creation links in the console when queries fail!

Testing Workflow ​

Setup (Both Users) ​

User 1: alice@test.com ​

  1. Log in with Alice account
  2. Go to Profile Settings
  3. Enable "Spoof location" toggle
  4. Enter San Diego coordinates: 32.7157,-117.1611
  5. Return to Dashboard

User 2: bob@test.com ​

  1. Log in with Bob account (different browser/device/incognito)
  2. Enable location spoof with same coordinates
  3. Return to Dashboard

Test Flow ​

Step 1: Both Users Light Lanterns at Same Venue ​

User 1 (Alice):

  1. On Dashboard home, find "Brew & Co Coffee" (should show 0.0 mi away)
  2. Click venue card
  3. Click "Light My Lantern"
  4. Enter interest: "Looking for React dev to pair program"
  5. Select mood: "Conversation"
  6. Confirm
  7. You should see success screen

User 2 (Bob):

  1. Find "Brew & Co Coffee"
  2. Click venue card
  3. You should now see Alice's lantern!
    • Should show her interest: "Looking for React dev to pair program"
    • Mood: "Conversation"
    • Time: "Just now"
  4. Light your own lantern
  5. Interest: "Want to discuss TypeScript tips"
  6. Mood: "Conversation"
  7. Confirm

Expected:

  • Both users have active lanterns at the same venue
  • Venue counter shows "2" lanterns
  • Each user can see the other's lantern when viewing the venue

Step 2: Send Wave ​

User 2 (Bob):

  1. Still in venue view, you should see Alice's lantern card
  2. Click the "Wave 👋" button
  3. Console should log: 👋 Wave sent successfully!

Expected:

  • Wave document created in Firestore
  • No error messages

Step 3: Receive & Accept Wave ​

User 1 (Alice):

  1. Within seconds, a wave notification should appear at the bottom of the screen
  2. Notification shows:
    • "Someone waved!"
    • Interest: "Want to discuss TypeScript tips"
    • Mood: "Conversation"
    • Venue: "Brew & Co Coffee"
  3. Click "Accept" button
  4. Chat window should open automatically
  5. Banner shows connection details and matching color

Expected:

  • Wave notification appears in real-time (no page refresh needed)
  • Accepting wave opens chat
  • Both users get the same matching color (amber, purple, blue, green, or pink)

Step 4: Chat & Beacon ​

Both Users:

  1. In chat, type a message and send
  2. Other user should see message in real-time
  3. Click "Hold Up Lantern to Meet" button
  4. Full-screen color beacon appears
  5. Both users show the same color

Expected:

  • Messages appear in real-time
  • Beacon colors match between users
  • Beacon stays open until user closes it

Step 5: Close and Verify Connection Persists ​

Both Users:

  1. Close beacon (X button)
  2. Close chat (X button)
  3. Check WaveManager at bottom - you should see "Open Chat" button
  4. Click it to reopen chat

Expected:

  • Connection persists even after closing chat
  • Can reopen chat anytime from WaveManager

Troubleshooting ​

Wave not appearing? ​

  1. Check Firebase console logs:

    • Go to Firestore Database > Data
    • Look for waves collection
    • Verify wave document was created with correct recipientUserId

  2. Check browser console:

    • Look for errors about missing indexes
    • Firebase will provide direct links to create missing indexes

  3. Verify authentication:

    • Both users must be logged in
    • Check console for "No authenticated user" warnings

Lanterns not showing in venue? ​

  1. Check venue coordinates:

    • Both users must have same lat/lng
    • Verify in Profile Settings location spoof

  2. Check lantern status:

    • In Firestore, verify lanterns have status: 'active'
    • Check expiresAt timestamp hasn't passed

  3. Verify venueId:

    • Both lanterns must have same venueId

Chat not opening after accepting wave? ​

  1. Check browser console for errors
  2. Verify connection was created:
    • In Firestore, look for connections collection
    • Should have document with both user IDs
  3. Check activeConnections state in React DevTools

"Simulate Wave" button not showing? ​

This is expected in production. The simulate button only appears in development mode:

  • Local: localhost:5173
  • Dev deployment: dev.ourlantern.app

It will NOT show on ourlantern.app (production).

Data Model Reference ​

Wave Document (waves/{waveId}) ​

javascript
{
  senderUserId: "user1_uid",
  senderLanternId: "lantern1_id",
  recipientUserId: "user2_uid",
  recipientLanternId: "lantern2_id",
  venueId: "venue_id",
  venueName: "Brew & Co Coffee",
  status: "pending" | "accepted" | "declined" | "expired",
  interest: "Looking for React dev to pair program",
  mood: "Conversation",
  sentAt: Timestamp,
  respondedAt?: Timestamp,
  expiresAt: Timestamp, // 1 hour from sentAt
  matchColor?: "amber" | "purple" | "blue" | "green" | "pink",
  connectionId?: "conn_id" // set when accepted
}

Connection Document (connections/{connectionId}) ​

javascript
{
  waveId: "wave_id",
  user1Id: "sender_uid",
  user2Id: "recipient_uid",
  venueId: "venue_id",
  venueName: "Brew & Co Coffee",
  matchColor: "purple",
  interest: "Looking for React dev to pair program",
  mood: "Conversation",
  createdAt: Timestamp,
  expiresAt: Timestamp, // 4 hours from createdAt
  status: "active" | "met" | "expired"
}

Next Steps ​

After verifying waves work:

  1. Test with different venues: Light lanterns at different venues and verify waves only work within same venue
  2. Test expiry: Wait 1 hour and verify waves auto-expire
  3. Test decline: Send wave and decline it - should remove from incoming waves
  4. Test multi-device sync: Have one user on phone, one on desktop
  5. Test connection expiry: Wait 4 hours and verify connection expires

Development Tips ​

Quick Test Without Two Devices ​

Use the "Simulate Wave" button (dev only):

  1. Light your lantern
  2. Click "Simulate wave" button at bottom
  3. Accept the mock wave
  4. Test chat and beacon

This creates a fake wave locally (not in Firebase) for quick UI testing.

Inspecting Real-Time Updates ​

Open React DevTools and watch these state variables:

  • incomingWaves - Should update when someone waves at you
  • activeConnections - Should update when you accept a wave
  • activeLanterns - Should update when you light/extinguish

Firebase Console Debugging ​

  1. Go to Firestore Database > Data
  2. Watch waves collection update in real-time
  3. Watch connections collection when waves are accepted
  4. Check document timestamps to verify expiry logic

Security Notes ​

All wave interactions are:

  • Authenticated: Must be logged in
  • Authorized: Can only send/accept your own waves
  • Rate-limited: One wave per user pair at a time
  • Ephemeral: Waves expire after 1 hour, connections after 4 hours
  • Private: Only sender and recipient can see wave details

See firestore.rules for complete security rules.

Success Criteria ​

✅ Two users can light lanterns at same venue
✅ Each user sees the other's lantern in venue view
✅ User can send wave to another user's lantern
✅ Recipient receives wave notification in real-time
✅ Accepting wave creates connection and opens chat
✅ Both users get matching color beacon
✅ Chat messages sync in real-time
✅ Connection persists across chat close/reopen
✅ Declining wave removes notification
✅ Waves expire after 1 hour if not responded
✅ Connections expire after 4 hours

Questions or issues? Check the Engineering docs or raise an issue in the repo!

Built with VitePress

Copyright © 2026 Lantern