mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-03-25 09:25:50 +00:00
docs: Create comprehensive external device testing guide
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 <noreply@anthropic.com>
This commit is contained in:
Jeff Hurray
Peter Steinberger
parent
d92a96e3bf
commit
9d0f29cf0c
1 changed files with 210 additions and 0 deletions
210
docs/TESTING_EXTERNAL_DEVICES.md
Normal file
210
docs/TESTING_EXTERNAL_DEVICES.md
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue