navidocs/docs/AGENTS.md

Instructions for AI Agents (Claude Code, Copilot, etc.)

Purpose: Critical instructions to prevent bugs from reaching production.

Last Updated: 2025-10-19

---

⚠️ CRITICAL RULE: Always Test the UI, Not Just the API

The Problem

What usually happens:

1. ✅ Agent tests API with curl → Test passes
2. ❌ Agent assumes feature works → Marks complete
3. 🐛 User finds bug in UI → Feature actually broken

Real examples from this project:

• Upload API worked perfectly via curl ✅
• Upload UI had wrong field name ('pdf' instead of 'file') ❌
• Result: 100% upload failure rate for users

The Solution

"If you didn't test it in a real browser with DevTools open, you didn't test it."

---

Mandatory Testing Protocol

For EVERY Feature/PR:

Phase 1: Code Review (BEFORE testing)

# Verify field names match between frontend and backend
grep -A 5 "formData.append" client/src/components/*.vue
grep "upload.single\|upload.array" server/routes/*.js
# Field names MUST match exactly

# Check for external dependencies (CDNs)
grep -r "cdnjs\|unpkg\|cdn.jsdelivr" client/src/
# Replace CDNs with local files from node_modules

Phase 2: API Testing

# Test with curl using EXACT field names from source code
curl -X POST http://localhost:8001/api/upload \
  -F "file=@test.pdf" \
  -F "title=Test" \
  -F "organizationId=test-org-123"

# Verify: 201 Created (not 400/500)

Phase 3: Browser Testing (REQUIRED)

1. Open browser: http://172.29.75.55:8080 (Windows)
                  http://localhost:8080 (WSL2)

2. Press F12 to open DevTools

3. Clear Console (important!)

4. Complete the user workflow:
   - Click buttons
   - Fill forms
   - Submit data
   - Navigate between pages

5. Check DevTools Console tab:
   ✅ No red errors
   ✅ No "Failed to fetch" messages
   ✅ No CDN loading failures

6. Check DevTools Network tab:
   ✅ Status codes: 200/201 (not 400/500)
   ✅ Field names match backend expectations
   ✅ All resources load successfully

7. Verify UI shows correct feedback:
   ✅ Success messages appear
   ✅ Progress bars work
   ✅ Data displays correctly

Phase 4: Full Workflow Testing

Test complete user journeys, not isolated endpoints:

Upload Workflow:
1. Click "Upload Document"
2. Select PDF file
3. Fill metadata form
4. Submit
5. Watch progress bar
6. See success message
7. Verify document appears in search

Search & View Workflow:
1. Search for a term
2. Click on a result
3. PDF viewer loads
4. Page navigation works
5. No errors in console

---

Specific Test Requirements by Feature

Upload Feature

❌ WRONG:

curl -X POST /api/upload -F "file=@test.pdf"  # ✅ API works
# ⚠️ But did you test the UI? Upload button could be broken!

✅ CORRECT:

# 1. API test
curl -X POST /api/upload -F "file=@test.pdf"

# 2. Code verification
grep "formData.append.*file" client/src/components/UploadModal.vue
# Verify field name is 'file' not 'pdf'

# 3. Browser test
# Open http://172.29.75.55:8080
# Click "Upload Document"
# Complete workflow
# Check DevTools Console and Network

# 4. Only mark complete if ALL tests pass

Document Viewer

❌ WRONG:

curl /api/documents/:id/pdf  # ✅ API works
# ⚠️ But PDF.js worker could fail to load in browser!

✅ CORRECT:

# 1. API test
curl /api/documents/:id/pdf

# 2. Code verification
grep "workerSrc" client/src/views/DocumentView.vue
# Verify NOT using CDN (use local worker file)

# 3. Browser test
# Upload a multi-page PDF (5+ pages)
# Click on the document to open viewer
# Page 1 should render

# Test page navigation:
# - Click "Next" → Page 2 displays
# - Click "Next" → Page 3 displays
# - Click "Previous" → Page 2 displays
# - Type page number and click "Go" → That page displays
# - Rapid click Next/Previous (test render task cancellation)

# Check Console for errors:
# - No worker errors
# - No CDN failures
# - No "Failed to render page" errors

# 4. Only mark complete if:
# - PDF displays correctly
# - All page navigation works
# - No console errors

Search Feature

❌ WRONG:

curl -X POST /api/search -d '{"q":"test"}'  # ✅ API works
# ⚠️ But search bar could send wrong query format!

✅ CORRECT:

# 1. API test
curl -X POST /api/search -d '{"q":"test","limit":10}'

# 2. Code verification
grep -A 10 "fetch.*search" client/src/composables/useSearch.js
# Verify request body format matches API

# 3. Browser test
# Type in search bar
# Press Enter
# Results should appear
# Check Console and Network

# 4. Only mark complete if search works in UI

---

Common Mistakes That Let Bugs Through

Mistake 1: Testing with correct values, UI sends wrong values

# Agent tests with correct field name:
curl -F "file=@test.pdf"  # ✅ Works

# But UI code has:
formData.append('pdf', file)  # ❌ Wrong field name

# Bug slips through because UI wasn't tested

Prevention: Grep the actual UI code before testing.

Mistake 2: Assuming external resources work

// Code uses CDN:
workerSrc = "//cdnjs.cloudflare.com/..."  # ✅ Works in test

// But CDN blocked in production:
// Browser: Failed to fetch  # ❌ Fails for user

// Bug slips through because browser wasn't tested

Prevention: Always test in actual browser, avoid CDNs.

Mistake 3: Testing steps in isolation, not full workflow

# Test each endpoint separately:
curl /api/upload      # ✅
curl /api/search      # ✅
curl /api/documents   # ✅

# But full workflow broken:
# Upload → Search → View PDF  # ❌ Fails

// Bug slips through because full workflow wasn't tested

Prevention: Test complete user journeys end-to-end.

---

Pre-Commit Checklist

Before marking ANY work as complete:

• Source code reviewed for integration issues
• Field names verified to match between frontend/backend
• External dependencies checked (no CDNs)
• API endpoints tested with curl
• UI tested in actual browser ← REQUIRED
• DevTools Console checked (no errors) ← REQUIRED
• DevTools Network checked (no failures) ← REQUIRED
• Full user workflow completed successfully
• Tested on target environment (WSL2 → Windows)

---

Quick Reference Commands

Verify Frontend/Backend Contract

# Check what frontend sends:
grep -r "formData.append\|body.*JSON.stringify" client/src/

# Check what backend expects:
grep -r "req.body\|req.file\|upload.single" server/routes/

# They MUST match!

Find Integration Issues

# Find CDN dependencies:
grep -r "http.*cdn\|//cdn" client/src/

# Find hardcoded values:
grep -r "test-user-id\|test-org" client/src/

# Find potential mismatches:
diff <(grep -r "formData.append" client/src/ | cut -d'"' -f2 | sort) \
     <(grep -r "req.body\|req.file" server/routes/ | grep -oP '\w+(?=\s*[,)])')

Test in Browser

1. Windows: http://172.29.75.55:8080
2. WSL2:    http://localhost:8080
3. Press F12 (DevTools)
4. Console + Network tabs
5. Perform action
6. Verify no errors

---

Automation Requirements

Unit Tests Must Verify Integration Points

// ✅ Good test - verifies actual field name
test('upload uses correct field name', () => {
  const form = component.createFormData()
  expect(form.has('file')).toBe(true)  // Not 'pdf'
  expect(form.has('organizationId')).toBe(true)
})

// ❌ Bad test - mocks everything, misses integration bugs
test('upload works', () => {
  mockUpload.mockResolvedValue({ ok: true })
  // This passes even if field names are wrong!
})

E2E Tests Required for Critical Paths

// Cypress/Playwright tests for:
// 1. Upload workflow
// 2. Search workflow
// 3. Document viewer
// 4. Full user journey

test('user can upload and view document', async () => {
  await page.goto('http://localhost:8080')

  // Upload
  await page.click('[data-testid=upload-button]')
  await page.setInputFiles('input[type=file]', 'test.pdf')
  await page.fill('input[name=title]', 'Test')
  await page.click('[data-testid=submit]')
  await page.waitForSelector('.success-message')

  // Search
  await page.fill('input[placeholder*=Search]', 'Test')
  await page.press('input[placeholder*=Search]', 'Enter')

  // View
  await page.click('.search-result:first-child')
  await page.waitForSelector('canvas')  // PDF renders

  // Verify no console errors
  const errors = await page.evaluate(() => window.consoleErrors || [])
  expect(errors).toHaveLength(0)
})

---

The One Rule

API tests are necessary but NOT sufficient.

They catch backend bugs but miss frontend integration issues.

If you didn't test it in a browser, you didn't test it.

---

Real Bug Examples from This Project

Bug 1: Upload Field Name Mismatch

API Test: ✅ PASS
curl -F "file=@test.pdf" /api/upload

UI Code: ❌ WRONG
formData.append('pdf', file)  // Should be 'file'

Result: 100% upload failure for users
Fix: 1 line change, 5 minutes
Cost: Hours of debugging

Bug 2: PDF.js CDN Failure

API Test: ✅ PASS
curl /api/documents/:id/pdf

UI Code: ❌ WRONG
workerSrc = "//cdnjs.cloudflare.com/..."  // CDN blocked

Result: PDF viewer broken for all users
Fix: 5 line change, 5 minutes
Cost: Complete feature failure

Both bugs would have been caught by browser testing.

---

Summary for AI Agents

When tasked with implementing/testing a feature:

1. ✅ Implement the feature
2. ✅ Test API with curl
3. ✅ ALSO test in browser ← Don't skip this!
4. ✅ Check DevTools Console
5. ✅ Check DevTools Network
6. ✅ Verify full user workflow
7. ❌ Don't mark complete until browser test passes

Remember: Your API test passing does NOT mean the feature works for users.

---

Full testing guide: /home/setup/navidocs/docs/testing/TESTING_REQUIREMENTS.md