256 lines
8.0 KiB
Markdown
256 lines
8.0 KiB
Markdown
* Use 'docker compose' not 'docker-compose'
|
|
* server, client, and voicebot directories always run in containers with those names
|
|
* All tests created must be put in tests/, which is bind mounted into the containers in /tests.
|
|
* In client, to run any npm, npx, node, etc. you need to run via 'docker compose exec client COMMAND'
|
|
* In voicebot, to run any python code, you need to run via 'docker compose exec voicebot uv run COMMAND'
|
|
* In server, to run any python code, you need to run via 'docker compose exec server uv run COMMAND'
|
|
* Server runs HTTPS, self-signed (-k for curl). It is port 8001 on the host and port 8000 inside the docker container. public_url is set to /ai-voicebot, so URLs should be https://localhost:8001/ai-voicebot/... (from host) or https://server:8000/ai-voicebot/... (from inside docker).
|
|
* Voicebot runs HTTP. It is not exposed to the host and is connected to by server at http://voicebot:8788.
|
|
* All services use hot-load. Any time you change a file, the service will reload. This is not an error. Examination of logs should occur beginning with the messages after the most recent startup complete.
|
|
* All docker tail calls should be time relative, not message count relative. Eg., --since 10m not -n 100.
|
|
|
|
## Testing Instructions
|
|
|
|
### General Testing Guidelines
|
|
- Always run tests inside the appropriate Docker containers using `docker compose exec`
|
|
- Use `uv run` for Python commands in voicebot and server containers
|
|
- Tests should be placed in the `tests/` directory (bind mounted to `/tests` in containers)
|
|
- Use proper PYTHONPATH when running Python code: `PYTHONPATH=/:/voicebot` for voicebot, `PYTHONPATH=/:/server` for server
|
|
- Check container logs with `docker compose logs --since 10m SERVICE_NAME` for debugging
|
|
|
|
### Voicebot Testing (Python with uv)
|
|
|
|
#### Running Python Code in Voicebot Container
|
|
```bash
|
|
# Basic Python execution
|
|
docker compose exec voicebot uv run python3 -c "print('Hello from voicebot')"
|
|
|
|
# Running Python scripts with proper imports
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 script.py
|
|
"
|
|
|
|
# Running tests
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -m pytest /tests/ -v
|
|
"
|
|
|
|
# Interactive Python session
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3
|
|
"
|
|
```
|
|
|
|
#### Voicebot-Specific Testing Patterns
|
|
```bash
|
|
# Test bot configuration updates
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
from bots.minimal import create_minimal_bot_tracks, handle_config_update
|
|
tracks = create_minimal_bot_tracks('test_session', {'visualization': 'ball'})
|
|
success = handle_config_update('test_session', {'visualization': 'waveform'})
|
|
print(f'Config update success: {success}')
|
|
\"
|
|
"
|
|
|
|
# Test WebRTC signaling
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
from webrtc_signaling import WebRTCSignalingClient
|
|
# Test signaling client instantiation
|
|
\"
|
|
"
|
|
```
|
|
|
|
### Server Testing (Python with uv)
|
|
|
|
#### Running Python Code in Server Container
|
|
```bash
|
|
# Basic Python execution
|
|
docker compose exec server uv run python3 -c "print('Hello from server')"
|
|
|
|
# Running server scripts with proper imports
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3 script.py
|
|
"
|
|
|
|
# Running FastAPI server tests
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3 -m pytest /tests/ -v
|
|
"
|
|
|
|
# Interactive Python session
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3
|
|
"
|
|
```
|
|
|
|
#### Server-Specific Testing Patterns
|
|
```bash
|
|
# Test API endpoints
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
|
|
import requests
|
|
# Test internal API calls
|
|
response = requests.get('http://localhost:8000/health')
|
|
print(f'Health check: {response.status_code}')
|
|
\"
|
|
"
|
|
|
|
# Test WebSocket connections
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
|
|
from websocket.connection import WebSocketConnection
|
|
# Test WebSocket connection logic
|
|
\"
|
|
"
|
|
```
|
|
|
|
### Shared Module Testing
|
|
|
|
#### Testing Shared Modules from Voicebot
|
|
```bash
|
|
# Test shared modules from voicebot container
|
|
docker compose exec voicebot bash -c "
|
|
cd /shared && PYTHONPATH=/shared uv run python3 -c \"
|
|
from shared.logger import logger
|
|
from shared.models import ChatMessageModel
|
|
logger.info('Testing shared modules')
|
|
print('Shared modules imported successfully')
|
|
\"
|
|
"
|
|
|
|
# Run shared module tests
|
|
docker compose exec voicebot bash -c "
|
|
cd /shared && PYTHONPATH=/shared uv run python3 -m pytest /tests/test_shared/ -v
|
|
"
|
|
```
|
|
|
|
#### Testing Shared Modules from Server
|
|
```bash
|
|
# Test shared modules from server container
|
|
docker compose exec server bash -c "
|
|
cd /shared && PYTHONPATH=/shared uv run python3 -c \"
|
|
from shared.logger import logger
|
|
from shared.models import BotConfigSchema
|
|
logger.info('Testing shared modules from server')
|
|
print('Shared modules imported successfully')
|
|
\"
|
|
"
|
|
```
|
|
|
|
### Integration Testing
|
|
|
|
#### Cross-Service Testing
|
|
```bash
|
|
# Test voicebot-server communication
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
import requests
|
|
# Test connection to server
|
|
try:
|
|
response = requests.get('http://server:8000/health')
|
|
print(f'Server connection: {response.status_code}')
|
|
except Exception as e:
|
|
print(f'Connection failed: {e}')
|
|
\"
|
|
"
|
|
|
|
# Test server-voicebot communication
|
|
docker compose exec server bash -c "
|
|
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
|
|
import requests
|
|
# Test connection to voicebot
|
|
try:
|
|
response = requests.get('http://voicebot:8788/health')
|
|
print(f'Voicebot connection: {response.status_code}')
|
|
except Exception as e:
|
|
print(f'Connection failed: {e}')
|
|
\"
|
|
"
|
|
```
|
|
|
|
### Debugging and Logging
|
|
|
|
#### Container Logs
|
|
```bash
|
|
# View recent logs for all services
|
|
docker compose logs --since 10m
|
|
|
|
# View logs for specific service
|
|
docker compose logs --since 10m voicebot
|
|
docker compose logs --since 10m server
|
|
docker compose logs --since 10m client
|
|
|
|
# Follow logs in real-time
|
|
docker compose logs -f voicebot
|
|
```
|
|
|
|
#### Debugging Python Code
|
|
```bash
|
|
# Run with debug output
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
import logging
|
|
logging.basicConfig(level=logging.DEBUG)
|
|
# Your debug code here
|
|
\"
|
|
"
|
|
|
|
# Check Python path and imports
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
import sys
|
|
print('Python path:', sys.path)
|
|
import shared.logger
|
|
print('Shared logger imported successfully')
|
|
\"
|
|
"
|
|
```
|
|
|
|
### Best Practices
|
|
|
|
1. **Always use proper PYTHONPATH**: Include `/shared` and the service directory
|
|
2. **Test in containers**: Never run Python code directly on host - always use `docker compose exec`
|
|
3. **Use uv run**: Always prefix Python commands with `uv run` in voicebot and server
|
|
4. **Check logs**: Use `docker compose logs --since 10m` for debugging
|
|
5. **Hot reload**: Services reload automatically on file changes - wait for reload messages
|
|
6. **Test isolation**: Use unique identifiers for test sessions to avoid conflicts
|
|
7. **Network calls**: Use service names (server, voicebot) for internal communication
|
|
8. **Dependencies**: All Python dependencies are managed via uv - don't use pip directly
|
|
|
|
### Common Issues and Solutions
|
|
|
|
#### Import Errors
|
|
```bash
|
|
# If shared modules can't be imported
|
|
docker compose exec voicebot bash -c "
|
|
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
|
|
import sys
|
|
sys.path.insert(0, '/shared')
|
|
from shared.logger import logger
|
|
print('Import successful')
|
|
\"
|
|
"
|
|
```
|
|
|
|
#### Module Not Found
|
|
```bash
|
|
# Check if modules exist and PYTHONPATH is correct
|
|
docker compose exec voicebot bash -c "
|
|
ls -la /shared/
|
|
echo 'PYTHONPATH=/shared:/voicebot'
|
|
PYTHONPATH=/shared:/voicebot uv run python3 -c 'import shared.logger'
|
|
"
|
|
```
|
|
|
|
#### Container Connection Issues
|
|
```bash
|
|
# Check container status
|
|
docker compose ps
|
|
|
|
# Restart services if needed
|
|
docker compose restart voicebot
|
|
docker compose restart server
|
|
"
|