navidocs/AGENT_2_TEST_PLAN.md

Agent 2: Search Debounce Test Plan

Manual Testing Steps

Test 1: Basic Debounce

1. Open any document in NaviDocs
2. Type "engine" in search box
3. Expected: See loading spinner appear after typing stops
4. Expected: Search executes 300ms after last keystroke
5. Expected: Results appear highlighted in document

Test 2: Cancellation on New Input

1. Type "eng"
2. Wait 200ms (before search triggers)
3. Continue typing "ine"
4. Expected: Previous pending search is cancelled
5. Expected: New 300ms timer starts
6. Expected: Only one search executes (for "engine")

Test 3: Minimum Query Length

1. Type "e" (1 character)
2. Expected: No search executes
3. Expected: No loading spinner
4. Type "n" (now "en", 2 characters)
5. Expected: Search triggers after 300ms
6. Expected: Results appear

Test 4: Clear Search

1. Type "engine" and wait for results
2. Click the X (clear) button
3. Expected: Input clears immediately
4. Expected: Results clear immediately
5. Expected: No highlights remain

Test 5: Backspace to < 2 Characters

1. Type "engine" and wait for results
2. Backspace to "en"
3. Expected: New search executes after 300ms
4. Backspace to "e"
5. Expected: Results clear immediately
6. Expected: No search executes

Test 6: Loading Indicator

1. Type "engine"
2. Expected: Search button shows spinning icon
3. Expected: Button is disabled during search
4. Expected: Tooltip shows "Searching..."
5. Wait for search to complete
6. Expected: Search icon returns
7. Expected: Tooltip shows "Search"

Test 7: Rapid Typing

1. Type "abcdefghijklmnop" quickly without pausing
2. Expected: Loading state appears
3. Expected: Only ONE search executes (after typing stops)
4. Expected: No multiple searches for intermediate strings

Test 8: Enter Key Override

1. Type "eng" (3 characters)
2. Press Enter immediately (don't wait for debounce)
3. Expected: Search executes immediately
4. Expected: Debounce timer is bypassed

Test 9: Multiple Cancel Operations

1. Type "test"
2. Before search executes, type "search"
3. Before that executes, clear input
4. Expected: No errors in console
5. Expected: All abort controllers cleaned up properly

Test 10: Cross-Page Search Integration

1. Type "engine" and wait for results
2. Expected: Current page highlights appear
3. Expected: Background cross-page search starts
4. Expected: Total match count includes all pages
5. Navigate to next/previous match
6. Expected: Navigation works correctly

Automated Test Scenarios (for future implementation)

describe('Search Debounce', () => {
  it('should debounce search by 300ms', async () => {
    // Type characters
    await typeText('engine')

    // Verify search hasn't executed yet
    expect(performSearch).not.toHaveBeenCalled()

    // Wait 300ms
    await delay(300)

    // Verify search executed
    expect(performSearch).toHaveBeenCalledTimes(1)
  })

  it('should cancel previous search on new input', async () => {
    await typeText('eng')
    await delay(200)
    await typeText('ine')

    // Only one search should execute
    await delay(300)
    expect(performSearch).toHaveBeenCalledTimes(1)
    expect(performSearch).toHaveBeenCalledWith('engine')
  })

  it('should not search for queries < 2 chars', async () => {
    await typeText('e')
    await delay(300)

    expect(performSearch).not.toHaveBeenCalled()
  })

  it('should show loading indicator', async () => {
    await typeText('engine')

    expect(isSearching.value).toBe(true)
    expect(searchButton.querySelector('.animate-spin')).toBeInTheDocument()

    await delay(300)
    await waitFor(() => expect(isSearching.value).toBe(false))
  })
})

Performance Verification

Metrics to Check

• Debounce delay: Should be exactly 300ms
• Search cancellation: Previous searches should abort properly
• Memory leaks: No timers or controllers left hanging
• UI responsiveness: No lag during typing
• Search execution: Only one search per debounce period

Console Checks

// Should see ONE log after typing "engine":
console.log("Found X matches across Y pages")

// Should NOT see:
console.error("Search error:")
console.warn("Failed to abort search")

Edge Cases

Concurrent Operations

• ✅ Typing while previous search is running
• ✅ Clearing input while search is running
• ✅ Navigating away while search is running
• ✅ Closing document while search is running

Boundary Conditions

• ✅ Empty string → No search
• ✅ 1 character → No search
• ✅ 2 characters → Search executes
• ✅ Very long query → Search executes normally

State Cleanup

• ✅ Timer cleared on new input
• ✅ Abort controller cleared on completion
• ✅ Loading state reset on error
• ✅ All state reset on clear

Success Criteria

✅ Search executes 300ms after user stops typing ✅ Loading indicator shows during search ✅ Previous searches cancel when new input arrives ✅ Results update in real-time ✅ Clearing input clears results immediately ✅ Queries < 2 characters don't trigger search ✅ No console errors ✅ No memory leaks ✅ Smooth user experience

Known Limitations

1. Debounce timing: 300ms is hardcoded (could be configurable)
2. Minimum query length: 2 characters is hardcoded (could be configurable)
3. No search history: Previous searches not saved
4. No smart cancellation: Cancels even if query prefix matches

Future Enhancements

1. Make debounce delay configurable via settings
2. Add search history dropdown
3. Implement smart cancellation (don't cancel if new query starts with old)
4. Add search suggestions/autocomplete
5. Persist search state across page navigation
6. Add keyboard shortcuts (Cmd+G for next match)
7. Add search within results filtering