navidocs/LIVE_TESTING_GUIDE.md

NaviDocs Live Testing Guide

Version: 1.0 Date: 2025-11-13 Platform: StackCP Live Deployment Status: Ready for Testing

---

Overview

This guide provides step-by-step instructions for testing the NaviDocs live deployment on StackCP. It covers all three core features:

1. Smart OCR - Intelligent PDF text extraction with performance optimization
2. Multi-Format Support - Upload and process 6 file types
3. Timeline Activity - Track document upload/deletion history

Expected Total Testing Time: 45-60 minutes

---

Table of Contents

1. Live URLs
2. Pre-Testing Setup
3. Test 1: Smart OCR
4. Test 2: Multi-Format Upload
5. Test 3: Timeline Activity
6. Test Data Suggestions
7. Expected Results
8. Reporting Bugs
9. Troubleshooting

---

Live URLs

Frontend

• Main Application: https://digital-lab.ca/navidocs/
• Register: https://digital-lab.ca/navidocs/#/register
• Login: https://digital-lab.ca/navidocs/#/login
• Dashboard: https://digital-lab.ca/navidocs/#/dashboard
• Library: https://digital-lab.ca/navidocs/#/library

Backend API

• Health Check: https://api.digital-lab.ca/navidocs/health
• API Base: https://api.digital-lab.ca/navidocs/api/
• Upload Endpoint: https://api.digital-lab.ca/navidocs/api/upload (POST)
• Search Token: https://api.digital-lab.ca/navidocs/api/search/token (POST)
• Documents: https://api.digital-lab.ca/navidocs/api/documents (GET)
• Jobs Status: https://api.digital-lab.ca/navidocs/api/jobs/{jobId} (GET)

Meilisearch (Internal)

• Endpoint: http://localhost:7700 (StackCP internal only)
• Index Name: navidocs-pages
• Search Health: http://localhost:7700/health

---

Pre-Testing Setup

Step 1: Verify Deployment Status

# Check API health
curl -s https://api.digital-lab.ca/navidocs/health | jq .

# Expected Response:
# {
#   "status": "ok",
#   "uptime": 1234567,
#   "timestamp": "2025-11-13T15:30:00.000Z"
# }

Step 2: Create Test Account

1. Navigate to: https://digital-lab.ca/navidocs/#/register
2. Fill in registration form:
   • Email: test-user-[random]@example.com
   • Password: TestPass123!@#
   • Confirm: TestPass123!@#
   • Boat Name: Test Vessel
3. Click "Create Account"
4. Verify email confirmation (or skip if in demo mode)
5. Login with credentials

Step 3: Verify Login & Dashboard

After login, you should see:

• Dashboard loads without errors
• User name appears in header
• "Upload Document" button visible
• "Document Library" accessible
• No console errors (F12 > Console)

---

Test 1: Smart OCR

Purpose

Verify that PDF uploads process quickly with intelligent OCR that:

• Extracts native text first (2-3 seconds)
• Only OCRs pages with <50 characters
• Completes 100-page PDFs in <5 seconds (was 180 seconds)

Test 1.1: Simple PDF Upload

Steps:

1. Navigate to dashboard
2. Click "Upload Document" button
3. Select a PDF file (2-10 pages, native text)
4. Fill in metadata:
   • Title: "Test Manual - Smart OCR"
   • Document Type: "Owner Manual"
   • Category: "Manuals"
5. Click "Upload"
6. Start timer

Monitoring:

• Watch browser console (F12 > Console) for job creation
• Observe job status in progress bar
• Note time at each stage:
  • Upload start: : (should be instant)
  • Upload complete: : (depends on file size)
  • OCR start: : (should start immediately)
  • OCR complete: : (THIS IS KEY METRIC)

Pass Criteria:

• File uploads successfully
• Job ID appears in console
• Progress bar shows status
• OCR completes in < 5 seconds
• No errors in console
• Document appears in library
• Search results appear within 2 minutes

Example Console Output:

[NaviDocs] Upload started
[NaviDocs] Job created: job-uuid-12345
[NaviDocs] Polling job status...
[NaviDocs] Job progress: 10%
[NaviDocs] Job progress: 50%
[NaviDocs] Job progress: 100%
[NaviDocs] OCR complete in 4.2 seconds

Test 1.2: Large PDF with Mixed Text

Steps:

1. Upload a 100-page PDF with:
   • 50 pages with native text
   • 50 pages with scanned images only
2. Note file size: ______
3. Start timer
4. Monitor job progress

Expected Behavior:

• Upload: < 30 seconds
• Native text extraction: 2-3 seconds (50 pages)
• Scanned page OCR: 1-2 seconds (50 pages, fast path)
• Total: < 5 seconds

Pass Criteria:

• Total OCR time < 5 seconds
• All 100 pages indexed
• Search returns results from both native and OCR text
• No timeout errors
• No memory issues

Test 1.3: OCR Quality Check

Steps:

1. Open completed document in library
2. Click "View Document"
3. Check search accuracy

Search Test:

1. Go to Library > Search
2. Try these searches:
   • "engine" (should find technical manual content)
   • "warranty" (should find warranty sections)
   • "maintenance" (should find service records)

Pass Criteria:

• Search results accurate (not gibberish)
• Results show page numbers
• Text snippets are readable
• OCR confidence > 80%
• Language detection correct

Check OCR Confidence:

// In browser console:
// After document loads, check page data
console.log(document.__nuxt__.$data.documentPages)
// Look for ocrConfidence field (should be 0.8-0.95)

---

Test 2: Multi-Format Upload

Purpose

Verify that NaviDocs handles 6 different file types correctly:

1. PDF - Native + OCR
2. Images (JPG/PNG) - OCR only
3. Word (DOCX) - Text extraction
4. Excel (XLSX) - Data extraction
5. Text (TXT) - Direct read
6. Markdown (MD) - Direct read

Test 2.1: Upload All 6 File Types

Prepare Test Files: Create or locate these files:

Format	Filename	Content	Size
PDF	test-manual.pdf	5-10 page manual	< 10 MB
JPG	boat-photo.jpg	2-3 MB photo	< 5 MB
PNG	diagram.png	System diagram	< 2 MB
DOCX	specifications.docx	Boat specs	< 1 MB
XLSX	maintenance.xlsx	Service log	< 1 MB
TXT	notes.txt	Engine notes	< 100 KB

Upload Steps:

For each file:

1. Click "Upload Document"
2. Select file
3. Fill metadata:
   • Title: "[Type] - Test Document"
   • Type: Appropriate type
   • Category: Appropriate category
4. Click "Upload"
5. Record Upload Status
6. Record Processing Time

Pass Criteria for Each Format:

PDF:

• Uploads successfully
• OCR processes text
• Search finds content
• Pages extracted correctly
• Processing time < 5 seconds

JPG/PNG:

• Uploads successfully
• OCR processes image text
• Search finds content
• Image displays in preview
• Processing time < 3 seconds

DOCX:

• Uploads successfully
• Text extracted correctly
• Formatting preserved
• Search finds content
• Processing time < 2 seconds

XLSX:

• Uploads successfully
• Sheet data extracted
• All columns readable
• Search finds cell content
• Processing time < 2 seconds

TXT:

• Uploads successfully
• Full text indexed
• Search finds content
• Formatting preserved
• Processing time < 1 second

MD:

• Uploads successfully
• Markdown parsed correctly
• Headers and content separate
• Search finds content
• Processing time < 1 second

Test 2.2: Search Across All Formats

Steps:

1. Go to Library > Search
2. Search for content that appears in multiple formats
   • Example: "engine" (in manual, specifications, notes)
3. Record results

Pass Criteria:

• Returns results from all 6 formats
• Results grouped by document type
• Preview shows correct snippet
• No format-specific errors
• Results load < 100 ms

Test 2.3: Multi-Format Organization

Steps:

1. Go to Library
2. Filter by document type

Pass Criteria:

• Can filter by "PDF"
• Can filter by "Image"
• Can filter by "Word"
• Can filter by "Spreadsheet"
• Can filter by "Text"
• Filters work correctly
• No data loss

---

Test 3: Timeline Activity

Purpose

Verify that all document operations are logged with:

• Timestamps
• User attribution
• Operation type (upload/delete/share)
• Document metadata

Test 3.1: Upload Activity Logging

Steps:

1. Go to Dashboard > Timeline (or Activity Feed)
2. Upload 3 documents of different types:
   • Document A (PDF)
   • Document B (JPG)
   • Document C (DOCX)
3. Start timer for each upload
4. Check Timeline after each upload

Pass Criteria:

• Each upload appears in timeline
• Correct document name shown
• Correct file type icon shown
• Timestamp accurate (within 1 minute)
• User name correct
• "Upload" action labeled correctly
• Timeline updates within 2 seconds of upload complete

Example Timeline Entry:

[✓] PDFs uploaded: test-manual.pdf
    User: test-user-123
    Time: 2025-11-13 15:30:45 UTC
    Status: Indexed (searchable)
    [View Document] [Delete]

Test 3.2: Delete Activity Logging

Steps:

1. In Library, select one uploaded document
2. Click "Delete" button
3. Confirm deletion
4. Start timer
5. Check Timeline

Pass Criteria:

• Delete appears in timeline
• Shows "Document deleted" action
• Original filename visible
• Timestamp accurate
• User name correct
• Document removed from library
• Timeline updates within 2 seconds

Example Timeline Entry:

[✗] PDFs deleted: old-manual.pdf
    User: test-user-123
    Time: 2025-11-13 15:35:12 UTC
    [Undo Delete - 30 minute window]

Test 3.3: Timeline Filtering

Steps:

1. Go to Timeline
2. Upload 5-10 documents of mixed types
3. Delete 2-3 documents
4. Try filtering:
   • By action: "Uploads only"
   • By action: "Deletions only"
   • By date range: "Last 1 hour"
   • By document type: "PDFs only"

Pass Criteria:

• Filters work correctly
• Display updates instantly
• Correct counts shown
• Can combine filters
• No missing entries
• Sorting works (newest first)

Test 3.4: Timeline Performance

Steps:

1. Generate large timeline:
   • Upload 20-50 documents over 5 minutes
   • Delete 5-10 documents
2. Navigate to Timeline
3. Start timer for page load
4. Check performance metrics

Pass Criteria:

• Timeline loads in < 2 seconds
• Scrolling smooth (60 FPS)
• No memory leaks
• Search within timeline works
• Can export timeline (if feature exists)

---

Test Data Suggestions

Sample Files You Can Use

For Smart OCR Testing:

• Download sample boat manuals from:
  • Jeanneau official website (PDF manuals)
  • Sunseeker documentation
  • Generic marine equipment manuals
• Use these to test OCR quality

For Multi-Format Testing: Create minimal test files:

# Create sample files
mkdir -p /tmp/navidocs-test-files

# PDF (convert text to PDF)
echo "Engine maintenance schedule" > /tmp/navidocs-test-files/manual.txt
# Convert to PDF (requires tools): wkhtmltopdf manual.txt manual.pdf

# JPG (download sample image)
wget https://via.placeholder.com/640x480.jpg -O /tmp/navidocs-test-files/boat.jpg

# PNG (create diagram)
# Use GIMP or online tool to create simple system diagram

# DOCX (Word)
# Create in Microsoft Word or LibreOffice with boat specifications

# XLSX (Spreadsheet)
# Create maintenance log with columns:
# Date | Service | Cost | Technician | Notes

# TXT
echo "Engine service notes
Date: 2025-11-01
Oil change completed
Next service: 2025-12-01" > /tmp/navidocs-test-files/notes.txt

# MD
echo "# Boat Maintenance

## Engine
- Oil capacity: 15L
- Change interval: 100 hours

## Hull
- Last paint: 2024-06" > /tmp/navidocs-test-files/specs.md

Real Test Data (If Available)

Best case: Use actual boat documentation:

• Owner's manuals
• Service records
• Insurance documents
• Warranty certificates
• Photos with text overlays (for OCR testing)

---

Expected Results

Test 1: Smart OCR Expected Results

Metric	Expected	Acceptable	Failure
5-page PDF OCR	< 2 sec	< 3 sec	> 5 sec
50-page PDF OCR	< 3 sec	< 4 sec	> 8 sec
100-page PDF OCR	< 5 sec	< 6 sec	> 10 sec
OCR Confidence	85-95%	70-85%	< 70%
Search Latency	< 50 ms	< 100 ms	> 200 ms
Indexing Rate	> 20 pages/sec	> 15 pages/sec	< 10 pages/sec

Test 2: Multi-Format Expected Results

Format	Upload Time	Process Time	Search Latency
PDF	2-5 sec	2-5 sec	50-100 ms
JPG	1-3 sec	1-3 sec	50-100 ms
PNG	1-3 sec	1-3 sec	50-100 ms
DOCX	1-2 sec	<1 sec	50-100 ms
XLSX	1-2 sec	<1 sec	50-100 ms
TXT	<1 sec	<1 sec	50-100 ms

Test 3: Timeline Expected Results

Operation	Expected Latency	Update Delay	Data Accuracy
Upload logged	< 1 sec	< 2 sec	100%
Delete logged	< 1 sec	< 2 sec	100%
Timeline load	< 2 sec	-	100%
Search filter	< 100 ms	-	100%

---

Reporting Bugs

Bug Report Template

When you find a bug, use this format:

Title: [FEATURE] Brief description

• Example: "[Smart OCR] 100-page PDF times out after 45 seconds"

Environment:

• Browser: Chrome 130.0 / Firefox 131.0 / Safari 18.1
• OS: Windows 11 / macOS 14 / Ubuntu 24.04
• Screen Resolution: 1920x1080
• Network: Wired / WiFi with speed (Mbps)
• Time: 2025-11-13 15:30 UTC

Steps to Reproduce:

1. Navigate to [URL]
2. Click on [button]
3. Upload [file type], size [MB]
4. Observe [behavior]

Expected Behavior: [What should have happened]

Actual Behavior: [What actually happened]

Screenshots: [Attach images showing the issue]

Console Errors: [Copy full error stack trace from F12 > Console]

Performance Metrics:

• Upload time: X seconds
• OCR time: Y seconds
• Search latency: Z ms

Severity:

• 🔴 Critical: Feature completely broken
• 🟠 Major: Feature partially broken
• 🟡 Minor: Cosmetic or edge case
• 🟢 Suggestion: Enhancement

Attachments:

• Test file if applicable
• Network HAR file (F12 > Network > Export)
• Browser console log

Where to Report

1. GitHub Issues: https://github.com/dannystocker/navidocs/issues
2. Email: bugs@digital-lab.ca
3. Internal Slack: #navidocs-bugs

---

Troubleshooting

Upload Fails with "Invalid File Type"

Problem: File upload rejected immediately

Causes:

• File extension not supported
• MIME type mismatch
• File too large (>50 MB)

Solutions:

# Check file type
file test-file.pdf
# Should output: PDF document, version 1.4

# Check file size
ls -lh test-file.pdf
# Size should be < 50 MB

# Verify MIME type
# PDF: application/pdf
# JPG: image/jpeg
# PNG: image/png
# DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document
# XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

OCR Takes Too Long (>10 seconds for 100 pages)

Problem: Performance degradation

Potential Causes:

• Server CPU high
• Tesseract process stuck
• Redis queue backed up
• Database locks

Diagnosis:

# SSH to StackCP
ssh stackcp

# Check CPU usage
top -b -n 1 | head -20

# Check queue length
redis-cli LLEN bull:ocr-jobs:jobs

# Check disk space
df -h ~/navidocs-data/

# Check database locks
lsof 2>/dev/null | grep navidocs.db

Fixes:

1. Restart OCR worker: systemctl --user restart navidocs-ocr-worker
2. Clear stuck jobs: redis-cli DEL bull:ocr-jobs:*
3. Increase Tesseract threads: Edit .env TESSERACT_THREADS=4

Search Returns No Results

Problem: Indexed documents don't appear in search

Causes:

• Meilisearch service down
• Index not created
• Documents not yet indexed
• Tenant token expired

Diagnosis:

# Check Meilisearch health
curl http://localhost:7700/health

# Check index exists
curl http://localhost:7700/indexes

# Check document count
curl http://localhost:7700/indexes/navidocs-pages/stats

# Check search token
curl -X POST http://localhost:8001/api/search/token \
  -H "Content-Type: application/json" \
  -d '{"expiresIn": 3600}' | jq .

Fixes:

1. Restart Meilisearch: systemctl --user restart meilisearch
2. Reindex: npm run reindex (from server directory)
3. Clear bad token and regenerate

Timeline Not Updating

Problem: Activity feed shows stale data

Causes:

• Database transaction not committed
• Cache not invalidated
• WebSocket connection failed
• Job status not updated

Diagnosis:

# Check recent database entries
sqlite3 ~/navidocs-data/db/navidocs.db \
  "SELECT * FROM ocr_jobs ORDER BY created_at DESC LIMIT 5;"

# Check timestamps
sqlite3 ~/navidocs-data/db/navidocs.db \
  "SELECT id, status, updated_at FROM ocr_jobs LIMIT 5;"

Fixes:

1. Refresh page (F5)
2. Clear browser cache (Ctrl+Shift+R)
3. Restart server: systemctl --user restart navidocs
4. Rebuild timeline index

File Upload Stuck at 50%

Problem: Upload progress bar frozen

Causes:

• Network timeout
• Server crash
• Browser cache issue
• Large file size

Solutions:

1. Check network:

   # F12 > Network, check for failed requests
   # Green = success, Red = failed
   

2. Check file size:

   ls -lh file.pdf
   # If > 50 MB, file too large
   # Max: 50 MB
   

3. Clear browser cache:

   • Chrome: Ctrl+Shift+Delete
   • Firefox: Ctrl+Shift+Delete
   • Safari: Cmd+Option+E

4. Try again with smaller file:

   • If file > 20 MB, split into sections
   • Upload separately, then combine

Account/Login Issues

Problem: Cannot login or register

Causes:

• Database connection failed
• Password hash mismatch
• Session expired
• CSRF token invalid

Solutions:

# Check database is accessible
sqlite3 ~/navidocs-data/db/navidocs.db "SELECT * FROM users LIMIT 1;"

# Check user exists
sqlite3 ~/navidocs-data/db/navidocs.db \
  "SELECT id, email FROM users WHERE email='test@example.com';"

# Reset user password (if admin)
npm run reset-password test@example.com NewPassword123!

---

Performance Benchmarks

Expected Performance Metrics

Backend API:

• Health check: < 50 ms
• Token generation: 100-200 ms
• Upload: 1-3 seconds (depends on file size)
• Search: 50-100 ms
• Job status: 50-100 ms

Frontend:

• Page load: < 2 seconds
• Library render: < 1 second
• Search results: < 100 ms
• Upload dialog: < 500 ms
• Timeline load: < 2 seconds

Database:

• Query response: < 50 ms
• Index update: < 1 second
• Document insert: < 100 ms

Search Engine (Meilisearch):

• Index creation: < 100 ms
• Document insert: < 10 ms each
• Search query: 10-50 ms
• Faceted search: 50-100 ms

Load Testing

If you have access to tools like Apache Bench or wrk:

# Simulate 10 concurrent users
wrk -t4 -c10 -d30s https://digital-lab.ca/navidocs/

# Load test upload endpoint
# Note: Requires authentication token
# See API docs for token generation

# Expected results:
# - Should handle 100+ requests/sec
# - <1% error rate
# - <200 ms p95 latency

---

Sign-Off Checklist

After completing all tests, check these boxes:

Test 1: Smart OCR

• 5-page PDF: < 3 seconds
• 100-page PDF: < 5 seconds
• Search results accurate
• OCR confidence > 80%
• No timeout errors

Test 2: Multi-Format

• PDF: Upload & search works
• JPG: Upload & OCR works
• PNG: Upload & OCR works
• DOCX: Upload & extract works
• XLSX: Upload & parse works
• TXT: Upload & index works
• All formats searchable

Test 3: Timeline

• Uploads logged to timeline
• Deletes logged to timeline
• Timestamps accurate
• User attribution correct
• Filtering works
• Updates within 2 seconds

Overall

• No console errors
• No network failures
• No database errors
• Performance acceptable
• UX is smooth
• No data loss

Sign-Off

• Tester Name: _______________________
• Date: _______________________
• Status: 🟢 PASS / 🟡 PASS WITH ISSUES / 🔴 FAIL
• Notes: _______________________

---

Additional Resources

• API Documentation: /home/setup/navidocs/server/API_SUMMARY.md
• Architecture Guide: /home/setup/navidocs/DEPLOYMENT_ARCHITECTURE.md
• Developer Guide: /home/setup/navidocs/server/docs/README_ARCHITECTURE.md
• Deployment Guide: /home/setup/navidocs/DEPLOYMENT_INDEX.md

---

Contact & Support

Questions about testing?

• Email: test-team@digital-lab.ca
• Slack: #navidocs-testing
• GitHub Issues: https://github.com/dannystocker/navidocs/issues

Report bugs using the Bug Report Template above.

---

Document Version: 2025-11-13 Status: Ready for Live Testing Confidence Level: High

Good luck with testing! 🚀