Updated copilot instructions
This commit is contained in:
parent
8caef2c3de
commit
ed8967f394
247
.github/copilot-instructions.md
vendored
247
.github/copilot-instructions.md
vendored
@ -1,5 +1,5 @@
|
||||
* Use 'docker compose' not 'docker-compose'
|
||||
* server, client, and voicebot directories always run in a conatiners with those names
|
||||
* 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'
|
||||
@ -8,3 +8,248 @@
|
||||
* 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=/shared:/voicebot` for voicebot, `PYTHONPATH=/shared:/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
|
||||
"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user