From 9d0f29cf0cb8b2ad48824262d75b2adb2a458097 Mon Sep 17 00:00:00 2001 From: Jeff Hurray Date: Tue, 1 Jul 2025 00:07:11 -1000 Subject: [PATCH] docs: Create comprehensive external device testing guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added detailed documentation for testing VibeTunnel on external devices, including setup instructions, troubleshooting, security considerations, and best practices for cross-device development. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/TESTING_EXTERNAL_DEVICES.md | 210 +++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 docs/TESTING_EXTERNAL_DEVICES.md diff --git a/docs/TESTING_EXTERNAL_DEVICES.md b/docs/TESTING_EXTERNAL_DEVICES.md new file mode 100644 index 00000000..f0f18749 --- /dev/null +++ b/docs/TESTING_EXTERNAL_DEVICES.md @@ -0,0 +1,210 @@ +# Testing VibeTunnel on External Devices + +This guide explains how to test VibeTunnel development changes on external devices like iPads, iPhones, and other computers. + +## Overview + +When developing VibeTunnel's web interface, you may encounter browser-specific issues that only appear on certain devices (e.g., Safari on iPad). This guide shows you how to test your local development changes on these devices without deploying. + +## Quick Start: Development Server Method + +This is the recommended approach for rapid iteration during development. + +### 1. Start the Development Server + +```bash +cd web +pnpm run dev --port 4021 --bind 0.0.0.0 +``` + +**Key parameters:** +- `--port 4021`: Use a different port than the production server (4020) +- `--bind 0.0.0.0`: Bind to all network interfaces (not just localhost) + +### 2. Find Your Mac's IP Address + +**Option A: System Preferences** +1. Open System Preferences → Network +2. Select Wi-Fi → Advanced → TCP/IP +3. Look for "IPv4 Address" + +**Option B: Terminal** +```bash +# For Wi-Fi connection +ipconfig getifaddr en0 + +# For Ethernet connection +ipconfig getifaddr en1 +``` + +### 3. Access from External Device + +Open a browser on your external device and navigate to: +``` +http://[your-mac-ip]:4021 +``` + +Example: `http://192.168.1.42:4021` + +## Production Build Method + +Use this method when you need to test with the full Mac app integration. + +### 1. Build the Web Project + +```bash +cd web +pnpm run build +``` + +### 2. Configure VibeTunnel for Network Access + +1. Open VibeTunnel from the menu bar +2. Go to Settings → Dashboard Access +3. Select "Network" mode +4. Set a dashboard password (required for network access) + +### 3. Access from External Device + +``` +http://[your-mac-ip]:4020 +``` + +## Common Issues and Solutions + +### Cannot Connect from External Device + +**Check network connectivity:** +- Ensure both devices are on the same Wi-Fi network +- Verify the IP address is correct +- Try pinging your Mac from the external device + +**Check firewall settings:** +- macOS may block incoming connections +- When prompted, click "Allow" for Node.js/Bun +- Check System Preferences → Security & Privacy → Firewall + +**Verify server is running:** +```bash +# Check if the port is listening +lsof -i :4021 +``` + +### Changes Not Appearing + +**For development server:** +- Hot reload should work automatically +- Try hard refresh on the external device (Cmd+Shift+R on Safari) +- Check the terminal for build errors + +**For production build:** +- You must rebuild after each change: `pnpm run build` +- Restart the VibeTunnel server after building +- Clear browser cache on the external device + +### Safari-Specific Issues + +**Enable Developer Mode on iOS/iPadOS:** +1. Settings → Safari → Advanced → Web Inspector (ON) +2. Connect device to Mac via USB +3. Open Safari on Mac → Develop menu → [Your Device] +4. Select the page to inspect + +**Common Safari quirks:** +- Different touch event handling +- Stricter security policies +- Different viewport behavior +- WebSocket connection issues + +## Advanced Testing Scenarios + +### Testing with HTTPS + +Some features may require HTTPS. Use ngrok for secure tunneling: + +```bash +# Install ngrok +brew install ngrok + +# Create tunnel to dev server +ngrok http 4021 +``` + +### Testing Different Network Conditions + +Use Chrome DevTools or Safari Web Inspector to simulate: +- Slow network connections +- Offline mode +- Different device viewports + +### Multi-Device Testing + +Test on multiple devices simultaneously: +```bash +# Terminal 1: Development server +pnpm run dev --port 4021 --bind 0.0.0.0 + +# Terminal 2: Production server (if needed) +# VibeTunnel app handles this automatically +``` + +## Security Considerations + +**Development only:** +- Only use `--bind 0.0.0.0` on trusted networks +- The dev server has no authentication +- Consider using a firewall to restrict access + +**Production testing:** +- Always set a dashboard password +- Use Tailscale or ngrok for remote access +- Never expose unprotected servers to the internet + +## Debugging Tips + +### Console Access on Mobile + +**Safari on iOS/iPadOS:** +1. Enable Web Inspector (see above) +2. Connect device to Mac +3. Use Safari Developer Tools + +**Chrome on Android:** +1. Enable Developer Options +2. Connect via USB +3. Open chrome://inspect on desktop Chrome + +### Network Debugging + +Monitor network requests: +```bash +# Watch incoming connections +sudo lsof -i -P | grep LISTEN | grep 4021 + +# Monitor HTTP traffic +sudo tcpdump -i en0 port 4021 +``` + +### Performance Profiling + +Use browser developer tools to: +- Profile JavaScript performance +- Analyze rendering bottlenecks +- Check memory usage +- Monitor WebSocket traffic + +## Best Practices + +1. **Always test on real devices** - Emulators don't catch all issues +2. **Test on multiple browsers** - Safari, Chrome, Firefox behave differently +3. **Check different orientations** - Portrait and landscape modes +4. **Test with poor network** - Not everyone has fast Wi-Fi +5. **Verify touch interactions** - Mouse events ≠ touch events +6. **Check responsive design** - Different screen sizes and resolutions + +## Related Documentation + +- [README.md](../README.md) - General setup and usage +- [CONTRIBUTING.md](CONTRIBUTING.md) - Development workflow +- [spec.md](spec.md) - Technical specification +- [architecture.md](architecture.md) - System architecture \ No newline at end of file