Skip to content

🧪 Local Testing Guide

Test Documentation and Legal Features Locally

🚀 Quick Test (2 Commands)

Step 1: Start MkDocs Documentation Server

Open Terminal 1: 

mkdocs serve

Access at: http://localhost:8001

Step 2: Start Main Application

Open Terminal 2: 

.\start-all-servers-windowed.ps1

Access at: http://localhost:5180

✅ Testing Checklist

Test MkDocs Documentation (http://localhost:8001)

Open http://localhost:8001 in your browser:

  • Home page loads with MagicON AI branding
  • Complete User Guide link in navigation works
  • Search bar appears and works
  • Light/Dark mode toggle works (top right)
  • Navigation sidebar shows all sections
  • Complete User Guide shows all your content
  • Mobile responsive (resize browser window)

Tips: - Use search to find topics (e.g., search "alternatives") - Click "Complete User Guide" to see full USER_GUIDE.md content - Try dark mode toggle in header - Test on mobile (Chrome DevTools → Toggle device toolbar)

Open http://localhost:5180 in your browser:

A. Test Disclaimer (First Visit):

Clear storage first: 1. Press F12 (open developer console) 2. Type: localStorage.clear() 3. Press Enter 4. Press F5 (reload page)

Test: - [ ] Disclaimer modal appears automatically - [ ] Must scroll to bottom before "I Agree" enabled - [ ] Click "Terms of Service" link → Terms modal opens - [ ] Click "Third-Party Notices" link → Licenses modal opens - [ ] Click "I Agree" → Disclaimer closes and doesn't reappear

Scroll to bottom of page:

Documentation: - [ ] Click "Documentation" - [ ] Opens http://localhost:8001 in new tab - [ ] Shows MkDocs documentation home page

Support: - [ ] Click "Support" - [ ] Opens email client with support@pcbgenerator.com

Terms: - [ ] Click "Terms" button - [ ] Modal opens with Terms of Service - [ ] Can scroll and read content - [ ] Click X or outside to close - [ ] Click "User Guide" link → Opens localhost:8001

Privacy: - [ ] Click "Privacy" button - [ ] Modal opens with Privacy Policy - [ ] Shows data collection, GDPR compliance, etc. - [ ] Can close modal

Licenses: - [ ] Click "Licenses" button - [ ] Modal opens with Third-Party Licenses - [ ] Shows KiCad, component data, etc. - [ ] Can close modal

C. Test Nested Modals:

  1. Open app at http://localhost:5180
  2. Clear localStorage: localStorage.clear() in console
  3. Reload page → Disclaimer appears
  4. Click "Terms of Service" link in disclaimer
  5. Terms modal should open ON TOP of disclaimer
  6. Close Terms modal → Back to disclaimer
  7. Click "Third-Party Notices" link
  8. Licenses modal should open ON TOP of disclaimer
  9. Close Licenses modal → Back to disclaimer
  10. Click "I Agree"
  11. Disclaimer closes

Test Component Features:

In http://localhost:5180:

  1. Navigate to RF Module Designer tab
  2. Phase 1: Enter requirements (2.4 GHz, 30 dBm, WiFi)
  3. Click "Continue to Phase II"
  4. Phase 2: Enable AI component selection
  5. Wait for chain to generate
  6. Test Info Icons:
  7. Hover VCO info icon → Tooltip appears
  8. Hover Driver info icon → Tooltip appears
  9. Hover PA info icon → Tooltip appears
  10. Test Component Details:
  11. Click PA component
  12. See Specs, Reasoning, Alternatives tabs
  13. Check alternatives show pros/cons
  14. Expand "Scoring Details"

🔧 Troubleshooting

"MkDocs not found"

pip install mkdocs mkdocs-material

"Port 8001 already in use"

# Stop MkDocs
# Press Ctrl+C in the MkDocs terminal

# Or change port
mkdocs serve --dev-addr=localhost:8002
  • Make sure MkDocs server is running (http://localhost:8001)
  • Check browser console for errors
  • Try hard refresh (Ctrl + Shift + R)
  • Check browser console (F12) for errors
  • Verify LegalPageModal.tsx exists
  • Make sure Chakra UI Modal components are available

"Disclaimer doesn't show"

  1. Clear localStorage: localStorage.clear()
  2. Reload page
  3. Should appear immediately

"Changes not appearing"

  • MkDocs: Auto-reloads (just save file)
  • React app: Auto-reloads (just save file)
  • If stuck: Hard refresh (Ctrl + Shift + R)

📊 What's Running

When both servers are running:

Service Port URL Purpose
MkDocs Docs 8001 http://localhost:8001 Documentation preview
React Frontend 5180 http://localhost:5180 Main application
FastAPI Backend 8000 http://localhost:8000 API & exports

🎯 Quick Test

Start the docs preview and the app in separate terminals: 

# Terminal 1 — MkDocs docs preview (port 8001)
mkdocs serve -a localhost:8001

# Terminal 2 — main application (FastAPI 8000 + frontend 5180)
.\start-all-servers-windowed.ps1

Then open both URLs: - http://localhost:8001 (docs) - http://localhost:5180 (app)

💡 Pro Tips

  1. Use two browser tabs:
  2. Tab 1: http://localhost:8001 (docs)
  3. Tab 2: http://localhost:5180 (app)

  4. Test footer link jumps between them

  5. Use incognito for disclaimer:

  6. Regular tab: Already accepted disclaimer

  7. Incognito: Fresh session, shows disclaimer

  8. Console is your friend:

  9. F12 → Console tab
  10. localStorage.clear() → Reset disclaimer

  11. Check for any errors

  12. Live reload works:

  13. Edit any .md file in docs/
  14. MkDocs auto-reloads
  15. Edit any .tsx file
  16. React auto-reloads

✅ Ready to Test?

Run these in order:

  1. Terminal 1: 

    mkdocs serve
    Wait for: "Serving on http://localhost:8001/"

  2. Terminal 2: 

    .\start-all-servers-windowed.ps1
    Wait for: All servers started

  3. Browser:

  4. Visit http://localhost:5180
  5. Test legal modals (footer buttons)
  6. Click "Documentation" → Opens localhost:8001
  7. Test all features!

That's it! Everything testable in local development! 🎉

Using Claude Sonnet 4.5