# Telegram Integration Testing Guide
This guide covers testing the Telegram channel integration for ZeroClaw.
## 🚀 Quick Start
### Automated Tests
```bash
# Full test suite (20+ tests, ~2 minutes)
./test_telegram_integration.sh
# Quick smoke test (~10 seconds)
./quick_test.sh
# Just unit tests
cargo test telegram --lib
```
## 📋 Test Coverage
### Automated Tests (20 tests)
The `test_telegram_integration.sh` script runs:
**Phase 1: Code Quality (5 tests)**
- ✅ Test compilation
- ✅ Unit tests (24 tests)
- ✅ Message splitting tests (8 tests)
- ✅ Clippy linting
- ✅ Code formatting
**Phase 2: Build Tests (3 tests)**
- ✅ Debug build
- ✅ Release build
- ✅ Binary size verification (<10MB)
**Phase 3: Configuration Tests (4 tests)**
- ✅ Config file exists
- ✅ Telegram section configured
- ✅ Bot token set
- ✅ User allowlist configured
**Phase 4: Health Check Tests (2 tests)**
- ✅ Health check timeout (<5s)
- ✅ Telegram API connectivity
**Phase 5: Feature Validation (6 tests)**
- ✅ Message splitting function
- ✅ Message length constant (4096)
- ✅ Timeout implementation
- ✅ chat_id validation
- ✅ Duration import
- ✅ Continuation markers
### Manual Tests (6 tests)
After running automated tests, perform these manual checks:
1. **Basic messaging**
```bash
zeroclaw channel start
```
- Send "Hello bot!" in Telegram
- Verify response within 3 seconds
2. **Long message splitting**
```bash
python3 -c 'print("test " * 1000)'
```
- Paste into Telegram
- Verify: Message split into chunks
- Verify: Markers show `(continues...)` and `(continued)`
- Verify: All chunks arrive in order
3. **Unauthorized user blocking**
```toml
# Edit ~/.zeroclaw/config.toml
allowed_users = ["999999999"]
```
- Send message to bot
- Verify: Warning in logs
- Verify: Message ignored
- Restore correct user ID
4. **Rate limiting**
- Send 10 messages rapidly
- Verify: All processed
- Verify: No "Too Many Requests" errors
- Verify: Responses have delays
5. **Mention-only mode (group chats)**
```toml
# Edit ~/.zeroclaw/config.toml
[channels.telegram]
mention_only = true
```
- Add bot to a group chat
- Send message without @botname mention
- Verify: Bot does not respond
- Send message with @botname mention
- Verify: Bot responds and mention is stripped
- DM/private chat should always work regardless of mention_only
6. **Error logging**
```bash
RUST_LOG=debug zeroclaw channel start
```
- Check for unexpected errors
- Verify proper error handling
6. **Health check timeout**
```bash
time zeroclaw channel doctor
```
- Verify: Completes in <5 seconds
## 🔍 Test Results Interpretation
### Success Criteria
- All 20 automated tests pass ✅
- Health check completes in <5s ✅
- Binary size <10MB ✅
- No clippy warnings ✅
- All manual tests pass ✅
### Common Issues
**Issue: Health check times out**
```
Solution: Check bot token is valid
curl "https://api.telegram.org/bot<TOKEN>/getMe"
```
**Issue: Bot doesn't respond**
```
Solution: Check user allowlist
1. Send message to bot
2. Check logs for user_id
3. Update config: allowed_users = ["YOUR_ID"]
4. Run: zeroclaw onboard --channels-only
```
**Issue: Message splitting not working**
```
Solution: Verify code changes
grep -n "split_message_for_telegram" src/channels/telegram.rs
grep -n "TELEGRAM_MAX_MESSAGE_LENGTH" src/channels/telegram.rs
```
## 🧪 Test Scenarios
### Scenario 1: First-Time Setup
```bash
# 1. Run automated tests
./test_telegram_integration.sh
# 2. Configure Telegram
zeroclaw onboard --interactive
# Select Telegram channel
# Enter bot token (from @BotFather)
# Enter your user ID
# 3. Verify health
zeroclaw channel doctor
# 4. Start channel
zeroclaw channel start
# 5. Send test message in Telegram
```
### Scenario 2: After Code Changes
```bash
# 1. Quick validation
./quick_test.sh
# 2. Full test suite
./test_telegram_integration.sh
# 3. Manual smoke test
zeroclaw channel start
# Send message in Telegram
```
### Scenario 3: Production Deployment
```bash
# 1. Full test suite
./test_telegram_integration.sh
# 2. Load test (optional)
# Send 100 messages rapidly
for i in {1..100}; do
-d "chat_id=<CHAT_ID>" \
-d "text=Message $i"
done
# 3. Monitor logs
RUST_LOG=info zeroclaw daemon
# 4. Check metrics
zeroclaw status
```
## 📊 Performance Benchmarks
Expected values after all fixes:
| Health check time | <5s | `time zeroclaw channel doctor` |
| First response time | <3s | Time from sending to receiving |
| Message split overhead | <50ms | Check logs for timing |
| Memory usage | <10MB | `ps aux \| grep zeroclaw` |
| Binary size | ~3-4MB | `ls -lh target/release/zeroclaw` |
| Unit test coverage | 61/61 pass | `cargo test telegram --lib` |
## 🐛 Debugging Failed Tests
### Debug Unit Tests
```bash
# Verbose output
cargo test telegram --lib -- --nocapture
# Specific test
cargo test telegram_split_over_limit -- --nocapture
# Show ignored tests
cargo test telegram --lib -- --ignored
```
### Debug Integration Issues
```bash
# Maximum logging
RUST_LOG=trace zeroclaw channel start
# Check Telegram API directly
curl "https://api.telegram.org/bot<TOKEN>/getMe"
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
# Validate config
Add to your CI pipeline:
```yaml
# .github/workflows/test.yml
name: Test Telegram Integration
on: [push, pull_request]
jobs:
test:
runs-on: blacksmith-2vcpu-ubuntu-2404
steps:
- uses: actions/checkout@v3
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
- name: Run tests
run: |
cargo test telegram --lib
cargo clippy --all-targets -- -D warnings
- name: Check formatting
run: cargo fmt --check
```
## 📝 Test Checklist
Before merging code:
- [ ] `./quick_test.sh` passes
- [ ] `./test_telegram_integration.sh` passes
- [ ] Manual tests completed
- [ ] No new clippy warnings
- [ ] Code is formatted (`cargo fmt`)
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
## 🚨 Emergency Rollback
If tests fail in production:
```bash
# 1. Check git history
git log --oneline src/channels/telegram.rs
# 2. Rollback to previous version
git revert <commit-hash>
# 3. Rebuild
cargo build --release
# 4. Restart service
zeroclaw service restart
# 5. Verify
zeroclaw channel doctor
```
## 📚 Additional Resources
- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
- [ZeroClaw Main README](README.md)
- [Contributing Guide](CONTRIBUTING.md)
- [Issue Tracker](https://github.com/theonlyhennygod/zeroclaw/issues)
