links/mobile/TESTING_GUIDE.md

Testing iOS Spotlight Search Integration

Quick Test Guide

1. Build and Run the App

1. Build the Heygo iOS app in Xcode
2. Install it on a physical device or simulator (iOS 9.0+)
3. Open the app and create a few test links if you don't have any

2. Test Basic Functionality

1. Create a test link with alias "google" pointing to "https://google.com"
2. Go to the debug tab (gear icon - only visible in debug builds)
3. Tap "Refresh Spotlight Index"
4. Wait for the success message

3. Test Spotlight Search

1. Go to the iOS home screen
2. Pull down from the top to open Spotlight search
3. Type "heygo g"
4. You should see your "google" link appear in the search results
5. Tap on the result - it should open Google in Safari and increment the click counter

4. Verify Click Tracking

1. After opening a link from Spotlight, return to the Heygo app
2. Go to the Analytics tab
3. Verify that the click count for the link has increased
4. Check that a new click log entry was created

5. Test Different Link Types

Regular Links

• Create a link with alias "github" → "https://github.com"
• Search "heygo github" in Spotlight
• Should open GitHub in Safari

Custom Links

• Create a custom link with some markdown content
• Search for it in Spotlight
• Should open the app and show the content (placeholder for now)

Template Links

• Create a template link with URL containing parameters like "https://google.com/search?q={query}"
• Search for it in Spotlight
• Should open the app for parameter input (placeholder for now)

6. Advanced Testing

Prefix Search

• Create links: "gmail", "github", "google"
• Search "heygo g" - should show all three
• Search "heygo git" - should show only github

Tag-Based Search

• Create a link with tags "work", "social"
• Search "heygo work" - should find the tagged link

Ranking Test

• Create two similar links
• Click one multiple times through the app
• Search for both - the frequently clicked one should appear higher

Debugging Issues

Links Not Appearing in Search

1. Check the debug tab - verify "Spotlight Available" shows ✅
2. Verify "Indexed Items" count matches your link count
3. Try refreshing the index
4. Make sure you're using the "heygo" prefix in your search

Links Not Opening Correctly

1. Check that the link exists in the app
2. Verify the URL is properly formatted for regular links
3. Check the debug console for error messages

Performance Issues

1. The system rate-limits full re-indexing to every 5 minutes
2. Individual link updates are indexed immediately
3. Large link collections (100+) may take a few seconds to index

Technical Verification

Check Spotlight Index Status

1. Use the debug tab to see indexed item count
2. Compare with total link count in the app
3. Use "Clear All Indexed Items" to reset if needed

Verify Core Data Integration

1. Create a new link → should auto-index
2. Edit an existing link → should re-index
3. Delete a link → should remove from index

Test Error Handling

1. Try searching when network is off (should still work - local index)
2. Force-quit the app during indexing (should recover on next launch)
3. Delete the app and reinstall (should rebuild index)

Expected Behavior Summary

Action	Expected Result
Create link	Automatically indexed in Spotlight
Edit link	Re-indexed with updated information
Delete link	Removed from Spotlight index
Search "heygo [term]"	Shows matching links
Tap search result	Opens link and records click
Regular link	Opens in Safari
Custom link	Opens app (placeholder)
Template link	Opens app for parameters (placeholder)

Known Limitations

1. Custom and template link handling shows placeholders - UI implementation needed
2. Template parameter input is not yet implemented - shows placeholder
3. Search results limited by iOS Spotlight constraints
4. Indexing happens on background thread - may have slight delay
5. Rate limiting prevents excessive re-indexing